agent-sandbox-os

# agent-sandbox-os [](LICENSE) [](https://www.python.org/downloads/) 用于不可信工作负载（AI 代理、用户代码、CI 作业）的简单、快速、隔离的 **microVM 沙盒**，由 [**AWS Lambda MicroVMs**](https://aws.amazon.com/lambda/lambda-microvms/) 支持，并使用 **裸 `boto3`**（无需外部 IaC 引擎）进行配置。 每个沙盒都是一个 Firecracker MicroVM，具有 VM 级别的隔离、基于快照的快速启动、专用的 HTTPS 端点，以及长达 8 小时的暂停/恢复功能。 ## 为什么选择 agent-sandbox-os？ 代理工作负载运行 **不可信的、模型生成的代码**。代理在运行时决定执行什么操作 — 调用 shell、安装软件包、访问网络 — 因此事先无法确定其影响范围。容器与主机内核共享；对于您未编写的代码，这种边界通常不够强大，而建立自己的 VM 群集以实现真正的隔离是一项繁重的运维工作。 [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html) 为每个沙盒提供一个 **Firecracker microVM**，具有硬件虚拟化的 VM 级别隔离，同时保持 **无服务器** — 无需管理集群、节点或容量。`agent-sandbox-os` 封装了该后端，使代理可以将沙盒视为一种可 disposable 的工具： - **从构造上保证安全** — 每个命令都在一个单独的会话 microVM 中运行，与主机和其他会话隔离。适用于 AI 生成的代码、用户提交的代码和 CI 作业。 - **快速且有状态** — 基于快照的快速启动，以及长达 8 小时的暂停/恢复功能，使代理可以暂停一个长时间运行的会话，并在以后恢复，同时保留内存和磁盘。 - **无服务器经济** — 按需付费；无需空闲 VM 群集。 - **包含电池** — 一个 `agent_sandbox` SDK + `asb` CLI、每个沙盒的 HTTPS 端点，以及一个内置的 **MCP 服务器**，使 Claude、Cursor、Goose 等代理可以直接创建、运行和管理沙盒。 - **无需 IaC 引擎** — 基础设施使用裸 `boto3` 配置，并在本地状态文件中跟踪；无需安装或操作其他内容。 ### 用例 **超出笔记本电脑的开发者工作负载。** 多代理编排非常耗费内存 — 几个并发代理，每个代理都有自己的工具链和构建树，很快就会耗尽本地 RAM。每个沙盒在 AWS 中都有自己的 CPU/内存分配（`asb create app --cpus 2 -m 2048`），因此您可以通过添加 microVM 来扩展，而不是购买 RAM。 **本地运行不受监控的代码代理。** 代理调用 shell、安装软件包并在 microVM 内重写文件 — 而不是在您的机器上。它无法访问您的主目录，您也不需要一直坐在那里批准每个命令以确保这一点。 **您实际控制的网络。** 默认情况下，沙盒从镜像中获取托管的出口。在 `sandbox.yaml` 中定义一个 VPC 出口连接器（`network.egress`），每个出站连接都通过您拥有的安全组离开，因此您可以决定工作负载可以访问哪些主机和端口。入口按沙盒选择加入，通过 SDK 的 `ingress_network_connectors`（例如 `SHELL_INGRESS`）— 除非您附加连接器，否则外部无法访问任何内容。参见 [网络](#networking)。 **通过 IAM 限定凭证，而不是将凭证嵌入镜像。** 在 `sandbox.yaml` 中使用 `role.extra_policy_arns` 将托管策略附加到 MicroVM 执行角色；然后，VM 内的代码通过该角色读取 Secrets Manager、SSM Parameter Store 或 S3 中的内容。没有长期密钥进入沙盒，妥协沙盒的影响范围是该角色允许的范围。 **在本地浏览器中查看沙盒开发服务器。** `asb forward app -r 8000 -l 8000` 在 VM 中运行一个本地反向代理，以便在沙盒内运行的 React、Vite 或 FastAPI 开发服务器在 `http://localhost:8000` 处打开。参见 [从沙盒提供 Web 应用](#5-serve-a-web-app-from-a-sandbox)。 **暂停、恢复和终止开箱即用。** `asb stop` 暂停并保留内存和磁盘，`asb start` 恢复，`asb rm` 终止。会话可以在 **8 小时** 的工作时间内保持活动状态而无需付费。 **每个代码会话一个沙盒。** 命名沙盒在本地状态中跟踪，因此多个并发会话 — 每个代理、每个分支、每个实验 — 每个会话都有自己的 microVM，彼此隔离且可独立暂停。 **一个镜像，多个 VM。** 构建一次 guest 镜像（`asb image build ./guest`），然后根据需要创建多个 microVM — 不同的工作负载，相同的可复制基础，无需为每个沙盒重建。 **一键启动后端。** `asb infra up` 使用裸 `boto3` 配置 MicroVM 镜像、执行角色、S3 构建桶和可选的网络连接器，并在本地状态文件中记录所有内容。 ## 目录 - [为什么选择 agent-sandbox-os？](#为什么选择agent-sandbox-os) - [用例](#用例) - [组件](#组件) - [架构](#架构) - [先决条件](#先决条件) - [1. 安装 SDK/CLI](#1-安装sdkcli) - [2. 配置和部署基础设施](#2-配置和部署基础设施) - [3. 使用 SDK](#3-使用sdk) - [4. 使用 `asb` CLI](#4-使用asb-cli) - [5. 从沙盒提供 Web 应用](#5-从沙盒提供-web-应用) - [环境变量](#环境变量) - [从 AI 代理（MCP）使用](#从ai-代理mcp使用) - [Guest 代理和生命周期钩子](#guest-代理和生命周期钩子) - [使用您自己的 Guest 镜像](#使用您自己的guest-镜像) - [本地 Guest 镜像烟雾测试](#本地guest-镜像烟雾测试) - [状态 / 尚未实施](#状态--尚未实施) - [贡献](#贡献) - [许可证](#许可证) ## 组件 | 组件 | 描述 | | --- | --- | | 运行时 | AWS Lambda MicroVMs（托管 Firecracker）通过 `boto3` `lambda-microvms` | | Guest 代理 | `guest/agentd` — FastAPI **agentd**（执行/文件系统 API，端口 8080）加上一个**生命周期钩子**服务器（端口 9000），通过 `agentd.serve` 一起运行并嵌入到 MicroVM 镜像中 | | SDK | `agent_sandbox.Sandbox.create(...)` | | 传输 | `agent_sandbox.agent_client.AgentClient`（HTTPS + `X-aws-proxy-auth`） | | CLI | `asb` | | 基础设施 | `asb infra`（裸 `boto3` 配置器，`agent_sandbox.infra`）由 `sandbox.yaml` 驱动；PyYAML 包含在基本安装中 | | MCP 服务器 | `agent_sandbox_mcp`（FastMCP 服务器，可选 `[mcp]` 额外功能，通过 `asb mcp` 启动） | ## 架构 ```mermaid graph TD subgraph app [您的应用程序] SDK["agent_sandbox SDK / asb CLI"] end subgraph aws [lambda-microvms 控制平面] CP["运行 / 暂停 / 恢复 / 终止 + 身份验证令牌"] end subgraph vm [来自快照的 MicroVM] AG["agentd: 执行，fs.read，fs.write (:8080)"] HK["生命周期钩子：就绪 / 验证 / 运行 / 恢复 / 暂停 / 终止 (:9000)"] end SDK -->|"boto3"| CP CP -->|"ID + HTTPS URL"| SDK SDK -->|"HTTPS + X-aws-proxy-auth"| AG CP -->|"生命周期钩子（仅限平台）"| HK ``` ## 先决条件 - Python 3.11+，[`uv`](https://docs.astral.sh/uv/) - 包含 `lambda-microvms` 的 AWS CLI v2，且已配置凭证 - Docker（仅用于本地测试 guest 镜像；构建本身在 AWS 中进行） - Lambda MicroVMs 可用的区域：`us-east-1`、`us-east-2`、`us-west-2`、`eu-west-1`、`ap-northeast-1`。在 `sandbox.yaml` 中或使用标准 `AWS_DEFAULT_REGION` / `AWS_REGION` 环境变量选择其中一个。 无需 IaC 引擎或外部 CLI — `asb infra` 使用 `boto3`（核心依赖项）配置所有内容，并在本地 JSON 文件中跟踪状态。 ## 1. 安装 SDK/CLI 克隆存储库并使用 [`uv`](https://docs.astral.sh/uv/)（推荐）或 `pip` 安装： ```bash git clone https://github.com/dhanababum/agent-sandbox-os.git cd agent-sandbox-os uv sync # SDK + CLI + 基础设施（PyYAML 是基本依赖项） uv sync --extra mcp # + MCP 服务器（FastMCP）— 参见下面的 MCP 部分 uv sync --extra isal # + 更快的 ISA-L guest 镜像压缩（可选加速器） # 或，在虚拟环境中使用 pip： # pip install -e . # SDK + CLI + 基础设施 # pip install -e ".[mcp]" # + MCP 服务器 ``` 这会在您的 `PATH` 上安装 `asb` 命令。验证使用 `asb --help`。 > 基础设施支持（`asb infra`，读取 `sandbox.yaml`）包含在基本安装中 — 无需额外功能。旧的 `[infra]` 额外功能仍然可以解析，但现在是一个空操作。 ## 2. 配置和部署基础设施 所有基础设施变量都存储在单个 `sandbox.yaml` 文件中。每个资源都是 **reuse-or-create**：设置现有 ID/ARN 以重用它，或留空让 `asb infra` 创建它。 ```bash asb infra init # 搭建 sandbox.yaml（根据需要编辑） asb infra preview # 查看将要更改的内容 asb infra up # 创建/更新；打印输出（image_arn、role、...） ``` `sandbox.yaml`（由 `asb infra init` 创建）： ```yaml project: agent-sandbox-os stack: dev region: us-east-1 image: name: agent-sandbox-guest guest_dir: ./guest # 压缩 -> S3 -> create_microvm_image base_image_arn: "" # 留空 -> 最新托管基础镜像（例如 al2023） base_image_version: "" # 可选 role: arn: "" # 设置 -> 重用；留空 -> 创建 name: agent-sandbox-exec extra_policy_arns: [] # 可选的托管策略 ARN bucket: name: "" # 设置 -> 重用；留空 -> 创建 network: # 可选。完全省略以使用默认公共出口。 egress: # VPC 出口网络连接器（重用或创建）。 connector_arn: "" # 设置 -> 重用；留空 -> 创建 VPC_EGRESS 连接器 name: agent-sandbox-egress # 创建的连接器名称（+ 安全组） vpc_id: "" # 留空 -> 默认 VPC subnet_ids: [] # 子网 ID 或名称标签；留空 -> 在 VPC 中发现 security_group_id: "" # 设置 -> 重用；留空 -> 创建仅出口安全组 operator_role_arn: "" # 设置 -> 重用；留空 -> 创建 NetworkConnectorOperatorRole ``` `asb infra` 是一个裸 `boto3` 配置器（在 `agent_sandbox.infra` 下）；每个资源都是幂等创建的，并在本地 JSON 状态文件中记录，因此无需 IaC 引擎或外部 CLI。 其他基础设施命令：`asb infra refresh`、`asb infra destroy`、`asb infra output [NAME]`。使用 `asb infra up --rebuild` 强制创建新的 MicroVM 镜像版本，即使已经有一个活动版本。 ### 状态文件（无需帐户或令牌） `asb infra` 在本地 JSON 文件 `~/.agent_sandbox/infra-state.json` 中记录它创建的内容 — 以及每个资源是由它创建（托管）还是从您的 `sandbox.yaml` 中重用。`asb infra destroy` 只会销毁它管理的资源，因此重用的资源将保持不变。该文件还包含 SDK/CLI 自动连接的输出（`image_arn`、`execution_role_arn`、`build_bucket`）。 ## 3. 使用 SDK 在 `asb infra up` 之后，CLI 会自动从堆栈中读取 `image_arn`、`execution_role_arn` 和任何网络输出。对于原始 SDK，您可以依赖它，也可以显式导出环境变量： ```bash export AGENT_SANDBOX_IMAGE_ARN=$(asb infra output image_arn) export AGENT_SANDBOX_EXECUTION_ROLE_ARN=$(asb infra output execution_role_arn) python examples/run_code.py # -> Hello from a microVM! ``` 在 Windows PowerShell 上，使用 `$env:` 代替 `export`: ```powershell $env:AGENT_SANDBOX_IMAGE_ARN = (asb infra output image_arn) $env:AGENT_SANDBOX_EXECUTION_ROLE_ARN = (asb infra output execution_role_arn) python examples/run_code.py ``` ```python import asyncio from agent_sandbox import Sandbox async def main(): sandbox = await Sandbox.create("my-sandbox", cpus=1, memory=512) out = await sandbox.exec("python", ["-c", "print('hi')"]) print(out.stdout_text) await sandbox.stop() asyncio.run(main()) ``` ## 4. 使用 `asb` CLI 在 `asb infra up` 之后， `--image`/`--role` 由堆栈自动读取，因此大多数命令不需要标志： ```bash # 生命周期（在本地状态中跟踪的命名沙盒） asb create app # 从基础设施输出中自动连接镜像/角色 asb exec app -- python -c "import this" asb ls # 所有跟踪的沙盒 + 实时状态 asb ps app # 一个沙盒的状态 asb inspect app # 完整的 MicroVM 信息作为 JSON asb logs app # CloudWatch 日志（尽力而为） asb metrics app # CloudWatch 指标（尽力而为） asb stop app # 暂停（保留内存/磁盘） asb start app # 恢复 asb rm app # 终止 + 从本地状态中删除 # 临时一次性（镜像 ARN 是必需的位置参数 — 未自动连接） asb run "$(asb infra output image_arn)" -- python -c "print('one-shot')" # 在 localhost 上提供沙盒内部的端口（参见第 5 节） asb forward app --remote-port 8000 --local-port 8000 # 镜像 asb image build ./guest --name my-guest --bucket "$(asb infra output build_bucket)" asb image ls # 您的镜像（--managed 用于 AWS 基础镜像，--json 用于原始输出） asb image rm <image-arn> # 基础设施 asb infra init | preview | up | refresh | destroy | output [NAME] # 通过 stdio 运行 MCP 服务器（参见 MCP 部分） asb mcp ``` **常见标志** - `asb create` / `asb run`： `--image/-i`、 `--role`、 `--cpus`、 `--memory/-m` （默认 512）、 `--region` 和 `--egress-connector <arn>` / `--egress/-e` （附加基础设施输出中的出口连接器）。 - 每个生命周期/状态命令都接受 `--region`。 - `asb logs`： `--log-group` 以覆盖 CloudWatch 组。 - `asb image ls`： `--managed` （AWS 基础镜像）、 `--json` （原始输出）。 - `asb forward`： `--remote-port/-r` （必需）、 `--local-port/-l`、 `--no-verify-tls`、 `--poll-interval`。保留的生命周期钩子端口（`AGENT_SANDBOX_HOOK_PORT`，默认为 `9000`）被拒绝 — 参见 [Guest 代理和生命周期钩子](#guest-代理和生命周期钩子)。 - `asb infra up`： `--file/-f` 可重复并接受目录（多项目），以及 `--stack/-s`、 `--rebuild`、 `--parallelism/-p`。 `asb create` 从标志 → 环境变量（`AGENT_SANDBOX_IMAGE_ARN` / `AGENT_SANDBOX_EXECUTION_ROLE_ARN`）→ `asb infra` 输出中解析，在顺序上，因此在 `asb infra up` 之后，大多数命令不需要标志。`asb run` 是例外：它将镜像 ARN 作为必需的位置参数，不会自动连接。 CLI 在 `~/.agent_sandbox/state.json` 处维护一个本地名称 → MicroVM 映射（通过 `AGENT_SANDBOX_STATE` 覆盖），因为 AWS 没有沙盒名称的概念。 > `image inspect` 和 `image prune` 仅作为 **MCP 工具** 可用，而不是作为 `asb` CLI 命令。 ### 网络 Lambda MicroVMs 使用 **网络连接器**（而非子网/安全组）进行入口/出口， 在 `run_microvm` 时附加。从镜像中，MicroVM 默认获取托管的出口（例如 `INTERNET_EGRESS`），因此 `asb create` / `run` 无需网络配置。 对于自定义 VPC 出口，在 `sandbox.yaml` 的 `network.egress` 块中配置一个连接器（`asb infra up` 创建/记录 `egress_network_connector_arn`），然后通过 `asb create app --egress` （从基础设施输出中提取连接器）或 `--egress-connector <arn>` 附加到每个沙盒。SDK 接受 `ingress_network_connectors` / `egress_network_connectors` 以实现更精细的控制（例如 `SHELL_INGRESS`）。 ### CLI 语义 - `asb stop` **暂停**（使用 `asb start` 恢复）；`asb rm` **终止**。 - `asb image build` 压缩一个目录，将其上传到 S3，并注册一个 MicroVM 镜像（AWS 上没有本地 OCI 缓存）。 - `asb logs` / `asb metrics` 读取 CloudWatch（尽力而为；使用 `--log-group` 覆盖日志组）。 ## 5. 从沙盒提供 Web 应用 `asb forward` 运行一个本地反向代理，以便您可以通过浏览器访问在沙盒 **内部** 运行的服务。[examples/serve_fastapi.py](examples/serve_fastapi.py) 脚本演示了完整的流程：它将一个小型 FastAPI 应用写入 VM，启动 `uvicorn`，并将 `http://localhost:8000` 代理到它。 ```bash python examples/serve_fastapi.py # 然后打开 http://localhost:8000 # 或转发您自己启动的服务的端口： asb forward app --remote-port 8000 --local-port 8000 ``` ## 环境变量 SDK 和 CLI 主要通过 `sandbox.yaml` 和 `asb infra` 输出进行配置，因此 **大多数设置不需要环境变量**。以下两个变量是必须可解析的；其他所有变量都是可选的覆盖。 **必填** — 每个变量需要以下之一：CLI 标志、环境变量或 `asb infra up` 输出（自动连接）。在 `asb infra up` 之后，两个变量都是自动连接的。 | 变量 | 用途 | | --- | --- | | `AGENT_SANDBOX_IMAGE_ARN` | `asb create` / `asb run` 和 SDK 使用的 MicroVM 镜像 ARN | | `AGENT_SANDBOX_EXECUTION_ROLE_ARN` | MicroVM 的执行角色 ARN | AWS 凭证和区域来自标准 boto3 链（`AWS_REGION` / `AWS_DEFAULT_REGION`、`AWS_PROFILE`、实例角色等）。区域必须是 Lambda MicroVMs 可用的区域（参见先决条件）。 **可选覆盖** | 变量 | 默认值 | 用途 | | --- | --- | --- | | `AGENT_SANDBOX_REGION` | boto3 默认值 | SDK / MCP 调用区域 | | `AGENT_SANDBOX_STATE` | `~/.agent_sandbox/state.json` | CLI 名称 → MicroVM 映射 | | `AGENT_SANDBOX_INFRA_STATE` | `~/.agent_sandbox/infra-state.json` | `asb infra` 状态文件 | | `AGENT_SANDBOX_SETUP` | `sandbox.yaml` | 基础设施配置路径（搜索顺序： `$AGENT_SANDBOX_SETUP` → `sandbox.yaml` → 旧版 `setup.yaml`） | | `AGENT_SANDBOX_EGRESS_CONNECTOR` | 来自基础设施输出 | 要附加的 VPC 出口网络连接器 ARN | | `AGENT_SANDBOX_WORKDIR` | `/work` | VM 内的默认工作目录 | | `AGENT_SANDBOX_VERIFY_TLS` | `1` | 将 `0` 设置为跳过对 MicroVM 端点的 TLS 验证（仅限调试） | | `AGENT_SANDBOX_AGENT_PORT` | `8080` | 代理应用程序端口，SDK 将身份验证令牌范围限定到此处（必须与 guest 的 `AGENTD_PORT` 匹配） | | `AGENT_SANDBOX_HOOK_PORT` | `9000` | 保留的生命周期钩子端口；`asb forward` 拒绝它（必须与 guest 的 `AGENTD_HOOK_PORT` 匹配） | MCP 服务器添加了一组额外的 `AGENT_SANDBOX_MCP_*` 调整旋钮 - 请参见下面 MCP 部分下的[配置](#configuration)。 ## 从 AI 代理（MCP）使用它 `agent-sandbox-os` 附带一个 [MCP](https://modelcontextprotocol.io/) 服务器（`agent_sandbox_mcp`），允许 AI 代理创建隔离的 MicroVM 沙盒，执行代码，管理文件，读取日志和监控资源。它镜像了 [microsandbox-mcp](https://github.com/superradcompany/microsandbox-mcp) 的工具命名约定和响应模式，但使用 Python 和 **FastMCP** 在 `agent_sandbox` SDK 之上构建。 ### 安装 MCP 服务器包含在可选的 **`mcp` 额外功能**中。**必须**安装它 - 没有它，`asb mcp` 立即退出，客户端报告 **"连接失败"**。通过以下方式之一安装： **源代码 checkout（开发）：** ```bash uv sync --extra mcp # 或，使用 pip：pip install -e '.[mcp]' ``` **全局工具（因此 `asb` 在任何地方都在您的 `PATH` 上）** - 包括 `[mcp]` 额外功能： ```bash # 从源代码 checkout（可编辑 - 跟踪您的工作树）： uv tool install --editable ".[mcp]" --force # 或从 PyPI： uv tool install "agent-sandbox-os[mcp]" ``` > **注意：** 每次您（重新）安装全局工具时，请保留 `[mcp]` 额外功能。`uv tool install --reinstall .` **不带** `[mcp]` 会删除 `mcp` 包并破坏 `asb mcp` - 重新运行上述命令并添加 `.[mcp]` 即可修复。 验证它是否已安装并可访问： ```bash asb mcp # 启动stdio服务器（Ctrl+C停止）。如果出现 "mcp不可用" # 消息，则表示缺少[mcp]额外功能 - 参见上文。 which asb # 例如 ~/.local/bin/asb - 如果您的MCP客户端 # 在不同环境中运行且无法在PATH上找到asb，请使用此绝对路径。 ``` 首先配置后端（`asb infra up`），以便解析镜像/角色ARN，或者设置 `AGENT_SANDBOX_IMAGE_ARN` / `AGENT_SANDBOX_EXECUTION_ROLE_ARN`（参见 [环境变量](#environment-variables)）- 否则客户端连接但运行时工具调用出错。 服务器在stdio上运行，可以通过三种方式启动 - 使用最方便您的客户端： - `asb mcp` - 通过捆绑的CLI（推荐）。 - `agent-sandbox-mcp` - 独立的控制台脚本（相同的服务器）。 - `python -m agent_sandbox_mcp` - 模块形式，当`asb`不在`PATH`上时很方便。 下面的所有客户端代码段都使用 `asb mcp`。如果您的MCP客户端在与shell不同的环境中运行（因此`asb`不在其`PATH`上），请替换为 `asb`的绝对路径，或使用 `uv run --directory /path/to/agent-sandbox-os asb mcp`。通过客户端的 `env`块传输所需的ARN时，请确保它们已经导出，如下面的通用示例所示。 **Claude 代码** ```bash claude mcp add agent-sandbox -- asb mcp ``` **Claude Desktop** - 添加到 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`）： ```json { "mcpServers": { "agent-sandbox": { "command": "asb", "args": ["mcp"] } } } ``` **Cursor** - 添加到 `~/.cursor/mcp.json`（或 `.cursor/mcp.json` 在项目中）： ```json { "mcpServers": { "agent-sandbox": { "command": "asb", "args": ["mcp"] } } } ``` **VS Code** - 添加到 `.vscode/mcp.json`： ```json { "servers": { "agent-sandbox": { "command": "asb", "args": ["mcp"] } } } ``` **Windsurf** - 添加到 `~/.codeium/windsurf/mcp_config.json`（与Cursor/Claude Desktop相同的`mcpServers`形状）： **Goose** - Goose使用YAML配置。运行 `goose configure` → *添加扩展* → *命令行扩展* 并输入 `asb mcp`，或在 `~/.config/goose/config.yaml` 中添加一个条目： ```yaml extensions: agent-sandbox: enabled: true type: stdio cmd: asb args: [mcp] ``` **pi / 任意stdio客户端** - 大多数客户端共享相同的形状。此通用块还显示了在客户端环境中未导出的情况下，通过 `env` 连接所需的ARN： ```json { "mcpServers": { "agent-sandbox": { "command": "asb", "args": ["mcp"], "env": { "AGENT_SANDBOX_IMAGE_ARN": "arn:aws:lambda:us-east-1:...:microvm-image/...", "AGENT_SANDBOX_EXECUTION_ROLE_ARN": "arn:aws:iam::...:role/agent-sandbox-exec" } } } } ``` ### 可用工具 每个工具都返回一个JSON信封：成功时 `{ "ok": true, "data": ... }`，失败时 `{ "ok": false, "error": { "code", "message", ... } }`。大命令输出、日志和文件读取默认情况下会被限制，并且包含截断元数据（`truncated`、`total_bytes`、`returned_bytes`）。 **运行时** | 工具 | 描述 | | --- | --- | | `runtime_check` | 检查boto3、`lambda-microvms`客户端、AWS凭证和解析的镜像/角色ARN | | `runtime_install` | 解释如何配置后端（`asb infra up`）；报告当前状态 | **沙盒生命周期** | 工具 | 描述 | | --- | --- | | `sandbox_run` | 创建一个临时沙盒，运行shell命令，返回输出，然后删除它 | | `sandbox_create` | 创建并启动一个持久的、命名的沙盒，在本地状态中跟踪 | | `sandbox_start` | 恢复一个停止（暂停）的沙盒 | | `sandbox_list` | 列出跟踪的沙盒，带有实时状态 | | `sandbox_status` | 显示一个沙盒的状态或所有跟踪的沙盒的状态 | | `sandbox_inspect` | 返回一个沙盒的完整控制平面配置/元数据 | | `sandbox_stop` | 暂停一个沙盒（保留状态） | | `sandbox_remove` | 终止一个沙盒并将其从本地状态中删除 | | `sandbox_wait` | 等待沙盒达到终端或目标状态 | **命令执行** | 工具 | 描述 | | --- | --- | | `sandbox_exec` | 执行带有cwd、env和timeout的argv命令 | | `sandbox_shell` | 执行shell命令字符串（`bash -lc`）并带有相同的控件 | **日志** | 工具 | 描述 | | --- | --- | | `sandbox_logs_read` | 读取捕获的CloudWatch日志，带有tail、since和grep过滤器 | | `sandbox_logs_stream` | 使用光标和有限的follow超时轮询捕获的日志 | **文件系统** | 工具 | 描述 | | --- | --- | | `sandbox_fs_read` | 读取一个沙盒文件为UTF-8文本或base64字节 | | `sandbox_fs_write` | 将UTF-8文本或base64字节写入一个沙盒文件 | | `sandbox_fs_list` | 列出沙盒目录条目 | | `sandbox_fs_mkdir` | 创建一个沙盒目录 | | `sandbox_fs_remove` | 删除一个沙盒文件或目录 | | `sandbox_fs_copy` | 在沙盒内复制文件或目录 | | `sandbox_fs_rename` | 重命名/移动一个沙盒文件或目录 | | `sandbox_fs_stat` | 获取沙盒路径元数据 | | `sandbox_fs_exists` | 检查沙盒路径是否存在 | | `sandbox_fs_copy_from_host` | 将允许列出的主机路径复制到沙盒中 | | `sandbox_fs_copy_to_host` | 将沙盒路径复制到允许列出的主机目标 | **指标** | 工具 | 描述 | | --- | --- | | `sandbox_metrics` | 获取一个沙盒的实时CPU/内存指标 | | `sandbox_metrics_all` | 获取所有跟踪的沙盒的实时指标 | | `sandbox_metrics_stream` | 从一个沙盒中收集一定数量的指标样本 | **镜像** | 工具 | 描述 | | --- | --- | | `image_list` | 列出账户镜像（或`managed=true`基础镜像） | | `image_inspect` | 检查一个MicroVM镜像的ARN | | `image_remove` | 删除一个镜像，由`confirm: true`保护 | | `image_prune` | 删除任何未被任何实时MicroVM引用的镜像，由`confirm: true`保护 | ### 资源 | URI | 描述 | | --- | --- | | `agent-sandbox://runtime` | 运行时/配置状态 | | `agent-sandbox://sandboxes` | 当前沙盒库存 | | `agent-sandbox://images` | 当前账户镜像库存 | | `agent-sandbox://policy` | 有效的主机路径和危险操作策略 | | `agent-sandbox://schemas/sandbox-create` | `sandbox_create`输入的JSON模式 | ### 配置 服务器重用SDK/CLI变量（镜像/角色ARN、区域、出口连接器、TLS、工作目录）并添加这些MCP特定调整旋钮。如果您运行**自定义guest镜像**，请参阅 [Bring your own guest image → If you use MCP](#if-you-use-mcp-with-a-custom-image) 以获取MCP进程必须独立解析的环境值： | 环境变量 | 默认值 | 描述 | | --- | --- | --- | | `AGENT_SANDBOX_MCP_HOST_PATHS` | 当前工作目录 | host复制操作的`os.pathsep`-分隔的允许列表 | | `AGENT_SANDBOX_MCP_HOST_PATH_POLICY` | `allowlist` | 设置为`unrestricted`以允许任何主机路径 | | `AGENT_SANDBOX_MCP_ENABLE_DANGEROUS` | `0` | 保留用于未来危险操作；破坏性镜像操作仍需要`confirm: true` | | `AGENT_SANDBOX_MCP_MAX_OUTPUT_BYTES` | `1048576` | 命令输出、日志和文件读取的默认上限 | | `AGENT_SANDBOX_MCP_DEFAULT_TIMEOUT_MS` | `120000` | 执行样式操作的默认超时 | | `AGENT_SANDBOX_IMAGE_ARN` | 来自 `asb infra` | MicroVM镜像ARN | | `AGENT_SANDBOX_EXECUTION_ROLE_ARN` | 来自 `asb infra` | 执行角色ARN | | `AGENT_SANDBOX_REGION` | AWS 默认值 | AWS 区域 | | `AGENT_SANDBOX_EGRESS_CONNECTOR` | 来自 `asb infra` | 要附加的VPC出口网络连接器ARN | | `AGENT_SANDBOX_WORKDIR` | `/work` | VM内的默认工作目录 | | `AGENT_SANDBOX_VERIFY_TLS` | `1` | 设置`0`以跳过对MicroVM端点的TLS验证（仅限调试） | | `AGENT_SANDBOX_AGENT_PORT` | `8080` | 代理应用程序端口，MCP在此处限定auth令牌范围（必须与guest的`AGENTD_PORT`匹配） | | `AGENT_SANDBOX_HOOK_PORT` | `9000` | 保留的生命周期钩子端口；`asb forward`拒绝它（必须与guest的`AGENTD_HOOK_PORT`匹配） | ### SDK 差距 服务器保持为`agent_sandbox` SDK的薄适配器，仅公开AWS Lambda MicroVMs后端当前支持的内容。以下`microsandbox-mcp`功能未实现，因为后端没有一流的API： - **卷** (`volume_*`) - 没有命名卷API。 - **快照** (`snapshot_*`) - 仅存在`suspend/resume`，而没有内容快照。 - **SSH / SFTP** (`sandbox_ssh_*`, `sandbox_sftp_*`) - guest中没有SSH子系统。 - **流式执行会话** (`sandbox_exec_start`/`_poll`/`_write_stdin`/`_signal`/`_close`) 和`sandbox_drain` - `agentd`的`/v1/exec`是一个阻塞的，一次性的调用，因此交互式/流式会话是不可能的，除非guest端有更改。 - **扩展点** - 请参阅`sdk/agent_sandbox/`了解扩展点。 ### MCP开发 ```bash uv sync --extra dev --extra mcp # 安装mcp + 依赖项 uv run pytest tests/mcp -q # 单元测试 + stdio冒烟测试（无AWS） AGENT_SANDBOX_MCP_E2E=1 uv run python tests/mcp/e2e.py # 真实端到端测试（需要基础设施） ``` ## 客人代理&生命周期钩子 guest镜像运行**一个进程中的两个服务器**（`python -m agentd.serve`）： - **agentd** 在端口 `8080` - 应用程序API（`/v1/exec`，`/v1/fs/*`，`/healthz`）SDK/CLI通过MicroVM的身份令牌代理访问。 - **生命周期钩子** 在端口 `9000` - **仅由AWS Lambda MicroVMs平台**调用（而非由您的客户端）- 在镜像构建和MicroVM状态转换时。 钩子在不需要您采取任何措施的情况下，使沙盒更快、更安全： | 钩子 | 何时 | 为您执行的操作 | | --- | --- | --- | | `/ready` | 在镜像构建期间，在快照之前 | 等待agentd完全服务，因此快照捕获了一个准备好的代理 - 没有第一次`exec`竞争，更快的启动 | | `/validate` | 构建后，在测试VM上 | 镜像测试，以便损坏的镜像不会在构建后被发布 | | `/run` | 每个VM启动时 | 产生一个新的VM标识并重新生成随机性（解决了共享镜像的唯一性缺陷） | | `/resume` | 在`asb start`（恢复）之后 | 重新生成随机性/刷新VM状态 | | `/suspend` | 在`asb stop`挂起之前 | 排空任何正在运行的`exec`，以便命令不会在运行中冻结 | | `/terminate` | 在`asb rm`销毁之前 | 刷新日志；尽力清理 | 钩子在构建时被编译到镜像中，因此**重建以获取它们**：`asb infra up --rebuild`. **生命周期端口是保留的.** `asb forward` 拒绝 `--remote-port 9000` - 生命周期平面是平台的私有通道，绝不能被客户端访问，并且身份验证令牌仅限于应用程序端口。 **端口是可配置的**（默认为 `8080` / `9000`）。使用 `AGENTD_PORT` / `AGENTD_HOOK_PORT`（通过Dockerfile编译）覆盖guest，使用匹配的 `AGENT_SANDBOX_AGENT_PORT` / `AGENT_SANDBOX_HOOK_PORT`覆盖SDK/CLI。保持两个钩子端口值同步 - SDK告诉平台要调用哪个端口，guest必须绑定相同的端口。 ## 自制guest镜像 您不必使用捆绑的guest。`asb image build ./my-guest`（或`sandbox.yaml`中的`image.guest_dir`）接受任何带有`Dockerfile`的目录。但是，SDK，`asb` CLI和**MCP服务器**都通过相同的HTTP代理（`agentd`）访问VM，因此自定义镜像必须遵守该约定，否则`exec`/`fs` - 因此**所有MCP `sandbox_*`工具** - 将无法连接。 保持镜像正常工作： 1. **在代理端口上提供agentd API。** 您的镜像必须在`AGENTD_PORT`（默认为`8080`）上回答`POST /v1/exec`，`POST /v1/fs/read`，`POST /v1/fs/write`和`GET /healthz`。最简单的路径：基于捆绑的guest镜像，或将捆绑的`agentd`包和`serve.py`复制到您的镜像中，并保留其`CMD`（`python -m agentd.serve`）。 2. **保持代理端口在两侧对齐。** guest绑定`AGENTD_PORT`；SDK/CLI/MCP限定auth令牌范围到`AGENT_SANDBOX_AGENT_PORT`。如果更改，请同时更改 - 不匹配意味着代理无法路由到您的代理。 3. **生命周期钩子是可选的。** 要保留它们，请运行`agentd.serve`（它也启动钩子服务器），`EXPOSE`并绑定`AGENTD_HOOK_PORT`（默认为`9000`），保持`AGENT_SANDBOX_HOOK_PORT`同步，并使用`--hooks`构建（`asb infra up`会执行此操作）。删除它们，沙盒仍然有效 - 您只会失去更快的启动/每个VM的唯一性优势（上文）。 ### 如果您将MCP与自定义镜像一起使用 MCP服务器作为**自己的进程**运行，由您的MCP客户端启动 - 它**不**继承您的shell环境。因此，您覆盖的任何值也必须在MCP进程中可解析，通过客户端的`env`块传输（请参阅配置示例）。 | 环境变量 | 必须匹配 | 为什么 | | --- | --- | --- | | `AGENT_SANDBOX_IMAGE_ARN` | 您自定义镜像的ARN | MCP从中创建沙盒 | | `AGENT_SANDBOX_EXECUTION_ROLE_ARN` | 您的执行角色 | 由MicroVM承担 | | `AGENT_SANDBOX_AGENT_PORT` | 您的代理绑定端口（`AGENTD_PORT`） | MCP将执行/文件系统身份验证令牌范围限定到它 | | `AGENT_SANDBOX_HOOK_PORT` | 您guest的`AGENTD_HOOK_PORT` | 保持`asb forward`保护正确的端口 | 端口不匹配通常是MCP `sandbox_exec` / `sandbox_fs_*` "连接失败" 错误的原因。 如果有疑问，请保持默认值 (`8080` / `9000`) 并仅设置两个ARN。 ## 本地guest镜像冒烟测试 您可以在没有AWS的情况下测试`agentd`和钩子服务器： ```bash docker build --platform linux/arm64 -t agent-sandbox-guest ./guest docker run --rm -p 8080:8080 -p 9000:9000 agent-sandbox-guest curl localhost:8080/healthz curl -s localhost:8080/v1/exec -H 'content-type: application/json' \ -d '{"command":"python","args":["-c","print(1+1)"]}' # 生命周期钩子服务器（通常由AWS Lambda MicroVMs平台调用，而不是您） curl -s -o /dev/null -w '%{http_code}\n' -X POST \ localhost:9000/aws/lambda-microvms/runtime/v1/ready # -> 200 一旦agentd启动 ``` ## 状态 / 尚未实施 卷、PTY/交互式会话、网络策略/TLS-MITM和流式执行（HTTP/2 / WebSocket）等功能尚未实施。有关扩展点，请参见`sdk/agent_sandbox/`，以及这些功能在MCP服务器上如何体现（或不体现）。 ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何设置开发环境，运行测试和lint，并打开拉取请求。 ## 许可证 Apache-2.0 - 请参阅 [LICENSE](LICENSE).