跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

接口

管理 MCP 工具

按照已发布的 schema 和结构化结果调用八项管理工具。

本页内容+

调用之前

使用 sandbox-mcp --set management 启动一个 stdio 服务器。它只发布八项系统范围工具，不发布运行时、可观测性、prompts、resources 或内部协调路由。

服务器进程
sandbox-mcp --set management

创建前使用发现工具，执行破坏性操作前检查目标记录，并把宿主机路径视为敏感输入。注册说明见MCP 服务器。

按类别筛选操作

显示 8 / 8 项工具。

宿主机发现

查找本地镜像和选择器可见的工作区根目录。

list_docker_images

列出本地 Docker 镜像引用

只读

列出所有本地 Docker 镜像引用，包括可用于创建沙箱的无标签镜像 ID。

何时使用

  1. 当调用方需要有效的本地镜像引用时，请在 create_sandbox 之前调用。
  2. 结果可能包含标签、摘要和无标签镜像 ID；请原样传入选中的字符串。
  3. 此操作不会拉取镜像，也不会创建沙箱。

工具参数

无参数。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_docker_images",
    "arguments": {}
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "images": [
        "ubuntu:24.04",
        "sha256:abc123…"
      ]
    },
    "isError": false
  }
}

结果约定： images 是已配置运行时提供器返回的完整集合。

相关操作create_sandbox

list_workspace_directories

浏览允许使用的工作区目录

只读

省略 path 时列出选择器可见的工作区根目录；指定后最多列出所选目录的 500 个直接子目录。

何时使用

  1. 省略 path 先列出选择器可见的根目录，再逐层浏览返回的绝对路径。
  2. 每次只返回直接子目录；如需深入，请重复调用。
  3. 将选中的绝对路径作为 create_sandbox.workspace_root。

工具参数

属性类型必填说明
pathstring否要浏览的、选择器可见的绝对工作区目录。省略时列出根目录。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_workspace_directories",
    "arguments": {
      "path": "/host/workspaces"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "要浏览的、选择器可见的绝对工作区目录。省略时列出根目录。"
    }
  },
  "required": [],
  "additionalProperties": false
}

代表性结果

响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "structuredContent": {
      "path": "/host/workspaces",
      "parent": "/host",
      "truncated": false,
      "directories": [
        {
          "name": "example",
          "path": "/host/workspaces/example"
        }
      ]
    },
    "isError": false
  }
}

结果约定： 位于已配置根目录时，path 和 parent 可能为 null；超过浏览上限后 truncated 为 true。

相关操作create_sandbox

沙箱生命周期

创建、枚举、检查和移除由管理器维护的记录。

create_sandbox

创建并启动一个或多个沙箱

修改状态

创建宿主机侧沙箱记录和运行时沙箱，然后启动其守护进程。

何时使用

  1. 先用发现操作选择有效的本地镜像和允许的工作区根目录。
  2. count=1 返回一条记录；更大的值返回 sandboxes 数组。
  3. 多沙箱批次创建失败时会回滚；成功创建会修改宿主机和容器状态。

工具参数

属性类型必填说明
imagestring是用于创建沙箱的容器镜像。
workspace_rootstring是绑定挂载到沙箱中的宿主机绝对工作区目录。
countinteger否；默认值 1要创建的沙箱数量（最少为 1）。大于 1 时共享一个只读工作区基础层。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_sandbox",
    "arguments": {
      "image": "ubuntu:24.04",
      "workspace_root": "/host/workspaces/example",
      "count": 1
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "image": {
      "type": "string",
      "description": "用于创建沙箱的容器镜像。"
    },
    "workspace_root": {
      "type": "string",
      "description": "绑定挂载到沙箱中的宿主机绝对工作区目录。"
    },
    "count": {
      "type": "integer",
      "description": "要创建的沙箱数量（最少为 1）。大于 1 时共享一个只读工作区基础层。",
      "minimum": 0,
      "default": 1
    }
  },
  "required": [
    "image",
    "workspace_root"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： count 为 1 时返回一条记录；大于 1 时返回 { sandboxes: [record, …] }。

相关操作list_sandboxesinspect_sandboxdestroy_sandbox

list_sandboxes

列出管理器已知的沙箱

只读

列出管理器已知的沙箱记录，包括生命周期状态和已配置的守护进程端点元数据。

何时使用

  1. 将其作为 sandbox_id 和生命周期状态的主要只读来源。
  2. 记录处于创建、停止中、已停止或失败状态时，可能没有可用的守护进程元数据。
  3. 已保存的端点不代表一定可达；需要确认健康状态时请使用 observability snapshot。

工具参数

无参数。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_sandboxes",
    "arguments": {}
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： 管理器没有记录时，sandboxes 为空。

相关操作inspect_sandboxcreate_sandbox

inspect_sandbox

检查一条沙箱记录

只读

检查沙箱记录，包括生命周期状态、工作区根目录和已配置的守护进程端点元数据。

何时使用

  1. 需要某条记录及其端点元数据时，请使用 list_sandboxes 返回的 ID。
  2. 此操作只读取管理器注册表，不会调用守护进程，也不能证明运行时健康。
  3. 请将工作区路径和端点视为运维元数据。

工具参数

属性类型必填说明
sandbox_idstring是沙箱 ID。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "inspect_sandbox",
    "arguments": {
      "sandbox_id": "sbox-example"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "沙箱 ID。"
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： 在 ready 之外的生命周期状态中，daemon、daemon_http 和 shared_base 可能为 null。

相关操作list_sandboxessnapshot

destroy_sandbox

停止并移除沙箱

修改状态

停止沙箱守护进程、销毁运行时沙箱，并移除宿主机侧沙箱记录。

何时使用

  1. 调用前先用 inspect_sandbox 确认目标。
  2. 管理器会停止守护进程、销毁运行时、将记录标为 stopped，然后移除记录。
  3. 若销毁运行时失败，记录会以 failed 状态保留，供运维人员恢复。

工具参数

属性类型必填说明
sandbox_idstring是沙箱 ID。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "destroy_sandbox",
    "arguments": {
      "sandbox_id": "sbox-example"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "沙箱 ID。"
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： 成功时返回已移除记录的最终 stopped 状态。

相关操作list_sandboxesinspect_sandbox

层交付

压缩已发布层，或在宿主机上物化其增量。

squash_layerstacks

压缩符合条件的已发布层

修改状态

将每个可压缩区段合并为等价的扁平层，并把在线工作区会话迁移到更短的层链。

何时使用

  1. 用于运维人员主动执行存储压缩；此操作会改变活动层 manifest。
  2. 守护进程提交等价的扁平层，并报告迁移或租约处理结果。
  3. 不支持压缩操作的旧守护进程会返回 operation_failed，必须重新创建。

工具参数

属性类型必填说明
sandbox_idstring是沙箱 ID。

JSON-RPC 请求

请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "squash_layerstacks",
    "arguments": {
      "sandbox_id": "sbox-example"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "沙箱 ID。"
    }
  },
  "required": [
    "sandbox_id"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： 可选的 blocked_reasons 和 faulty_sessions 用于说明未完全回收的原因。

相关操作inspect_sandboxexport_changeslayerstack

export_changes

应用或归档已发布增量

修改状态

把基础层之上的全部已发布层折叠为经过验证的增量，并应用到宿主机目录或写入归档。

何时使用

  1. 使用 dir 将增量应用到宿主机目录；使用 tar/tar-zst 原子写入归档。
  2. dest 必须是绝对路径；禁止使用文件系统根目录、家目录、管理器状态目录和导出暂存目录。
  3. 管理器会验证守护进程返回的字节，并且是唯一写入宿主机目标的组件。

工具参数

属性类型必填说明
sandbox_idstring是沙箱 ID。
deststring是宿主机绝对目标路径：dir 使用目录，tar 格式使用归档文件。
formatstring否；默认值 dir输出格式：dir、tar 或 tar-zst。

JSON-RPC 请求

请求
{
  "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"
    }
  }
}
已发布的输入 schema
JSON Schema
{
  "type": "object",
  "properties": {
    "sandbox_id": {
      "type": "string",
      "description": "沙箱 ID。"
    },
    "dest": {
      "type": "string",
      "description": "宿主机绝对目标路径：dir 使用目录，tar 格式使用归档文件。"
    },
    "format": {
      "type": "string",
      "description": "输出格式：dir、tar 或 tar-zst。",
      "default": "dir"
    }
  },
  "required": [
    "sandbox_id",
    "dest"
  ],
  "additionalProperties": false
}

代表性结果

响应
{
  "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
  }
}

结果约定： dir 结果报告删除和不透明目录清除；归档结果报告输出的 whiteout。

相关操作inspect_sandboxsquash_layerstacks

结果与错误约定

每次工具调用都会返回 MCP 结果：content 数组为空，网关响应位于 structuredContent，并带有明确的 isError 布尔值。远程错误仍是成功的 JSON-RPC 响应，但其工具结果包含 isError: true 和结构化错误 envelope。

18 个结果