Interfaces

Runtime MCP tools

Call the seven runtime tools for command sessions and file operations.

On this page+

Before you call
Command sessions
exec_command
write_command_stdin
read_command_lines
Files and attribution
file_read
file_write
file_edit
file_blame
Session and result contract

Before you call

Start one stdio server with sandbox-mcp --set runtime. All seven tools require sandbox_id. The adapter lifts that property into gateway scope and sends the remaining properties as semantic operation arguments.

Server process

sandbox-mcp --set runtime

Keep command_session_id values returned by running commands and page transcripts by offset. Direct file changes publish immediately when workspace_session_id is omitted. See Files and commands for complete workflows.

Find an operation

Showing 7 of 7 tools.

Command sessions

Start a command, write input, and page its stable transcript.

`exec_command`

Start a sandbox shell command

Session state

Start a shell command in a workspace session. Omit workspace_session_id to use an automatic publish_then_destroy session.

When to use it

Use workspace_session_id only when an existing managed session is available.
If status is running, retain command_session_id for read_command_lines or write_command_stdin.
A terminal automatic command captures and publishes filesystem changes before destroying its session.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`workspace_session_id`	`string`	No	Existing workspace session id to run inside. Omit to create a session with finalize policy publish_then_destroy.
`cmd`	`string`	Yes	Shell command text.
`timeout_ms`	`integer`	No	Command timeout in milliseconds.
`yield_time_ms`	`integer`	No	Initial output wait in milliseconds.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "exec_command",
    "arguments": {
      "sandbox_id": "sbox-example",
      "cmd": "cargo check",
      "yield_time_ms": 1000
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "workspace_session_id": {
      "type": "string",
      "description": "Existing workspace session id to run inside. Omit to create a session with finalize policy publish_then_destroy."
    },
    "cmd": {
      "type": "string",
      "description": "Shell command text."
    },
    "timeout_ms": {
      "type": "integer",
      "description": "Command timeout in milliseconds.",
      "minimum": 0
    },
    "yield_time_ms": {
      "type": "integer",
      "description": "Initial output wait in milliseconds.",
      "minimum": 0
    }
  },
  "required": [
    "sandbox_id",
    "cmd"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "running",
      "exit_code": null,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 0,
      "end_offset": 2,
      "total_lines": 2,
      "original_token_count": 4,
      "output": "building…\n"
    },
    "isError": false
  }
}

Result contract: status is running, ok, error, timed_out, or cancelled. A terminal result can include publication fields.

Related operationswrite_command_stdin read_command_lines

`write_command_stdin`

Write to a running command

Session state

Append text to the stdin stream of a running command session and return a bounded output yield.

When to use it

Use a command_session_id returned while exec_command is still running.
stdin is written exactly as supplied; include a newline for line-oriented programs.
The result uses the command-output shape and may become terminal after the write.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`command_session_id`	`string`	Yes	Command session id returned by exec_command.
`stdin`	`string`	Yes	Text to write to stdin.
`yield_time_ms`	`integer`	No	Output wait after writing stdin.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_command_stdin",
    "arguments": {
      "sandbox_id": "sbox-example",
      "command_session_id": "namespace_execution_42",
      "stdin": "yes\n",
      "yield_time_ms": 1000
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "command_session_id": {
      "type": "string",
      "description": "Command session id returned by exec_command."
    },
    "stdin": {
      "type": "string",
      "description": "Text to write to stdin."
    },
    "yield_time_ms": {
      "type": "integer",
      "description": "Output wait after writing stdin.",
      "minimum": 0
    }
  },
  "required": [
    "sandbox_id",
    "command_session_id",
    "stdin"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "ok",
      "exit_code": 0,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 0,
      "end_offset": 4,
      "total_lines": 4,
      "original_token_count": 4,
      "output": "accepted\ndone\n"
    },
    "isError": false
  }
}

Result contract: The response contains only a bounded transcript window.

Related operationsexec_command read_command_lines

`read_command_lines`

Page a command transcript

Read-only

Read rendered command output for a command session using stable line offsets.

When to use it

Start at offset 0, then continue from end_offset until it reaches total_lines.
The command may still be running; status and offsets are a point-in-time snapshot.
Reading output does not extend or trigger workspace-session lifecycle behavior.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`command_session_id`	`string`	Yes	Command session id returned by exec_command.
`start_offset`	`integer`	No; default 0	First transcript line offset. Defaults to 0.
`limit`	`integer`	No; default 200	Maximum transcript rows to return. Defaults to 200; maximum 1000.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_command_lines",
    "arguments": {
      "sandbox_id": "sbox-example",
      "command_session_id": "namespace_execution_42",
      "start_offset": 2,
      "limit": 200
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "command_session_id": {
      "type": "string",
      "description": "Command session id returned by exec_command."
    },
    "start_offset": {
      "type": "integer",
      "description": "First transcript line offset. Defaults to 0.",
      "minimum": 0,
      "default": 0
    },
    "limit": {
      "type": "integer",
      "description": "Maximum transcript rows to return. Defaults to 200; maximum 1000.",
      "minimum": 0,
      "default": 200
    }
  },
  "required": [
    "sandbox_id",
    "command_session_id"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "command_session_id": "namespace_execution_42",
      "workspace_session_id": "workspace_17",
      "status": "ok",
      "exit_code": 0,
      "wall_time_seconds": 0.25,
      "command_total_time_seconds": 0.25,
      "start_offset": 2,
      "end_offset": 4,
      "total_lines": 4,
      "original_token_count": 4,
      "output": "accepted\ndone\n"
    },
    "isError": false
  }
}

Result contract: original_token_count describes the untruncated source before rendering bounds.

Related operationsexec_command write_command_stdin

Files and attribution

Read snapshots, publish file mutations, and inspect line ownership.

`file_read`

Read a UTF-8 text window

Read-only

Read a UTF-8 window from a repository-relative or workspace-root-absolute path in the published snapshot or a live session.

When to use it

Omit workspace_session_id for the published snapshot; include it for uncommitted session content.
Follow next_offset while truncated is true to page long files.
Only UTF-8 regular files are supported.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`path`	`string`	Yes	Repository-relative or workspace-root-absolute path to read.
`offset`	`integer`	No; default 1	1-indexed line number to start reading from. Defaults to 1.
`limit`	`integer`	No; default 2000	Maximum number of lines to read. Defaults to 2000; must be 1..=2000.
`workspace_session_id`	`string`	No	Existing workspace session id to read inside. Omit to read the snapshot.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_read",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "README.md",
      "offset": 1,
      "limit": 40
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "path": {
      "type": "string",
      "description": "Repository-relative or workspace-root-absolute path to read."
    },
    "offset": {
      "type": "integer",
      "description": "1-indexed line number to start reading from. Defaults to 1.",
      "minimum": 0,
      "default": 1
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of lines to read. Defaults to 2000; must be 1..=2000.",
      "minimum": 0,
      "default": 2000
    },
    "workspace_session_id": {
      "type": "string",
      "description": "Existing workspace session id to read inside. Omit to read the snapshot."
    }
  },
  "required": [
    "sandbox_id",
    "path"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "path": "README.md",
      "content": "# Example\n\nProject overview…\n",
      "start_line": 1,
      "num_lines": 3,
      "total_lines": 3,
      "bytes_read": 31,
      "total_bytes": 31,
      "next_offset": null,
      "truncated": false
    },
    "isError": false
  }
}

Result contract: next_offset is non-null when another window is available.

Related operationsfile_write file_edit file_blame

`file_write`

Create or overwrite a file

Changes state

Write content to a path in a live session, or publish a new attributed layer when no session is supplied.

When to use it

Use only when overwriting the complete target file is intended.
A session-scoped write stays private until that session resolves.
Without a session, the runtime publishes a layer owned by operation:<request_id>.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`path`	`string`	Yes	Repository-relative or workspace-root-absolute path to write.
`content`	`string`	Yes	File content to write.
`workspace_session_id`	`string`	No	Existing workspace session id to write inside. Omit to publish a layer.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_write",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt",
      "content": "new content\n"
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "path": {
      "type": "string",
      "description": "Repository-relative or workspace-root-absolute path to write."
    },
    "content": {
      "type": "string",
      "description": "File content to write."
    },
    "workspace_session_id": {
      "type": "string",
      "description": "Existing workspace session id to write inside. Omit to publish a layer."
    }
  },
  "required": [
    "sandbox_id",
    "path",
    "content"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "type": "update",
      "path": "notes.txt",
      "bytes_written": 12
    },
    "isError": false
  }
}

Result contract: type is create for a new path or update for an existing regular file.

Related operationsfile_read file_edit file_blame

`file_edit`

Apply ordered exact replacements

Changes state

Apply ordered exact-string replacements in a live session, or publish one attributed layer when no session is supplied.

When to use it

Each item requires old_string and new_string; replace_all defaults to false.
Without replace_all, old_string must occur exactly once. Empty, missing, ambiguous, and no-op edits fail.
Edits run in array order; omitting a session publishes a durable layer immediately.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`path`	`string`	Yes	Repository-relative or workspace-root-absolute path to edit.
`edits`	`array`	Yes	JSON array of { old_string, new_string, replace_all? } edits, applied in order.
`workspace_session_id`	`string`	No	Existing workspace session id to edit inside. Omit to publish a layer.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_edit",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt",
      "edits": [
        {
          "old_string": "draft",
          "new_string": "ready",
          "replace_all": true
        }
      ]
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "path": {
      "type": "string",
      "description": "Repository-relative or workspace-root-absolute path to edit."
    },
    "edits": {
      "type": "array",
      "description": "JSON array of { old_string, new_string, replace_all? } edits, applied in order."
    },
    "workspace_session_id": {
      "type": "string",
      "description": "Existing workspace session id to edit inside. Omit to publish a layer."
    }
  },
  "required": [
    "sandbox_id",
    "path",
    "edits"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "type": "edit",
      "path": "notes.txt",
      "edits_applied": 1,
      "replacements": 2,
      "bytes_written": 26
    },
    "isError": false
  }
}

Result contract: edits_applied counts edit objects; replacements counts occurrences changed.

Related operationsfile_read file_write file_blame

`file_blame`

Inspect per-line published ownership

Read-only

Return each line owner for a published path from the latest auditability event.

When to use it

Use this after commands, writes, or edits have created auditability events.
Ranges are 1-indexed and tile the latest known file content.
Treat owner strings as opaque. A missing auditability record returns not_found.

Tool arguments

Property	Type	Required	Description
`sandbox_id`	`string`	Yes	Target sandbox id (selects the daemon to query).
`path`	`string`	Yes	Repository-relative path to blame.

JSON-RPC request

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "file_blame",
    "arguments": {
      "sandbox_id": "sbox-example",
      "path": "notes.txt"
    }
  }
}

Published input schema

JSON Schema

{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "Target sandbox id (selects the daemon to query)."
    },
    "path": {
      "type": "string",
      "description": "Repository-relative path to blame."
    }
  },
  "required": [
    "sandbox_id",
    "path"
  ],
  "additionalProperties": false
}

Representative result

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "path": "notes.txt",
      "ranges": [
        {
          "start_line": 1,
          "line_count": 4,
          "owner": "original"
        },
        {
          "start_line": 5,
          "line_count": 2,
          "owner": "operation:request-id"
        }
      ]
    },
    "isError": false
  }
}

Result contract: owner can be workspace_session:<id>, operation:<id>, original, or unknown.

Related operationsfile_read file_write file_edit

Session and result contract

The server does not stream MCP progress. A command call yields a bounded initial transcript; use read_command_lines and write_command_stdin for continuation. Each call returns an empty content array, a gateway envelope in structuredContent, and isError for tool-level failure.