Interfaces
Observability MCP tools
Call the five read-only observability tools and interpret their structured evidence.
On this page+−
Before you call
Start one stdio server with sandbox-mcp --set observability. The five tools are read-only. snapshot accepts an optional sandbox_id; the other four require it.
sandbox-mcp --set observabilityQuery snapshot first, then narrow to trace, event, resource, or layer evidence. The architecture guide explains the runtime and LayerStack boundaries behind this evidence.
Showing 5 of 5 tools.
Fleet health
Inspect normalized live availability and active runtime state.
Show live state for one sandbox, or aggregate every ready manager-known sandbox when sandbox_id is omitted.
When to use it
- Omit sandbox_id for fleet aggregation, or supply one id to select a manager record.
- Each node normalizes availability and includes an errors array for partial failures.
- Use this first for live health, then follow with telemetry or resource operations.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | No | Optional target sandbox id. When omitted, the manager queries all ready sandboxes. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "snapshot",
"arguments": {}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Optional target sandbox id. When omitted, the manager queries all ready sandboxes."
}
},
"required": [],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"sandboxes": [
{
"sandbox_id": "sbox-example",
"lifecycle_state": "ready",
"availability": "available",
"sampled_at_unix_ms": 1784016000000,
"errors": [],
"daemon": {
"daemon_pid": 321,
"runtime_dir": "/run/ephemeral-os"
},
"resources": {
"latest": null,
"history": []
},
"workspaces": [],
"stack": {
"layer_count": 2,
"layers_bytes": 4096,
"active_leases": 0
}
}
]
},
"isError": false
}
}Result contract: A sandbox-scoped call returns the node shape rather than the aggregate sandboxes wrapper.
Related operationstracecgrouplayerstack
Traces and events
Fold telemetry into a span waterfall or filtered fact stream.
Fold the telemetry log into a nested span waterfall for one exact trace or the most recent root trace.
When to use it
- Use last for the most recently started root trace, or provide an exact trace/request id.
- spans is a forest containing completed span data, offsets, children, and events.
- An unknown trace is not an operation error; it returns an empty spans array.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Target sandbox id (selects the daemon to query). |
trace_id | string | No; default last | Trace id to render, or 'last' for the most recent root trace. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "trace",
"arguments": {
"sandbox_id": "sbox-example",
"trace_id": "last"
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Target sandbox id (selects the daemon to query)."
},
"trace_id": {
"type": "string",
"description": "Trace id to render, or 'last' for the most recent root trace.",
"default": "last"
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"view": "trace",
"trace": "request-uuid",
"spans": [
{
"span": {
"ts": 1784016000250,
"trace": "request-uuid",
"span": "d-0",
"name": "daemon.dispatch",
"dur_ms": 250,
"status": "completed",
"attrs": {
"op": "exec_command"
}
},
"offset_ms": 0,
"children": [],
"events": []
}
]
},
"isError": false
}
}Result contract: Span status is completed, error, cancelled, or timed_out; attrs is operation-specific.
Fold the telemetry log into a newest-first event stream with optional exact-name, timestamp, and count filters.
When to use it
- name is an exact dotted label such as lease.acquired.
- last_n retains only the newest matches; omit filters for every retained event.
- Each event carries trace and parent identifiers that can be followed into trace.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Target sandbox id (selects the daemon to query). |
name | string | No | Filter to events with this exact name (e.g. lease.acquired). |
since_ms | integer | No | Only events at or after this unix-ms timestamp. |
last_n | integer | No | Keep only the N newest matched events. |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "events",
"arguments": {
"sandbox_id": "sbox-example",
"name": "lease.acquired",
"last_n": 20
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Target sandbox id (selects the daemon to query)."
},
"name": {
"type": "string",
"description": "Filter to events with this exact name (e.g. lease.acquired)."
},
"since_ms": {
"type": "integer",
"description": "Only events at or after this unix-ms timestamp.",
"minimum": 0
},
"last_n": {
"type": "integer",
"description": "Keep only the N newest matched events.",
"minimum": 0
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"view": "events",
"events": [
{
"ts": 1784016000120,
"trace": "request-uuid",
"parent": "d-1",
"name": "lease.acquired",
"attrs": {
"layer_id": "layer-7"
}
}
]
},
"isError": false
}
}Result contract: attrs is an open domain-fact object and varies by event name.
Related operationstrace
Resources and layers
Inspect resource samples and the active layer manifest.
Read sandbox CPU, memory, and I/O counters from Docker Engine, or workspace disk samples from daemon telemetry.
When to use it
- Use sandbox scope for Docker CPU, memory, and block-I/O counters.
- Use a workspace id as scope for daemon-recorded workspace disk samples.
- Deltas appear only when a prior counter sample exists in the selected window.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Target sandbox id (selects the daemon to query). |
scope | string | No; default sandbox | Resource scope: 'sandbox' or a workspace id. |
window_ms | integer | No; default 60000 | Lookback window in milliseconds (max 600000). |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "cgroup",
"arguments": {
"sandbox_id": "sbox-example",
"scope": "sandbox",
"window_ms": 60000
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Target sandbox id (selects the daemon to query)."
},
"scope": {
"type": "string",
"description": "Resource scope: 'sandbox' or a workspace id.",
"default": "sandbox"
},
"window_ms": {
"type": "integer",
"description": "Lookback window in milliseconds (max 600000).",
"minimum": 0,
"default": 60000
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"view": "cgroup",
"scope": "sandbox",
"series": [
{
"ts": 1784016000000,
"sample_delta_ms": null,
"metrics": {
"metrics_source": "docker_engine",
"cpu_usec": 912345,
"mem_cur": 67108864,
"mem_max": 1073741824,
"io_rbytes": 4096,
"io_wbytes": 8192
},
"deltas": {}
}
]
},
"isError": false
}
}Result contract: Sandbox metrics identify metrics_source as docker_engine.
Related operationssnapshotlayerstack
Show live layer sizes, leases, base bookings, and optional trend data from the active manifest.
When to use it
- Omit workspace_id for the full active manifest and optional trend.
- Include workspace_id for that session lower layers and private upperdir bytes.
- Layers are returned in manifest order; booked_by and leased_by_workspaces describe live use.
Tool arguments
| Property | Type | Required | Description |
|---|---|---|---|
sandbox_id | string | Yes | Target sandbox id (selects the daemon to query). |
workspace_id | string | No | Show one workspace's lower layers and private upperdir. |
window_ms | integer | No; default 60000 | Lookback window in milliseconds for the stack trend (max 600000). |
JSON-RPC request
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "layerstack",
"arguments": {
"sandbox_id": "sbox-example",
"window_ms": 60000
}
}
}Published input schema
{
"type": "object",
"properties": {
"sandbox_id": {
"type": "string",
"description": "Target sandbox id (selects the daemon to query)."
},
"workspace_id": {
"type": "string",
"description": "Show one workspace's lower layers and private upperdir."
},
"window_ms": {
"type": "integer",
"description": "Lookback window in milliseconds for the stack trend (max 600000).",
"minimum": 0,
"default": 60000
}
},
"required": [
"sandbox_id"
],
"additionalProperties": false
}Representative result
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [],
"structuredContent": {
"view": "layerstack",
"manifest_version": 7,
"root_hash": "sha256:…",
"active_lease_count": 1,
"total_bytes": 16384,
"total_allocated_bytes": 20480,
"storage_logical_bytes": 24576,
"storage_allocated_bytes": 28672,
"staging_entry_count": 0,
"layers": [
{
"layer_id": "layer-7",
"bytes": 8192,
"allocated_bytes": 12288,
"leased_by_workspaces": 1,
"booked_by": []
}
],
"trend": []
},
"isError": false
}
}Result contract: With workspace_id, the result changes to { view, workspace, mounts, upper_bytes }.
Evidence and result contract
Results are point-in-time and can include partial evidence. The MCP result has an empty content array, the gateway response in structuredContent, and isError. Operation and transport failures use isError: true with the structured error envelope preserved for inspection.