Skip to content

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.

client process RemoteConsole Ctrl+C interrupts, Ctrl+D detaches RemoteReplClient discover, describe, execute server process ReplAppRemoteBackend Repl.Remote.Defaults, your ReplApp RemoteReplServer calls IRemoteReplBackend JSON-RPC 2.0 requests, responses, notifications Content-Length framing ASCII header, then a UTF-8 JSON body Byte stream a same-user named pipe, or streams you supply
Client and server share only the wire: JSON-RPC messages, framed on a byte stream. Neither side sees the other's types.

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.

Content-Length: 48\r\n\r\n {"jsonrpc":"2.0","id":1,"method":"cli.describe"} next frame header ASCII, ends with a blank line body: 48 bytes UTF-8 JSON; count bytes, not characters
The two parts of one message on the stream, and what the header's number counts.

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.

MethodDirectionPurpose
rpc.discoverClient → serverThe OpenRPC document, with the profile version and capabilities
cli.describeClient → serverContexts, canonical routes, aliases and parameter schemas
cli.executeClient → serverRun one command; returns its outcome, exit code, JSON result, stdout and stderr
terminal.openClient → serverStart a terminal session with a client-chosen sessionId and initial metadata
terminal.inputClient → serverText and VT sequences, at most 16,384 UTF-16 code units per call
terminal.resizeClient → serverNew column and row counts, both positive
terminal.interruptClient → serverCancel the active command and keep the session
terminal.closeClient → serverCancel and close the session
terminal.outputServer notificationText and VT sequences for a sessionId
terminal.exitedServer notificationThe session’s exit code, once its output has drained
$/cancelRequestNotificationCancel a pending request by its JSON-RPC id

Parameters are passed by name. The authoritative description is openrpc.json, which rpc.discover returns.

Client probe, script, console Server the running process rpc.discover request OpenRPC document, x-cli version, capabilities response cli.describe request contexts, commands, parameter schemas response cli.execute {"arguments":["health"]} request kind, exitCode, result, stdout, stderr response
A one-shot call: check the profile, read the command graph, then execute once.

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.

Client RemoteConsole, or yours Server interactive session terminal.open {"sessionId":"t1",...} request null: the session started response terminal.input "client list\r" request terminal.output "Alice\r\nBob\r\n..." notification terminal.close request terminal.exited {"sessionId":"t1","exitCode":...} notification null: the session is closed response
Which side starts each message of a terminal session, and in what order the exit code and the close response arrive.

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.

A connection runs one execution or one terminal at a time. Open several connections to run commands concurrently.

CodeMeaning
-32602Invalid 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
-32001Busy: this connection already owns an execution or a terminal
-32002No 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

$/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.

  • The supplied listener opens its pipe with PipeOptions.CurrentUserOnly on 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.execute captures its output in memory. The endpoint suits administrative commands, not bulk data transfer or untrusted traffic.