Remote Protocol
Remote Administration connects an operator console, or a one-shot command, to a running process. This page describes what travels on that connection, for those who write a client of their own: a monitoring probe in another language, a custom terminal, a test harness. The .NET client, RemoteReplClient, already implements everything below.
Layers
Section titled “Layers”The envelope is JSON-RPC 2.0. Discovery uses OpenRPC, with JSON Schema Draft 7 for parameter values. No service provider, CLR type name or serialized exception is part of the wire contract, so a client needs no .NET type from the server.
The protocol package, Repl.Remote, references neither Repl.Core nor Repl.Defaults. On the server side, IRemoteReplBackend is the boundary: Repl.Remote.Defaults implements it with ReplAppRemoteBackend for a ReplApp, and another engine can implement it without changing clients, framing or messages.
Framing
Section titled “Framing”Messages are framed on the stream the way the Language Server Protocol frames them: an ASCII Content-Length: <bytes> header, a blank line (\r\n\r\n), then the JSON body. The length counts UTF-8 bytes, not characters. This is stream framing, not HTTP.
The supplied listener is a named pipe; RemoteReplServer.RunAsync serves any pair of streams you supply instead, including redirected standard input and output.
Methods
Section titled “Methods”| Method | Direction | Purpose |
|---|---|---|
rpc.discover | Client → server | The OpenRPC document, with the profile version and capabilities |
cli.describe | Client → server | Contexts, canonical routes, aliases and parameter schemas |
cli.execute | Client → server | Run one command; returns its outcome, exit code, JSON result, stdout and stderr |
terminal.open | Client → server | Start a terminal session with a client-chosen sessionId and initial metadata |
terminal.input | Client → server | Text and VT sequences, at most 16,384 UTF-16 code units per call |
terminal.resize | Client → server | New column and row counts, both positive |
terminal.interrupt | Client → server | Cancel the active command and keep the session |
terminal.close | Client → server | Cancel and close the session |
terminal.output | Server notification | Text and VT sequences for a sessionId |
terminal.exited | Server notification | The session’s exit code, once its output has drained |
$/cancelRequest | Notification | Cancel a pending request by its JSON-RPC id |
Parameters are passed by name. The authoritative description is openrpc.json, which rpc.discover returns.
One command
Section titled “One command”rpc.discover returns the OpenRPC document. Its x-cli member carries the profile version, the capabilities (describe, execute, terminal, cancel), the framing and the schema dialect. The profile version is separate from the document’s own info.version.
cli.describe returns the command graph that discovery shows: hidden commands are left out, and explicit service parameters are omitted. Hidden commands remain invocable, so hiding is not authorization.
cli.execute takes exactly one representation of the command. Either already-separated tokens, as a shell would pass them:
{ "arguments": ["items", "show", "42"] }or a canonical route from cli.describe, with values keyed by canonical parameter names:
{ "command": "items show {id}", "values": { "id": 42 }, "globalValues": { "tenant": "demo" }}values and globalValues require command. Shell expansion and quoting stay on the client side. JSON arrays and objects bind as native values.
The response is a RemoteExecutionResult. A command that fails still answers successfully at the RPC level: read kind, the execution outcome in camelCase (success, usageError, help…), and exitCode. result holds the rendered JSON, an array when the command produced several results; standardOutput and standardError hold the text the handler wrote through its injected I/O. ReplAppRemoteBackend forces JSON output and never enters interactive mode for cli.execute; another backend may choose differently. An empty invocation returns the help outcome, with human-readable help in standardOutput.
A terminal session
Section titled “A terminal session”The client chooses the sessionId and passes initial options: terminal type, columns, rows and ansi. Output arrives as terminal.output notifications at any time; consume them continuously. The server queues a bounded amount of output for each session, and a session that cannot write its output fails with exit code 1. The .NET RemoteTerminal also disconnects when its own buffer overflows. The responses to terminal.input, terminal.resize and terminal.interrupt are empty and left out of the drawing.
terminal.interrupt cancels the command that is running and leaves the session at its prompt. terminal.close cancels the session and answers once it has finished. A session that ends by cancellation reports 130; one whose backend failed reports 1.
Connections and errors
Section titled “Connections and errors”A connection runs one execution or one terminal at a time. Open several connections to run commands concurrently.
| Code | Meaning |
|---|---|
-32602 | Invalid parameters: both or neither of arguments and command, an empty command, values sent with arguments, an empty sessionId or terminal type on terminal.open, an oversized input chunk, a non-positive size |
-32001 | Busy: this connection already owns an execution or a terminal |
-32002 | No active terminal with this sessionId on this connection, including an empty one |
-32603 | ”The remote backend failed.” The detail goes to the server’s onError callback, never to the client |
Cancellation and retries
Section titled “Cancellation and retries”$/cancelRequest cancels a pending request by its id. It is a JSON-RPC ecosystem convention, not part of the 2.0 specification. Cancellation is cooperative: the handler receives a cancelled token, but nothing proves it stopped. A request the server abandons answers with a JSON-RPC error that acknowledges the cancellation; a handler that finishes anyway returns its normal result. Closing the connection cancels its work in the same way.
Never retry a cli.execute automatically after a transport failure: the command may already have run even though its response was lost.
Security and limits
Section titled “Security and limits”- The supplied listener opens its pipe with
PipeOptions.CurrentUserOnlyon both ends, so only the same OS account connects. Any process running as that account can run any command, hidden ones included. On Windows, client and server also need compatible elevation. On Unix, .NET implements the pipe with a Unix-domain socket, and clients use the logical pipe name rather than a socket path. - Terminal output contains VT sequences that the application controls. A custom terminal decides which ones it honours.
cli.executecaptures its output in memory. The endpoint suits administrative commands, not bulk data transfer or untrusted traffic.
Further reading
Section titled “Further reading”- Remote Administration — serve a running application and connect to it from .NET.
- Remote CLI and local administration — the repository’s description of the wire profile, stream ownership and shutdown.
openrpc.json— methods and schemas.RemoteProtocol— the profile version and the OpenRPC document in .NET.