Skip to main content
RPC is a session’s in-app API over JSON-RPC 2.0. Each method is named after the call it makes: shell is session.shell, vfs/read is session.vfs.read. Use it when a program drives the workspace and needs exact bytes, with stdout, stderr and the exit code apart. Every workspace on the Mirage server answers RPC at:

Connect

These examples use the demo workspace from the CLI quickstart.
mirage rpc reads one message per line on stdin and writes one answer per line on stdout. It starts the server if needed and sends your token.
Both answer:
Answers come back as calls finish, so match them by id.

Auth

RPC uses the same bearer token as HTTP. mirage rpc sends the CLI’s token for you: a saved login, MIRAGE_TOKEN, or the local token file. A client that posts to the URL sends the header itself.

Methods

  • ? marks an optional param.
  • initialize is optional and creates nothing: it reports the server, and the workspace and session the connection uses.
  • vfs/<call> is each of the 23 VFS calls, with the same arguments and results as HTTP. The tools take the inputs listed on the MCP page.
  • explain: true on shell or vfs/<call> says what it would do and runs nothing; see Explain.
  • Bytes, stdin included, are base64 strings. A message is at most 4 MiB, so send larger stdin over HTTP or SSH.
  • A line that exits non-zero is a result, not an error.

Sessions

Calls run in the workspace’s default session. To use another, add ?session_id=<id> to the URL, or -s <id> to mirage rpc. The session’s session profile applies to every method.

Cancel

Send the notification $/cancelRequest with the id of a running request. That request answers -32800, and its job ends canceled. A dropped HTTP request cancels its calls too.

Write to a running line

A shell with open_stdin: true reads what stdin/write sends until stdin/close. Both name the id of that shell request, as $/cancelRequest does, and its answer comes when the line ends.
stdin/write answers once the bytes are buffered, so a command that reads slowly holds it back. Send one at a time to keep the bytes in order.

Errors

A file error carries the HTTP error object in data: its code, message and errno, plus a decision record when a policy refused it: