Skip to content

Remote Administration

A long-running service still needs an operator. Repl.Remote lets one attach a console to the process that is already running, or ask it to run a single command and return its exit code. The command runs inside the live process, against the same services, so settings show reads the settings the service is actually using, without a restart or a second instance.

Running process container or service Application services ReplApp, singletons, hosted services NamedPipeReplServer ReplAppRemoteBackend, onError Console attach RemoteConsole One-shot command health → exit code same machine, same OS account
An operator on the same machine attaches a console, or runs one command, over the named pipe.

Both put a Repl session somewhere other than the app’s own console, but they serve different people:

Hosted sessionsRemote administration
PackagesRepl.WebSocket, Repl.TelnetRepl.Remote, Repl.Remote.Defaults
Who connectsUsers of the app, over the networkA trusted operator on the same machine, same OS account
TransportWebSocket, Telnet, any stream pairNamed pipe (PipeOptions.CurrentUserOnly), or streams you supply
One-shot command with an exit codeNoYes, cli.execute
Typical useA REPL in a browser, a shared multi-user consoleHealth probes, maintenance, live inspection inside a container

MCP is a third, separate surface: it exposes selected tools to AI agents. The administration endpoint exposes the application’s command surface to operators.

Nothing listens unless the application starts an endpoint. Upgrading Repl or Repl.Defaults does not add one, and referencing the remote packages alone starts nothing. Repl.Remote.Defaults connects a ReplApp and brings in Repl.Remote; see Packages for what each one holds.

Terminal window
dotnet add package Repl.Remote.Defaults

The application creates a NamedPipeReplServer next to its host. Each connection gets a backend; here it borrows the existing ReplApp and the host’s service provider, so singletons are shared with the running service:

using Repl;
using Repl.Remote;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRepl((services, app) =>
{
app.UseEmbeddedConsoleProfile();
app.Map("health", () => new { status = "ready" });
});
await using var host = builder.Build();
var app = host.Services.GetRequiredService<ReplApp>();
var remote = new NamedPipeReplServer("my-app",
_ => ValueTask.FromResult<IRemoteReplBackend>(
new ReplAppRemoteBackend(app, host.Services)),
error => host.Logger.LogError(error, "Remote CLI failure"));
try
{
await host.StartAsync();
var stopping = Task.Delay(Timeout.InfiniteTimeSpan, host.Lifetime.ApplicationStopping);
if (await Task.WhenAny(stopping, remote.Completion) == remote.Completion)
{
await remote.Completion; // rethrows the fault that stopped the endpoint
}
}
finally
{
host.Lifetime.StopApplication();
try
{
await remote.DisposeAsync();
}
catch (TimeoutException error)
{
// Remote commands still run on the host's services: never stop or dispose them underneath.
host.Logger.LogCritical(error, "Remote commands did not drain; terminating.");
Environment.Exit(1); // skips the finally below and the host's disposal
}
finally
{
await host.StopAsync();
}
}

Three details in this code matter in production:

  • The third argument, onError, is where failures go. A client only ever sees “The remote backend failed.” (-32603) or a terminal that exits 1. The exception itself reaches onError; without a callback it goes to System.Diagnostics.Trace, which no default logging provider reads.
  • Watch remote.Completion. It faults when the endpoint stops accepting connections, so the host can stop instead of running on without its administration endpoint.
  • Dispose the listener before stopping the host. Remote work drains first, while the services it uses are still alive. Disposal waits at most five seconds; when it times out, commands are still running and the listener keeps cleaning up in the background, so stopping or disposing the host would pull services from under them. The example ends the process before that happens; sample 05 applies a similar fatal policy to its whole shutdown. A logger that writes on a background thread can lose that last line, so also write it to standard error if it must survive. Choose the policy your application needs.

The framework does not add --remote-console or --remote-exec switches to your executable. The hosting program chooses client mode itself, before it builds a host, as sample 05 does. A client connects, discovers, and executes:

using var deadline = new CancellationTokenSource(TimeSpan.FromSeconds(5));
await using var client = await NamedPipeReplServer.ConnectAsync("my-app", deadline.Token);
await client.DiscoverAsync(deadline.Token);
var result = await client.ExecuteAsync(
new RemoteInvocationRequest { Arguments = ["health"] },
deadline.Token);
return result.ExitCode;

A RemoteExecutionResult carries the outcome Kind, the ExitCode chosen by the application’s exit-code policy, the JSON Result, and the text written to StandardOutput and StandardError. Check ExitCode even when the call itself succeeds.

For an interactive session, hand the client to RemoteConsole: await RemoteConsole.RunAsync(client, ct). Ctrl+C interrupts the remote command, and Ctrl+D detaches without stopping the server.

Sample 05 ships a Dockerfile. Its health check and its operator console are both remote clients of the running process, so neither needs a shell or curl in the image:

  1. Build and start the service, from the repository root:

    Terminal window
    docker build -f samples/05-hosting-remote/Dockerfile -t repl-hosting-remote .
    docker run -d --name repl-hosting-remote -p 127.0.0.1:8080:8080 repl-hosting-remote
  2. Probe it without a TTY. health --liveness exits 0 while the host is up; health also fails during maintenance, which makes it a readiness probe:

    Terminal window
    docker exec repl-hosting-remote dotnet /app/HostingRemoteSample.dll --remote-exec repl-hosting-sample health --liveness
  3. Attach a console to the same process, and change shared state live:

    Terminal window
    docker exec -it repl-hosting-remote dotnet /app/HostingRemoteSample.dll --remote-console repl-hosting-sample

A real readiness command should check what the service needs to do its work, such as a database or a warmed cache, and return a failing exit code otherwise. The repository’s container hosting recipe also covers logs, the shutdown budget and a Portainer console.

  • One connection runs one execution or one terminal at a time; separate connections run concurrently, so shared state must be thread-safe.
  • One-shot output is captured in memory. The endpoint suits administrative commands, not bulk data transfer.
  • A transport failure is never retried automatically: the command may already have run.