npm package: @fastagent/sandbox-runtime
Description: Multi-user sandbox runtime with process pool management for FastAgent
Author: FastAgent Team
Latest version: 0.2.0

# @fastagent/sandbox-runtime

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

## 适合什么场景

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

## 安装

```bash
npm install -g @fastagent/sandbox-runtime
```

或者在项目内安装：

```bash
npm install @fastagent/sandbox-runtime
```

全局安装后可直接使用：

```bash
fastagent-sandbox
```

如果是项目内安装：

```bash
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`

## 常用环境变量

```bash
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

常见可调项：

```bash
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` 后再启动

例如：

```bash
cp .env.example .env
fastagent-sandbox
```

或者：

```bash
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 示例

```ts
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`。