> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置 Sandbox 资源与网络策略

在创建 Session 前声明任务所需策略，再预检组合是否满足。配置通过只说明结构和声明兼容，真实网络限制需要云环境中的允许 / 拒绝探测证明。

## 资源字段的实际范围

当前 Session `resources` 接受 `timeout_seconds` 与 `idle_timeout_seconds`，不是任意 CPU / 内存对象。超时范围为 60—3600 秒，默认 600；空闲范围为 15—3600 秒，默认 60。实际生命周期会将 idle 阈值限制在 timeout 减十秒以内。Provider 的模板、规格和配额可能在 Sandbox 连接配置中选择，按对应连接 schema 使用。

不要把 timeout 理解为所有供应商完全相同的墙钟计费时限。持久 Provider 的期限与暂停策略不同，见[生命周期](https://github.com/NexusFox88/docs/blob/main/resources/docs/serverless-sessions.md)。

## 配置 allowlist 并预检

以下片段中的 `credential_host` / `credentialHost` 必须是当前受保护凭据通道 URL 的 hostname；不包含 scheme、端口或路径。示例目标域名用于说明，正式运行应替换为获准的目标。

```python theme={null}
definition = dict(
    harness={'id': 'pi', 'version': '1.5.2'},
    sandbox_connection_id=sandbox_connection_id,
    model_connection_id=model_connection_id,
    resources={'timeout_seconds': 600, 'idle_timeout_seconds': 60},
    network={'mode': 'allowlist', 'allowed_hosts': [credential_host, 'example.com']},
    required_capabilities=['network_allowlist'],
)
check = client.preflight_session(**definition)
if not check['ready']:
    raise RuntimeError('Preflight did not establish readiness')
session = client.create_session(**definition)
```

```typescript theme={null}
const definition = {
  harness: { id: 'pi', version: '1.5.2' },
  sandbox_connection_id: sandboxConnectionId,
  model_connection_id: modelConnectionId,
  resources: { timeout_seconds: 600, idle_timeout_seconds: 60 },
  network: { mode: 'allowlist' as const, allowed_hosts: [credentialHost, 'example.com'] },
  required_capabilities: ['network_allowlist'],
};
const check = await client.preflightSession(definition);
if (!check.ready) throw new Error('Preflight did not establish readiness');
const session = await client.createSession(definition);
```

若 Provider 不支持网络 allowlist，会拒绝 `network_policy_unsupported`；缺少凭据通道主机时出现 `credential_proxy_not_allowed_by_network_policy`。不要自动退回 unrestricted。临时入口 hostname 变化后需要重新核对配置，不能假设旧 allowlist 仍可用。

## 哪一层的策略

Sandbox 出站策略约束云环境的网络能力。Agent Tool 操作选择约束允许调用的业务操作；受保护模型和 HTTP 连接约束控制平面允许代理的目标。外部工具请求可能由控制平面发出，不能仅凭 Sandbox allowlist 推断所有 Tool 的目标都被它过滤。

`required_capabilities` 是请求必需能力，不能通过添加字符串使 Provider 获得新能力。预检还检查 Harness 模型协议、Tools、初始化和 OCI 等兼容性。当前组合结构中的 `verification.status` 为 unverified，不代表刚执行了云验收。

## 列出执行所需的全部目标

按实际执行路径构造 allowlist：受保护凭据入口、适用时的 Harness 安装/下载端点、项目所需包源，以及已授权的任务目标。模型上游可能由控制平面经受保护访问调用，仅添加模型上游域名不能替代 Sandbox 对凭据入口的访问。当前入口检查要求列表中包含精确 hostname，不能填 URL 或假定通配符能匹配。

区分控制平面预检与 Provider 对主机名规则的实现。预检不测试 DNS、重定向、依赖下载或未列入目标的实际阻断。项目可能通过结构预检，随后因为包源被阻断而安装失败。先定位被拒绝目标，再调整策略；不要为通过教程而静默改为 unrestricted。

用自己控制或获准访问的目标做允许/拒绝双向探测。先确认被拒绝目标在允许访问的对照环境中可达，否则超时可能只是目标失效。记录探测执行位置、实际策略、连接/版本、请求结果与清理。单独的 DNS 失败或代理失败不足以证明预期网络边界。

临时凭据入口 hostname 改变后，重新检查既有 Session 固定的 allowlist；目标策略变化时创建新 Session。新预检通过不会修改既有 Session，旧资源应保留对账记录直到确认清理。

## 验证真实生效

在已支持的专用组合上，从 Sandbox 对一个获准域名发出请求，再对未获准域名发出请求，核对前者成功、后者拒绝。同时确认模型凭据通道可用。记录实际执行结果、Provider 和 Harness 版本；API 接受 JSON 不足以证明网络约束生效。

若失败，区分 schema 不合法、能力不支持、通道被阻止、账户配额和云网络异常，保留资源标识并清理。依据：[请求 schema](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/sessions.ts)、[组合解析](https://github.com/NexusFox88/docs/blob/main/resources/modules/execution/compatibility.ts)。下一步：[Tools](https://docs.hexagon.autos/zh-CN/build/tools.md)、[恢复](https://docs.hexagon.autos/zh-CN/build/recovery.md)。

## 理解一次真实允许与拒绝探测

[11 月 15 日公共 API 网络旅程](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-15-network-api-journey.md)使用 TypeScript SDK 和普通 worker，在真实 E2B Sandbox 内运行已注册的确定性 Harness。无限制时 `example.com`、`example.org` 均返回 HTTP 200；采用记录中的允许列表后，`example.com` 为 200，`example.org` 为 HTTP 000、curl exit 35。探针保持不变并绕过代理环境变量，测量 Sandbox 直接出站，导出观察结果并确认两项资源删除。

成对基线支持该次允许与拒绝的结论；单独 exit 35 只能说明 TLS 或连接失败。该 Harness 未调用模型，记录不能证明当前 Pi 模型访问、Python 对等验证、全部域名、IP、IPv6、通配符或完整绕过防护。选择当前组合时应核对[Sandbox 能力](https://docs.hexagon.autos/zh-CN/integrations/sandboxes.md)与[初始化契约](https://github.com/NexusFox88/docs/blob/main/resources/docs/session-initialization.md)，将不支持时的预检拒绝与实际网络执行证据分开。

下一步：[Sandbox 能力](https://docs.hexagon.autos/zh-CN/integrations/sandboxes.md)、[能力与证据](https://docs.hexagon.autos/zh-CN/concepts/capabilities-and-evidence.md)、[配置参考](https://docs.hexagon.autos/zh-CN/reference/configuration.md)。Provider 细节见[Sandbox 集成契约](https://github.com/NexusFox88/docs/blob/main/resources/docs/sandbox-providers.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.