Interfaces
Management MCP tools
Call the eight management tools with their published schemas and structured results.
On this page+−
Before you call
Start one stdio server with sandbox-mcp --set management. It publishes exactly eight system-scoped tools; it does not publish runtime, observability, prompts, resources, or internal coordination routes.
sandbox-mcp --set managementUse discovery tools before creation, inspect the selected record before destructive work, and treat host paths as sensitive inputs. Registration instructions are in MCP servers.
Showing 8 of 8 tools.
Host discovery
Find local images and picker-visible workspace roots.
List every local Docker image reference, including untagged image IDs that can create a sandbox.
When to use it
- Call this before create_sandbox when the caller needs a valid local image reference.
- The result may contain tags, digests, and untagged image IDs. Pass the selected string unchanged.
- This operation does not pull an image or create a sandbox.
Tool arguments
No arguments.
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_docker_images",
"arguments": {}
}
}Published input schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"images": [
"ubuntu:24.04",
"sha256:abc123…"
]
},
"isError": false
}
}Result contract: images is the complete set returned by the configured runtime provider.
List picker-visible workspace roots when path is omitted, or up to 500 immediate local subdirectories of a selected workspace directory.
When to use it
- Omit path to list picker-visible roots, then browse one returned absolute path at a time.
- Only immediate subdirectories are returned; repeat the call to walk deeper.
- Use the selected absolute path as create_sandbox.workspace_root.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
path | string | No | Absolute picker-visible workspace directory to browse. Omit to list roots. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_workspace_directories",
"arguments": {
"path": "/host/workspaces"
}
}
}Published input schema
{
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute picker-visible workspace directory to browse. Omit to list roots."
}
},
"required": [],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"path": "/host/workspaces",
"parent": "/host",
"truncated": false,
"directories": [
{
"name": "example",
"path": "/host/workspaces/example"
}
]
},
"isError": false
}
}Result contract: path and parent may be null at a configured root. truncated becomes true after the browse limit.
Sandbox lifecycle
Create, enumerate, inspect, and remove manager-owned records.
Create a host-side sandbox record, create the runtime sandbox, and start its daemon.
When to use it
- Choose an image and workspace root with the two host-discovery operations first.
- The manager creates or reuses a shared read-only base, installs daemon assets, waits for readiness, and records endpoints.
- A failed multi-create batch is rolled back. Successful creation changes host and container state.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Container image used to create the sandbox. |
workspace_root | string | Yes | Absolute host workspace directory bind-mounted into this sandbox. |
count | integer | No; default 1 | Number of sandboxes to create (minimum 1). Values greater than 1 use a shared read-only workspace base. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_sandbox",
"arguments": {
"image": "ubuntu:24.04",
"workspace_root": "/host/workspaces/example",
"count": 1
}
}
}Published input schema
{
"type": "object",
"properties": {
"image": {
"type": "string",
"description": "Container image used to create the sandbox."
},
"workspace_root": {
"type": "string",
"description": "Absolute host workspace directory bind-mounted into this sandbox."
},
"count": {
"type": "integer",
"description": "Number of sandboxes to create (minimum 1). Values greater than 1 use a shared read-only workspace base.",
"minimum": 0,
"default": 1
}
},
"required": [
"image",
"workspace_root"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"id": "sbox-example",
"workspace_root": "/host/workspaces/example",
"state": "ready",
"daemon": {
"host": "127.0.0.1",
"port": 41001
},
"daemon_http": {
"host": "127.0.0.1",
"port": 42001
},
"shared_base": {
"source": "/host/cache/shared-base/rootfs",
"target": "/eos/layer-stack/shared-base",
"root_hash": "sha256:…",
"readonly": true
}
},
"isError": false
}
}Result contract: count 1 returns one record; count greater than 1 returns { sandboxes: [record, …] }.
List sandbox records known to the manager, including lifecycle state and configured daemon endpoint metadata.
When to use it
- Use this as the primary read-only source of sandbox_id values and lifecycle state.
- A record may lack usable daemon metadata while it is creating, stopping, stopped, or failed.
- A stored endpoint does not prove reachability; use observability snapshot when health matters.
Tool arguments
No arguments.
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_sandboxes",
"arguments": {}
}
}Published input schema
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"sandboxes": [
{
"id": "sbox-example",
"workspace_root": "/host/workspaces/example",
"state": "ready",
"daemon": {
"host": "127.0.0.1",
"port": 41001
},
"daemon_http": {
"host": "127.0.0.1",
"port": 42001
},
"shared_base": {
"source": "/host/cache/shared-base/rootfs",
"target": "/eos/layer-stack/shared-base",
"root_hash": "sha256:…",
"readonly": true
}
}
]
},
"isError": false
}
}Result contract: sandboxes is empty when the manager has no records.
Inspect one sandbox record, including lifecycle state, workspace root, and configured daemon endpoint metadata.
When to use it
- Call with an id from list_sandboxes when one record and its endpoint metadata are needed.
- This reads the manager registry; it does not call the daemon or prove runtime health.
- Treat workspace paths and endpoints as operational metadata.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Sandbox id. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "inspect_sandbox",
"arguments": {
"sandbox_id": "sbox-example"
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Sandbox id."
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"id": "sbox-example",
"workspace_root": "/host/workspaces/example",
"state": "ready",
"daemon": {
"host": "127.0.0.1",
"port": 41001
},
"daemon_http": {
"host": "127.0.0.1",
"port": 42001
},
"shared_base": {
"source": "/host/cache/shared-base/rootfs",
"target": "/eos/layer-stack/shared-base",
"root_hash": "sha256:…",
"readonly": true
}
},
"isError": false
}
}Result contract: daemon, daemon_http, and shared_base can be null outside the ready lifecycle state.
Stop the sandbox daemon, destroy the runtime sandbox, and remove the host-side sandbox record.
When to use it
- Confirm the target with inspect_sandbox before calling.
- The manager stops the daemon, destroys the runtime, marks the record stopped, and removes it.
- If runtime destruction fails, the record is retained in failed state for operator recovery.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Sandbox id. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "destroy_sandbox",
"arguments": {
"sandbox_id": "sbox-example"
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Sandbox id."
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"id": "sbox-example",
"workspace_root": "/host/workspaces/example",
"state": "stopped",
"daemon": {
"host": "127.0.0.1",
"port": 41001
},
"daemon_http": {
"host": "127.0.0.1",
"port": 42001
},
"shared_base": {
"source": "/host/cache/shared-base/rootfs",
"target": "/eos/layer-stack/shared-base",
"root_hash": "sha256:…",
"readonly": true
}
},
"isError": false
}
}Result contract: Success returns the removed record in its final stopped state.
Layer delivery
Compact published layers or materialize their delta on the host.
Squash every squashable block into equivalent flattened layers and migrate live workspace sessions onto the compact chains.
When to use it
- Use this for operator-directed storage compaction; it changes the active layer manifest.
- The daemon commits equivalent flattened layers and reports migration or lease dispositions.
- A stale daemon without squash support returns operation_failed and must be recreated.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Sandbox id. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "squash_layerstacks",
"arguments": {
"sandbox_id": "sbox-example"
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Sandbox id."
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"manifest_version": 5,
"squashed_blocks": [
{
"squashed_layer_id": "layer-flat-5",
"replaced_layer_ids": [
"layer-2",
"layer-3"
],
"replaced_layers": "reclaimed"
}
],
"swept_sessions": [
{
"session_id": "workspace_17",
"disposition": "migrated"
}
]
},
"isError": false
}
}Result contract: Optional blocked_reasons and faulty_sessions explain incomplete reclamation.
Fold every published layer above the base into a validated delta and apply it to a host directory or write an archive.
When to use it
- Use dir to apply the delta to a host directory, or tar/tar-zst to atomically write an archive.
- dest must be absolute. The filesystem root, home, manager state, and export spool paths are denied.
- The manager validates daemon bytes and is the only component that writes the host destination.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Sandbox id. |
dest | string | Yes | Absolute host destination: directory for dir, archive file for tar formats. |
format | string | No; default dir | Output format: dir, tar, or tar-zst. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "export_changes",
"arguments": {
"sandbox_id": "sbox-example",
"dest": "/host/exports/example.tar.zst",
"format": "tar-zst"
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Sandbox id."
},
"dest": {
"type": "string",
"description": "Absolute host destination: directory for dir, archive file for tar formats."
},
"format": {
"type": "string",
"description": "Output format: dir, tar, or tar-zst.",
"default": "dir"
}
},
"required": [
"sandbox_id",
"dest"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"manifest_version": 7,
"format": "tar-zst",
"layers_exported": [
"layer-6",
"layer-7"
],
"files_written": 12,
"symlinks_written": 1,
"whiteouts_emitted": 2,
"bytes_written": 48211
},
"isError": false
}
}Result contract: dir results report deletes and opaque clears; archive results report emitted whiteouts.
Tool result and error contract
Every tool call returns an MCP result with an empty content array, the gateway response in structuredContent, and an explicit isError boolean. A remote error remains a successful JSON-RPC response whose tool result has isError: true and a structured error envelope.