Connection wire protocol

If you use our SDKs or CLI, you don't need to read this. The SDKs handle the wire protocol for you. If you want to manually access a machine's file system, connect to its shell, or run a command, this page explains the message formats and connection details.

Get an access token

Request a token for the kind of access you need: shell, files, or ports. Tokens last 3600 seconds by default and up to 86400.

curl -X POST https://api.metorial.com/sandbox/machines/$MACHINE/access/shell \
  -H "Authorization: Bearer $METORIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 3600}'

{
  "object": "sandbox.machine.access",
  "token": "…",
  "scope": "shell",
  "urls": {
    "shell": "wss://…",
    "exec": "wss://…",
    "files": "wss://…",
    "ports": {}
  },
  "expires_at": "2026-10-16T15:00:00.000Z"
}

A shell token works for both the shell and exec URLs. For ports, pass "ports": [3000] or "ports": "*" in the body, and urls.ports maps each port to its URL.

Authenticate a WebSocket

Send the token as a WebSocket subprotocol, next to the protocol name. Headers and query parameters aren't accepted. Browsers can connect this way, since they can't set WebSocket headers.

let socket = new WebSocket(access.urls.exec, [
  'metorial-sandbox-v1',
  `metorial-sandbox-token.${access.token}`
]);
socket.binaryType = 'arraybuffer';

Call a port

Ports are plain HTTPS. Send the token in the Metorial-Sandbox-Token header. Public ports need no token.

curl -H "Metorial-Sandbox-Token: $TOKEN" "$PORT_URL/health"

Multiplexed framing

The exec and files protocols run many requests over one socket. Every request has a client-chosen id, and every reply carries it.

• Text frames are JSON objects with an id.
• Binary frames start with one byte holding the length of the id, then the id in UTF-8, then the payload.

[id length: 1 byte][id: UTF-8][payload]

Exec

Use the urls.exec socket to run commands and stream their output. The SDKs' command() and spawn() use it.

Run a command

{
  "id": "r1",
  "op": "run",
  "v": 1,
  "command": ["/bin/sh", "-c", "npm test"],
  "cwd": "/app",
  "env": { "CI": "true" },
  "timeoutMs": 300000
}

command is an argv array. cwd, env, and timeoutMs are optional. Set "stdin": true to keep standard input open for writing.

Messages from the client

Messages from the server

Interactive shell

Use the urls.shell socket for a terminal session. The CLI's shell command uses it. Each socket carries one session.

Open a session

Send open as the first message:

{ "type": "open", "v": 1, "tty": true, "cols": 120, "rows": 40, "cwd": "/app" }

command (an argv array), cwd, and env are optional. Leave out command for an interactive shell. cols and rows go from 1 to 1000 and only apply when tty is true.

The server answers with { "type": "session_init", "sessionId": "shs_…", "offset": 0 }.

Streams

• Client binary frames are stdin.
• With tty: true, server binary frames are raw terminal output.
• Without a TTY, the first byte of each server binary frame is 0x01 for stdout or 0x02 for stderr.

Control messages from the client are { "type": "resize", "cols", "rows" }, { "type": "signal", "signal": "INT" }, and { "type": "stdin_eof" }. When the process ends, the server sends { "type": "exit", "code", "signal" }.

Resume after a dropped connection

Track how many output bytes you've received. If the socket drops without a normal close, open a new socket and attach to the session instead of opening a new one:

{ "type": "attach", "v": 1, "sessionId": "shs_…", "offset": 18342 }

The server replays output from offset. If some of it is no longer buffered, it first sends { "type": "output_gap", "from", "to" }. Closing the socket with code 1000 ends the session for good.

Files

Use the urls.files socket to read and write files. Requests use the multiplexed framing, and file content travels in binary frames of up to 64 KiB. All paths are absolute.

Write a file

After the write request, send the content as binary frames, then finish with the SHA-256 of the whole content. The server rejects the write with checksum_mismatch if the hashes differ.

{ "id": "w1", "type": "end", "sha256": "9f86d08…" }

write also accepts append, sync, and the expected total size.

File entries

stat and list return entries with type (file, directory, symlink, or other), size, mode, mtime in milliseconds, and target for symlinks. Non-recursive listings set name. Recursive listings set path, relative to the listed directory.

Cancel a request

Send { "id": "c1", "op": "cancel", "target": "r1" } to cancel request r1, or { "id": "w1", "type": "abort" } to abort an upload in progress.

Errors

{
  "id": "r1",
  "type": "error",
  "error": { "code": "not_found", "message": "…", "path": "/app/x" }
}

Connection notices

Idle sockets close after the machine's connection idle timeout. Before that, the server sends notices:

{ "type": "connection_notice", "notice": "idle_warning", "idleInSeconds": 30 }

notice is idle_warning, idle, or closing, and closing can include a reason.

Close codes

The shell socket adds these: