指南
Daemon
API
博客
版本
指南
Daemon
API
博客
简体中文

从 1.x 迁移

aiod 替代 1.x Python 服务器。预构建镜像的公开端口和网关不变，多数客户端只需切换镜像标签。

v1 端点集的参考文档在 v1 API 参考。v2 端点集在 API 参考。

用预构建镜像迁移

把 ghcr.io/agent-infra/sandbox:latest（1.x AIO 镜像）换成 aio-daemon；GUI 用户可使用 aio-computer。run 命令沿用 1.x 的参数，只多一个给 Chromium 的 --shm-size 4g；启动命令、网关端口和启动耗时见 快速开始。

然后按下面清单进行检查：

  • API key —— SANDBOX_API_KEY 仍然可用，JWT 和 ticket 已移除。见 鉴权。
  • 移除的路由 —— 调用代理映射、skills 增删改查或页面级浏览器自动化的客户端需要替换方案。见 已移除的路由。
  • SDK 覆盖面 —— v1 的 SDK 仍然覆盖大部分端点，剩下三个失败的调用发的是 daemon 不提供的方法、路由或 id。见 1.x SDK 兼容性。
  • 镜像中的默认值变更 —— Code Server 和 JupyterLab 默认关闭，默认不预热 kernel，shell 和代码后端固定为 native。见 镜像。

路由对照：v1 到 v2

Planev2v1（兼容）
命令POST /v2/commands/v1/bash/*
文件/v2/fs/*、/v2/watch/v1/file/*
终端/v2/pty/sessions/*/v1/shell/*
代码/v2/code/*/v1/code/*、/v1/jupyter/*、/v1/nodejs/*
浏览器/v2/browser/*（别名）/v1/browser/*
桌面 GUI/v2/computer/*/v1/browser/actions、/v1/display/record
MCPPOST /mcpPOST /mcp
运维/v2/sandbox、/health、/metrics/v1/sandbox、/v1/capabilities

/metrics 需要 key。

下面按 plane 列出具体路由。能力页一次只展示一种调用风格，可以通过侧栏的 API Preference 开关切换。

Commands

Operationv2v1
Run a commandPOST /v2/commandsPOST /v1/bash/exec
Read outputGET /v2/commands/{command_id}POST /v1/bash/output
Write stdinPOST /v2/commands/{command_id}/stdinPOST /v1/bash/write
KillPOST /v2/commands/{command_id}/killPOST /v1/bash/kill
Create sessionPOST /v2/commands/sessionsPOST /v1/bash/sessions/create
List sessionsGET /v2/commands/sessionsGET /v1/bash/sessions
Close sessionDELETE /v2/commands/sessions/{session_id}POST /v1/bash/sessions/{session_id}/close

v2 将每次执行建模为一个资源。POST /v2/commands 返回 command_id，可以通过 offset 增量读取输出，也可以在同一路由上以 NDJSON 流式读取。

会话是可选的，统一通过 /v2/commands/sessions 管理。v1 每次调用都使用 session_id，首次使用时隐式创建会话。

v2 还新增了 shell、args 和会话级 env。

v1 与大多数 v2 接口的返回结构：

  • success —— 请求是否成功
  • message —— 一行摘要
  • data —— 负载内容；没有时是 null
  • hint —— 可选的提示信息，否则是 null

校验失败和 1.x 一样返回 422，带 errors: [{location, message, type}]。文件类错误在 data 里带这些字段：

  • errno —— 操作系统的错误号
  • errno_name —— 它的符号名，比如 ENOENT
  • error_type —— 失败的类型：not_found、permission_denied 等
  • exception_type —— 1.x 的异常类名，比如 FileNotFoundError
  • message —— 一行摘要
  • operation —— 失败的文件操作
  • path —— 涉及的路径
  • retryable —— 重试是否可能成功

状态码约定：

  • 400 —— 请求格式错误
  • 401 —— 未携带 key 或 key 无效
  • 403 —— 操作系统层拒绝了输入
  • 404 —— 路由或对象不存在
  • 422 —— 校验失败
  • 429 —— 会话或监听器数量达到上限
  • 501 —— 此 daemon 未实现：Windows 上调用仅 Linux 的路由，或未安装 ipykernel 时调用 /v1/jupyter
  • 503 —— 能力暂时不可用

Files

操作v2v1
读取GET /v2/fs/readPOST /v1/file/read
写入POST /v2/fs/writePOST /v1/file/write
编辑POST /v2/fs/editPOST /v1/file/str_replace_editor、POST /v1/file/replace
元数据GET /v2/fs/statPOST /v1/file/stat
列目录GET /v2/fs/listPOST /v1/file/list
按名字查找GET /v2/fs/searchPOST /v1/file/find、POST /v1/file/glob
搜索内容POST /v2/fs/grepPOST /v1/file/grep、POST /v1/file/search
创建目录POST /v2/fs/mkdirPOST /v1/file/mkdir
复制POST /v2/fs/copyPOST /v1/file/copy
移动POST /v2/fs/movePOST /v1/file/move
删除POST /v2/fs/deletePOST /v1/file/delete
上传POST /v2/fs/uploadPOST /v1/file/upload
下载GET /v2/fs/downloadGET /v1/file/download
整目录 tarGET/PUT /v2/fs/tree—
创建监听器POST /v2/watchPOST /v1/file/watch
轮询监听器GET /v2/watch/{id}/pollPOST /v1/file/watch/{id}/poll
流式监听器GET /v2/watch/{id}/eventsGET /v1/file/watch/{id}/events
停止监听器DELETE /v2/watch/{id}DELETE /v1/file/watch/{id}

v2 所有调用都使用 path 字段。读取文件和列目录使用 GET，?user= 用于指定文件归属身份。

v1 混用 file 和 path 两个参数，并且每次调用都可以带 sudo。

Terminals

操作v2v1
创建会话POST /v2/pty/sessionsPOST /v1/shell/sessions/create
列出会话GET /v2/pty/sessionsGET /v1/shell/sessions
查看会话GET /v2/pty/sessions/{id}—
调整会话尺寸PATCH /v2/pty/sessions/{id}—
关闭会话DELETE /v2/pty/sessions/{id}DELETE /v1/shell/sessions/{session_id}
执行命令POST /v2/pty/sessions/{id}/execPOST /v1/shell/exec
输入POST /v2/pty/sessions/{id}/inputPOST /v1/shell/write
发信号POST /v2/pty/sessions/{id}/signalPOST /v1/shell/kill
读屏幕GET /v2/pty/sessions/{id}/screenPOST /v1/shell/view
attach WebSocketGET /v2/pty/sessions/{id}/wsGET /v1/shell/ws
匿名 shellGET /v2/pty/ws—

v2 将终端建模为 /v2/pty/sessions/{id} 下的资源。exec、input、signal、screen 和 resize 都有独立路由，WebSocket attach 还可以持久化。

v1 则通过 /v1/shell/exec {id} 和 /v1/shell/ws 完成这些操作。

Code

操作v2v1
执行POST /v2/code/executePOST /v1/code/execute
运行时信息GET /v2/code/infoGET /v1/code/info
有状态会话带 session_id 的 /v2/code/execute、GET /v2/code/sessions带 session_id 的 /v1/code/execute、/v1/jupyter/*、/v1/nodejs/*

v2 只有一个入口：POST /v2/code/execute {language, code, session_id?}，会话统一在 /v2/code/sessions 下。

v1 按语言拆成三个路由，每个路由都有自己的会话语义。

Browser

操作v2v1
浏览器 REST 工具/v2/browser/*/v1/browser/*

/v2/browser/* 是 /v1/browser/* 的别名：路由相同，body 相同。v2 不新增页面级路由，页面自动化交给 CDP 客户端，DevTools 转发交给代理层。

Desktop

操作v2v1
桌面动作/v2/computer/*/v1/browser/actions
录屏/v2/computer/record/v1/display/record

桌面能力只在 v2 提供，路径在 /v2/computer/* 下；/v1/browser/actions 和 /v1/display/record 作为 1.x 客户端的别名保留。

Sandbox

操作v2v1
沙箱信息GET /v2/sandboxGET /v1/sandbox
能力探测—GET /v1/capabilities
Python 包GET /v2/sandbox/packages?lang=pythonGET /v1/sandbox/packages/python
Node.js 包GET /v2/sandbox/packages?lang=nodejsGET /v1/sandbox/packages/nodejs

GET /v2/sandbox 用一个 JSON 对象返回身份、workspace 和能力。

/v1/sandbox 保留 1.x 的返回布局：data 是文本摘要，detail、version 和 workspace 位于顶层。

v2 中的 workspace 字段名为 workspace_dir。/v1/sandbox 还会返回 home_dir，并在顶层和 detail.system 下各保留一份，以兼容 1.x 模型。

已移除的路由

以下路由在 aiod 上已不存在，调用一律返回 404。它们分为两类：一类已整体删除，没有替代入口；另一类只是换了入口，功能仍然保留。

整体删除，没有替代：

  • /v1/skills/*（增删改查）、/v1/sandbox/hooks 与 SANDBOX_SHUTDOWN_HOOKS
  • /v1/util/convert_to_markdown
  • POST /v1/nodejs/execute 的 stdin 字段；请求体里不认识的字段会被忽略
  • /v1/sandbox/observe/*
  • 独立的 Node REPL server（DISABLE_NODEJS_REPL、NODEJS_REPL_PORT*）
  • WORKSPACE 重定位（没有 --workspace 参数）
  • /v1/browser/captcha/*、/v1/browser/state/*、/v1/browser/restart、/v1/browser/network/* 的 route/headers/scoped_headers/export_har 子路由（network/requests 仍可用）与 /v1/browser/proxy.pac

换了个入口，功能还在：

  • 运行时代理映射 API → 镜像上用静态 PROXY_MAP
  • /v1/mcp/servers、/v1/mcp/<server>/tools 等管理路由 → /mcp hub（见 下文 MCP）
  • /v1/browser/page/* 页面自动化 → 用 CDP 驱动页面（BROWSER_REMOTE_DEBUGGING_HOST/_PORT，默认 127.0.0.1:9222）；daemon 不代理 DevTools，需部署方自行暴露（镜像上由 nginx 完成）
  • POST /tickets 与 JWT 鉴权 → 改用 AIO_API_KEY（见 下文鉴权）

/v1/browser/* 的以下路由仍然提供：

  • navigate
  • screenshot
  • click
  • fill
  • evaluate
  • upload
  • config
  • cdp
  • snapshot
  • tabs
  • cookies
  • info
  • network/requests
  • actions

鉴权

AIO_API_KEY（--api-key）是唯一的凭证，可选。设了 key，除公开路由外的请求都要带上；镜像上的 SANDBOX_API_KEY 设置的也是同一个 key。

三种携带方式等价，任选其一：

  • Authorization: Bearer <key>
  • x-api-key: <key>
  • ?api_key=<key> —— 已废弃，但 WebSocket / VNC 的 URL 带不了 header，只能靠它

以下路由不需要 key：

  • /
  • /health
  • /v1/ping
  • /v1/openapi.json
  • /v2/openapi.json
  • /internal/auth

设置 key 后，其余路由（包括 /metrics）都必须携带 key。镜像网关还接受 X-AIO-API-Key。

把 key 作为 bearer token 发送：

KEY=<key>

curl -H "Authorization: Bearer $KEY" "$BASE_URL/v2/sandbox"

1.x 的 ticket / JWT 机制整体移除：POST /tickets、GET /auth、JWT_PUBLIC_KEY 校验都不再存在。以前只配了 JWT_PUBLIC_KEY 的部署现在等于没开鉴权，启动时会告警——请显式设置 AIO_API_KEY。

WebSocket 或 VNC 场景没有 header 可用，key 只能放在 URL 里，例如 ws://127.0.0.1:8091/v2/pty/sessions/SESSION_ID/ws?api_key=$KEY。

身份：user 与 AIO_DEFAULT_USER

在命令、PTY 和代码执行上，user（按请求）或 AIO_DEFAULT_USER（启动时）是执行身份。进程以该账户运行。

在文件路由上它只是归属身份。daemon 仍以自己的权限读写，新建对象归属该账户。

仅 Linux 有效。Windows 上显式传 user 返回 400，AIO_DEFAULT_USER 生效的场合返回 503。

在镜像上，daemon 以 root 运行，AIO_DEFAULT_USER=gem；命令以 gem 执行。

工作目录不是隔离边界。文件路由能触达整台主机的文件系统。隔离是容器或虚拟机的职责，不是 daemon 的。

MCP

EXTRA_MCP_SERVERS（或 --mcp-servers）注册 loopback、无状态的 streamable-HTTP MCP server。它们的工具和 10 个内置工具一起出现在 POST /mcp 上。

只接受 http://127.0.0.1|localhost|[::1] 的目标。以下会被跳过并给出告警：

  • 远程 server
  • command（stdio）server
  • 需要 session 的 server

1.x 的管理机制已移除：

  • MCP_FILTER_SERVERS
  • hidden
  • 逐条超时
  • /v1/mcp/* 管理路由

改用 /mcp 上的 tools/list 列工具。AIO 镜像上，mcp-server-browser 随浏览器一起启动。

镜像

AIO 镜像

aio-daemon 把 aiod 与 Chromium、VNC、Python 和 Node 工具链、nginx 网关打包在一起。

Computer 镜像

aio-computer 在 AIO 镜像基础上加了 XFCE 桌面和 computer-use worker。

环境变量

镜像专属环境变量：

变量默认值含义
SANDBOX_API_KEY未设置AIO_API_KEY 的别名
BROWSER_START_MODEasyncasync 异步启动浏览器，不阻塞服务就绪；auto 等待浏览器启动完成；manual（Computer 镜像默认）启动时不启动浏览器，点击桌面上的 Browser 图标后才启动
DISABLE_CODE_SERVERtrueCode Server IDE 默认关闭
DISABLE_JUPYTERtrue/jupyter 的 Lab 界面关闭；/v1/jupyter API 仍可用
EXTRA_MCP_SERVERS未设置与 --mcp-servers 相同的 registry 格式
MCP_SERVER_BROWSER_PORT8100mcp-server-browser 监听的端口
DISABLE_MCP_BROWSER未设置true 时不启动 mcp-server-browser
PROXY_SERVER / PROXY_MAP未设置静态代理映射（1.x 的运行时映射 API 已移除）
WORKSPACE账户 home必须保持为该账户的 home 目录

Computer 镜像额外带 AIO_DESKTOP=xfce 和 ENABLE_DBUS=true，后者会启动 AT-SPI 需要的 session D-Bus。Chromium 带 --force-renderer-accessibility 启动。

默认值变更

JUPYTER_POOL_SIZE 映射为 AIO_KERNEL_PREWARM：默认 0，不预热任何内核。镜像上 AIO_SHELL_BACKEND=native、AIO_CODE_BACKEND=native 是固定值，不做自动探测。

构建自定义镜像

两种起点覆盖大多数场景。在 FROM enterprise-public-cn-beijing.cr.volces.com/vefaas-public/aio-daemon:1.0.0（或 aio-computer）基础上加层，或者把 aiod 二进制复制进已有的任意镜像。见 部署。

daemon 在请求发生时才从 PATH 里解析工具。在 Dockerfile 里装好对应的包就够了：

  • 代码执行需要 Python 包和 ipykernel
  • JavaScript 需要 node
  • 搜索和终端需要 rg 和 tmux

GET /v1/capabilities 会报告镜像最终具备哪些能力。

镜像里的服务都由 supervisord 管理。新增长驻进程只需在 /opt/gem/supervisord/ 下放置一个 .conf 文件；镜像的 /etc/supervisord.conf 会 include 该目录。

生命周期钩子由镜像入口脚本执行，每个都是一段 shell 命令字符串：

  • RUN_HOOK_INIT —— 在任何东西启动之前执行
  • RUN_HOOK_PRE_SERVICES —— 在服务启动之前执行
  • RUN_HOOK_POST_READY —— 在 daemon 就绪之后执行

RUN_HOOKS_STRICT=true 让钩子失败变成致命错误（默认 false）。

daemon 刻意限制了一些能力，自定义镜像可以解除这些限制：

Daemon 的限制自定义镜像里的做法
/mcp hub 只聚合 loopback、无状态的 MCP server。把 MCP server 作为 supervisord 程序运行在镜像中，并列入 EXTRA_MCP_SERVERS。
没有运行时代理映射 API。启动时设置 PROXY_SERVER / PROXY_MAP。
没有 skills 增删改查 API。把 skill 目录放到磁盘上，AIO_SKILLS_PATH 指向它们；MCP 工具 sandbox_load_skill 会读取这些目录。
Code Server 和 JupyterLab 默认关闭。设置 DISABLE_CODE_SERVER=false（服务于 /code-server/）和 DISABLE_JUPYTER=false（服务于 /jupyter）。
daemon 从不启动浏览器。镜像负责启动 Chromium；BROWSER_EXTRA_ARGS 加启动参数，HOMEPAGE 设置起始页。
默认没有预热的 kernel。设置 AIO_KERNEL_PREWARM=1。
ref 套件（snapshot、ref 版 click/fill/upload）运行在内置的 CDP 后端上。把 AIO_AGENT_BROWSER_BIN 指向一个 agent-browser CLI 即可改由它处理；AIO 镜像自带一个。
daemon 从不启动桌面。使用 aio-computer，或者在自己的镜像里提供 X11 display，同时运行 computer-use 和 aiod。

1.x SDK 兼容性

1.x 的 SDK 调用 v1 路由，不需要修改就能对接 aiod：Python agent-sandbox 0.0.31 和 TypeScript @agent-infra/sandbox 1.0.17 已在 aiod 0.9.x 上验证。Go SDK github.com/agent-infra/sandbox-sdk-go v0.0.5 已在 aiod 0.9.2 上验证：模块与 Python 一致，方法名按 Go 习惯书写（file.GrepFiles、code.ExecuteCode、nodejs.GetInfo），下表中每个方法的表现都与对应的 Python 方法相同，失败的也是同样那三个调用。SDK 只覆盖 v1；/v2/* 通过 HTTP 调用，见 API 参考，运行中的 daemon 也在 /v2/openapi.json 提供同一份文档。

已验证的方法

模块方法
sandboxget_context、get_python_packages、get_nodejs_packages
shellexec_command 及各个 session 方法
bashexec、output、write、kill、create_session、sessions、close_session
file除 watch_events 外的全部方法：它返回 Server-Sent Events，生成的客户端会按 JSON 解析而失败（Go 上已验证），这条路由直接用 HTTP 读
jupyterexecute_code、get_info、create_session、list_sessions、delete_session
nodejsexecute_code、get_info、create_session、list_sessions、get_session、delete_session
codeexecute_code、get_info
browserget_info、screenshot、set_config、execute_action
browser_tabslist、create
browser_cookies、browser_networkget_cookies、get_requests
displayrecord

以上响应都能被 SDK 的 1.x 模型解析。TypeScript SDK 提供同样的模块，方法名为驼峰（file.grepFiles、code.executeCode、nodejs.getInfo）；sandbox、bash、shell、file、code、nodejs、browser.getInfo 和 browserTabs.list 已验证，桌面和 Jupyter 方法发出的请求与上面的 Python 方法相同。TypeScript 调用成功返回 { ok, body }，失败返回 { ok, error }，结果在 body.data。

会失败的调用

以下三个调用在请求阶段就会失败：

调用原因
nodejs.update_session发送 PATCH /v1/nodejs/sessions/{id}，daemon 返回 404
browser_tabs.activate发送 PUT，而路由只接受 POST，返回 405
browser_tabs.close参数是标签页下标，而路由按 CDP target id 定位，返回 404 no tab with id 1

close 有绕法：传标签页列表里的 id 而不是位置。Python 直接可用，TypeScript 需要一次类型断言；Go 的参数类型是 int，表达不了，只能直接用 HTTP 调这个路由。

已移除的路由

以下模块调用的路由 daemon 已不再提供，返回 404：

  • browser_page.*、browser_state.*、browser_captcha.*、browser.restart、browser.get_proxy_pac
  • mcp.list_mcp_servers、mcp.list_mcp_tools
  • skills.*
  • sandbox.list_hooks、sandbox.register_hook、sandbox.remove_hook、sandbox.observe_*
  • proxy.*
  • util.convert_to_markdown
  • auth.create_ticket