@fastagent/sandbox-runtime

@fastagent/sandbox-runtime 是 FastAgent 的独立沙箱执行服务。它以独立进程方式运行，对外提供 REST 和 Socket.IO 接口，用于会话创建、命令执行、状态查询和健康检查。

适合什么场景

• 作为本地或远端 sandbox service 运行
• 给 first-party CLI 或其他外部进程提供 fastagent-sandbox 可执行入口
• 通过 @fastagent/sandbox-runtime/sdk 访问 runtime 协议客户端

安装

npm install -g @fastagent/sandbox-runtime

或者在项目内安装：

npm install @fastagent/sandbox-runtime

全局安装后可直接使用：

fastagent-sandbox

如果是项目内安装：

npx fastagent-sandbox

公开面

• 可执行入口：fastagent-sandbox
• SDK 入口：@fastagent/sandbox-runtime/sdk
• 不支持根入口 import '@fastagent/sandbox-runtime'

这个包的运行模型始终是“子进程 + HTTP / Socket.IO”。它不是给上层应用做 in-process import 的 runtime library。

最小启动要求

当前支持平台：

• macOS
• Linux

宿主机或容器运行时需要满足：

• Node.js 20+
• bash
• ripgrep (rg)
• socat

常用环境变量

export PORT=3000
export HOST=127.0.0.1
export API_KEY=your-sandbox-api-key
export FASTAGENT_SANDBOX_PROFILE=shared

FASTAGENT_SANDBOX_PROFILE 当前支持：

• shared：默认多用户服务配置
• local：单用户轻量配置，默认按需创建 worker

常见可调项：

export POOL_SIZE=30
export MIN_READY_PROCESSES=30
export SESSION_TIMEOUT=600000
export HEALTH_CHECK_INTERVAL=30000

如果显式设置 POOL_SIZE，也应显式设置 MIN_READY_PROCESSES，并保证 MIN_READY_PROCESSES <= POOL_SIZE。

Local .env Loading

fastagent-sandbox 的启动入口会预加载 dotenv/config，所以运行时会先读取进程环境，再补充本地 .env 文件中的变量。

• 默认会读取当前启动目录下的 .env
• 如果你想固定配置文件路径，可以在启动前设置 DOTENV_CONFIG_PATH
• npm 发布包现在会包含 .env.example，可以直接复制为 .env 后再启动

例如：

cp .env.example .env
fastagent-sandbox

或者：

DOTENV_CONFIG_PATH=/absolute/path/to/sandbox-runtime.env fastagent-sandbox

Sandbox Runtime Configuration

运行时启动时会从环境变量加载默认沙箱策略；这些 SANDBOX_DEFAULT_* 配置会作为每个新 session 的基线策略。

运行态隔离单元是 userId + workspaceId：

• 同一个 scope 同时只允许一个活动 session
• 重复 createSession(userId, workspaceId) 会返回现有活动 session
• 同一用户仍然可以在不同 workspace scope 上持有多个并发 session
• workspaceId 必须匹配 [a-z0-9_-]+
• session 级 config 当前只支持 network.deniedDomains

网络策略当前是 denylist 模型：

• SANDBOX_DEFAULT_DENIED_DOMAINS：逗号分隔的默认拒绝域名列表；留空表示默认不拦截出站网络
• session 级 network.deniedDomains 只会在这个基线 denylist 上继续追加，不会清空或放宽宿主机默认限制
• SANDBOX_EXTERNAL_PROXY=true：仅在你自行托管外部 Anthropic SRT 兼容代理时开启；常规直连部署保持 false

文件系统策略同样通过环境变量注入：

• SANDBOX_DEFAULT_ALLOW_READ：逗号分隔的默认可读路径列表；未设置或留空表示不额外注入 allowRead 基线
• SANDBOX_DEFAULT_ALLOW_WRITE：逗号分隔的默认可写路径列表；默认值是 /tmp
• SANDBOX_DEFAULT_DENY_READ：逗号分隔的默认读取拒绝路径，用于保护宿主机敏感目录和凭证文件
• SANDBOX_DEFAULT_DENY_WRITE：逗号分隔的默认写入拒绝路径，用于阻止覆盖 .env、SSH/AWS 凭证等敏感位置

推荐先复制发布包里的 .env.example，再按宿主机安全边界调整这些默认项。

Runtime Scope Behavior

• workspacePath 默认落在 WORKSPACE_BASE_PATH/userId/workspaceId
• sandbox-runtime 还会在内部派生 stateRoot 与 metadataRoot
• stateRoot 承载 runtime-owned HOME、XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_STATE_HOME、XDG_DATA_HOME、TMPDIR
• metadataRoot 只给 runtime 自己保存默认 scope config 等控制面元数据
• 这些 scope 根目录会被 runtime 收紧为 owner-only 权限；目录使用 0700，默认配置文件使用 0600

命令执行时还有两个重要约束：

• cwd 未指定时默认使用 session.workspacePath，显式 cwd 也必须留在该 workspace 内
• 调用方不能覆盖 HOME、XDG_*、TMPDIR；这些环境变量由 runtime 为当前 scope 强制注入

SDK 示例

import {
  createRuntimeRestClient,
} from '@fastagent/sandbox-runtime/sdk';

const restClient = createRuntimeRestClient('http://127.0.0.1:3000', 'sandbox-api-key');
const health = await restClient.healthCheck();

命令结果查询示例：

const snapshot = await restClient.getCommandResult('session-id', 'request-id');

if (snapshot.found && snapshot.terminal) {
  console.log(snapshot.status, snapshot.output);
}

@fastagent/sandbox-runtime/sdk 现在只暴露 REST client、command completion helper、错误类型和协议派生类型。 如果第三方要自建 Socket.IO 桥接，请直接基于 runtime 的 wire contract 自己实现，不要依赖 runtime 包再维护第二套高层命令状态机。

当前接口

• REST：POST /sessions、GET /sessions/:sessionId、DELETE /sessions/:sessionId、POST /sessions/:sessionId/activity、GET /sessions?userId=...、POST /commands、GET /sessions/:sessionId/commands/:requestId、GET /health、GET /pool/status、GET /metrics
• Socket.IO：auth、session.create、session.attach、session.close、command、command.signal

GET /health 返回正式 health contract：status、timestamp、uptime、version、pool。 command.signal 是针对已 accepted requestId 的 follow-up control message，当前只支持 SIGINT；如果连接断开，后续 session.attach 会把输出和中断控制重新绑定到新 socket。

accepted command 的 terminal status 为 succeeded / failed / timed_out / signaled / lost。lost 表示 runtime 已接管命令但无法确认真实子进程终局；它仍是可查询的 terminal completion。client 在收到 accepted ack 后断线时，应优先通过 GET /sessions/:sessionId/commands/:requestId 恢复结果，而不是把命令视为普通 transport rejection。