@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 的基线策略。

网络策略当前是 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，再按宿主机安全边界调整这些默认项。

SDK 示例

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

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

const socketClient = createRuntimeSocketClient({
  url: 'http://127.0.0.1:3000',
  apiKey: 'sandbox-api-key',
});

当前接口

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

GET /health 返回正式 health contract：status、timestamp、uptime、version、pool。