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

接口

Web 控制台

启动控制台栈，并了解其经过认证的 RPC 与受限 HTTP 边界。

本页内容+

启动完整栈

栈启动器会检查 Docker，启动或重启网关，重建过期的 SPA 资源，构建 sandbox-console，并使用当前网关令牌启动它。

Shell
bin/start-sandbox-console-stack
# open http://127.0.0.1:7880

使用 --skip-gateway 保留已有网关，使用 --skip-spa 保留已打包资源，或使用 --bind HOST:PORT 修改控制台 listener。默认仍只绑定 loopback，因为浏览器认证不在当前范围内。

从浏览器到网关 RPC

浏览器从不调用 CLI 或 MCP 服务器。管理、命令、文件读取/写入/编辑/归因和可观测性请求都发送到 POST /api/rpc。控制台依据公开目录校验路由，把网关令牌留在服务端，并通过共享操作客户端转发已认证 RPC。

控制台路由用途
POST /api/rpc单项公开操作；请求流式日志时使用 SSE
GET /api/catalog合并的公开管理、运行时和可观测性目录
GET /api/sandboxes/<id>/health代理守护进程存活探针
POST /api/sandboxes/<id>/files/list代理仅限 HTTP 的目录列表

受限守护进程 HTTP

每个沙箱都有独立于已认证守护进程 RPC 的 daemon_http 端点。它的精确 allowlist 是 GET /health、POST /files/list，以及 /forward/ 之下的应用转发。

文件读取/写入/编辑/归因、可观测性和导出的直接 HTTP 路径都返回 404。file_list 是唯一的 HTTP-only 操作例外；公开目录请使用 CLI、MCP 或 /api/rpc 访问网关 RPC。

从宿主机访问沙箱服务器

假设 ready 沙箱在端口 8000 提供网页。先检查沙箱，找到发布到宿主机的守护进程 HTTP 端点，再在共享命令会话中启动服务器。此示例要求沙箱镜像含 python3，宿主机含 jq。

Shell
export SANDBOX_ID=eos-abc

DAEMON_HTTP=$(
  sandbox-manager-cli inspect_sandbox --sandbox-id "$SANDBOX_ID" |
    jq -er '.daemon_http | select(. != null) | "http://\(.host):\(.port)"'
)

SERVER=$(
  sandbox-runtime-cli --sandbox-id "$SANDBOX_ID" \
    exec_command --yield-time-ms 1000 \
    "python3 -m http.server 8000 --bind 127.0.0.1 --directory ."
)

COMMAND_SESSION_ID=$(
  printf '%s\n' "$SERVER" | jq -er '.command_session_id'
)

在宿主机上用共享转发前缀打开守护进程端点。守护进程会先移除该前缀，再把请求传给沙箱服务器，因此这里的应用收到 /。

Shell
APP_URL="$DAEMON_HTTP/forward/shared/8000/"

curl --fail --show-error "$APP_URL"
printf 'Open in a browser: %s\n' "$APP_URL"

不要在宿主机打开 http://127.0.0.1:8000/，那会指向宿主机自身。请使用 inspect_sandbox 返回的随机 daemon_http 端口和 /forward/shared/8000/ 路径。向命令会话发送 Ctrl-C 可停止示例服务器：

Shell
sandbox-runtime-cli --sandbox-id "$SANDBOX_ID" \
  write_command_stdin --command-session-id "$COMMAND_SESSION_ID" \
  --yield-time-ms 1000 $'\003'

共享服务器可绑定 127.0.0.1 或 0.0.0.0。附加到隔离工作区会话的服务器必须绑定 0.0.0.0，并改用 /forward/isolated=<workspace-session-id>/<port>/。

预览路由

共享预览使用 /s/<id>/shared/<port>/...；工作区隔离预览使用 /s/<id>/isolated=<workspace-id>/<port>/...。控制台将其重写到守护进程转发 allowlist，并支持流式 body 和协议升级。

配置与安全

选择可选 console 段时，--config-yaml 优先于 SANDBOX_CONSOLE_CONFIG_YAML。绑定地址和资源目录按参数、环境变量、YAML/默认值的顺序解析；网关 socket 和令牌发现彼此独立。

预览文档拥有不透明 origin，不能调用 /api/*；令牌始终不进入浏览器。默认值见配置，运行时边界见命名空间架构。

18 个结果