> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RPC

> Drive a workspace session from a program over JSON-RPC 2.0.

RPC is a session's in-app API over [JSON-RPC 2.0](https://www.jsonrpc.org/specification).
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:

```
http://127.0.0.1:8765/v1/workspaces/{id}/rpc
```

## Connect

These examples use the `demo` workspace from the [CLI quickstart](https://docs.mirage.strukto.ai/home/access/cli.md#quickstart).

> [tab] stdio
>
> `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.
>
> ```bash theme={null}
> echo '{"jsonrpc": "2.0", "id": 1, "method": "shell", "params": {"command": "ls / | wc -l"}}' | mirage rpc -w demo
> ```

> [tab] HTTP
>
> One message, or a batch, per `POST`. The answer is the body.
>
> ```bash theme={null}
> curl -s http://127.0.0.1:8765/v1/workspaces/demo/rpc \
>   -H "Authorization: Bearer $MIRAGE_TOKEN" \
>   -H 'Content-Type: application/json' \
>   -d '{"jsonrpc": "2.0", "id": 1, "method": "shell", "params": {"command": "ls / | wc -l"}}'
> ```

Both answer:

```json theme={null}
{"jsonrpc": "2.0", "id": 1, "result": {"exit_code": 0, "stdout": "3\n", "stderr": "", "decision": null}}
```

Answers come back as calls finish, so match them by `id`.

## Auth

RPC uses the same bearer token as [HTTP](https://docs.mirage.strukto.ai/home/access/http.md#configure-authentication). `mirage rpc`
sends the CLI's token for you: a saved [login](https://docs.mirage.strukto.ai/home/access/cli.md#log-in),
`MIRAGE_TOKEN`, or the local token file. A client that posts to the URL sends
the header itself.

## Methods

| Method | Params | Result |
| - | - | - |
| `initialize` | | `{server_info, protocol_version, workspace_id, session_id, methods}` |
| `shell` | `command`, `cwd?`, `env?`, `stdin?`, `open_stdin?`, `explain?` | `{exit_code, stdout, stderr, decision}` |
| `stdin/write` | `id`, `data` | `null` |
| `stdin/close` | `id` | `null` |
| `vfs/<call>` | the call's arguments, `explain?` | the same object as HTTP, such as `{exists}` or `{}` |
| `tools/<tool>` | the tool's input | `{text, is_error}` |
| `tools/list` | | `{tools}`, as MCP lists them |
| `tools/call` | `name`, `arguments` | `{text, is_error}` |

* `?` 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](https://docs.mirage.strukto.ai/api/reference.md),
  with the same arguments and results as HTTP. The [tools](https://docs.mirage.strukto.ai/home/access/mcp.md#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](https://docs.mirage.strukto.ai/home/policy/explain.md).
* Bytes, `stdin` included, are base64 strings. A message is at most 4 MiB, so
  send larger stdin over [HTTP](https://docs.mirage.strukto.ai/api/streaming.md#send-stdin) 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](https://docs.mirage.strukto.ai/home/configuration/session.md) 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.

```json theme={null}
{"jsonrpc": "2.0", "method": "$/cancelRequest", "params": {"id": 7}}
```

## 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.

```json theme={null}
{"jsonrpc": "2.0", "id": 7, "method": "shell", "params": {"command": "cat", "open_stdin": true}}
{"jsonrpc": "2.0", "id": 8, "method": "stdin/write", "params": {"id": 7, "data": "aGVsbG8K"}}
{"jsonrpc": "2.0", "id": 9, "method": "stdin/close", "params": {"id": 7}}
```

`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

| Code | Means |
| - | - |
| `-32700` | The message is not JSON. |
| `-32600` | Not a JSON-RPC 2.0 request: no `"jsonrpc": "2.0"`, or no method. |
| `-32601` | No such method. |
| `-32602` | Bad params. |
| `-32004` | No such path (`ENOENT`), or no running `shell` opened that stdin. |
| `-32603` | Anything else, such as a refused path. |
| `-32800` | Canceled. |

A file error carries the [HTTP error object](https://docs.mirage.strukto.ai/api/errors.md#error-body) in `data`:
its `code`, `message` and `errno`, plus a `decision` record when a policy
refused it:

```json theme={null}
{"jsonrpc": "2.0", "id": 2, "error": {"code": -32004, "message": "No such file or directory", "data": {"code": "not_found", "message": "No such file or directory", "errno": "ENOENT"}}}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.