Cloud 托管 Sandbox

Appaloft Cloud 提供一个开箱即用的托管 Execution Sandbox：不需要注册自己的服务器，也能创建、连接、 在其中执行命令/文件/进程操作，并在使用结束后清理。它和自托管 Appaloft 使用的是同一套 Sandbox operation 与 SDK；Cloud 只是额外提供托管 worker、隔离策略和凭据代理，让你不用自己运维底层机器。

与自托管 Sandbox 的关系

Sandbox 本身是 Appaloft 的公共能力：创建、暂停/恢复、执行命令、文件传输、进程与端口管理、快照和 清理都通过同一套 CLI/HTTP/API/SDK 完成，不区分 Cloud 或自托管。Cloud 托管 Sandbox 的区别只在于 谁提供底层机器：

• 自托管：Sandbox 运行在你注册到 Appaloft 的服务器上，由你负责机器本身的可用性和成本。
• Cloud 托管：Sandbox 运行在 Appaloft Cloud 提供或代管的 worker 上；你只拿到一个 scoped Sandbox handle，看不到也不需要管理底层 VPS/SSH/Docker 细节。

如果你的组织已经在 Appaloft Cloud 中注册了自己的服务器，没有保存策略时 Cloud 会直接使用该 registered Server，不要求 managed 容量。Owner 或 Admin 仍可显式保存 registered-server 或 managed。已保存的 managed 策略在托管容量不可用时不会自动改用你的服务器。

appaloft code 的托管目标选择

登录 Appaloft Cloud 后，在 clean、已 push 的 Git repository 中运行 appaloft code：

1. 如果当前 Project 或组织保存了 registered-server 策略，只使用该组织可用的 registered Server； Project 策略优先于组织策略。
2. 如果没有保存策略，并且组织已经有一台可用的 registered Server，Cloud 使用该 Server，结果为 registered-server/platform-default。这条路径不要求 managed entitlement，也不会再 enroll 一台 新 Server。appaloft code --server <id> 仍是显式选择。
3. 如果没有保存策略，也没有可用的 registered Server，并且当前账号有 managed Workspace entitlement，Cloud 使用 managed/platform-default，并在同一次请求中创建或复用最小 Project、 Repository Binding 和默认 Workspace Profile。这个路径不要求先执行 appaloft server enroll。
4. 如果生效选择是 managed（已保存 managed 策略，或没有可用 registered Server），但 entitlement、 健康状态或容量不满足，请求会在创建 Sandbox 前显式失败。已保存的 managed 请求不会静默回退到 registered Server 或本机；要把默认改成自有机器，由 Owner/Admin 保存 registered-server 策略。

Workspace 结果、状态和 TUI 显示相同的安全证据：目标类别、选择来源和原因，例如 managed/platform-default。这些字段不会包含 Server id、host、provider handle、容量总量或凭据。

Owner/Admin 可以在 Cloud Console 的 Workspace target policy 页面修改组织或 Project 策略； Developer 可以读取生效结果但不能修改。自动化可调用：

GET /cloud/workspace-target-policy?projectId=<project-id>
PUT /cloud/workspace-target-policy

PUT body 包含 scope、targetClass、可选 projectId 和必填的 expectedRevision；首次写入使用 null。过期 revision 返回冲突，不会覆盖另一位管理员刚保存的策略。

隔离模型

Cloud 托管 Sandbox 首批可用的隔离等级是如实标记的 container-trusted：一个真实的容器边界，但不 承诺对抗恶意多租户级别的强隔离。更强的隔离等级（例如基于 gVisor 的沙箱运行时）会在可用并通过验收 后逐步开放；页面会在隔离等级变化时更新说明，不会静默把 container-trusted 包装成”完全安全隔离” 去宣传。

高风险或异常使用模式的 Sandbox 创建请求可能被 admission 策略拒绝，或被要求使用更高隔离等级。

凭据与网络边界

• Cloud 不会把底层 VPS、SSH、Docker 或服务器凭据字段暴露给调用方；你得到的始终是一个 scoped Sandbox handle 和 Appaloft 签发的 token，而不是可以直接连接底层机器的凭据。
• Sandbox 需要访问外部服务（例如模型 API、Git 凭据）时，Cloud 通过短期、目的绑定的凭据授予下发， 不会把长期密钥明文注入到 Sandbox 环境变量或日志中；凭据代理未就绪时请求会显式失败，而不是退化 成明文注入。
• Sandbox 默认没有任意公网出站权限；需要访问特定外部服务时，通过显式声明的凭据/网络能力获得, 而不是打开整个 Sandbox 的出站网络。

连接模型 provider

在 组织设置 → Agent 工作区 → 模型连接 中选择 OpenCode 或 Pi，再连接 DeepSeek、OpenAI、 Anthropic 或 OpenAI-compatible provider。模型 API key 只提交一次，由 Cloud credential vault 立即加密；列表、日志、Task input、argv 和 audit 只显示 redacted connection metadata。

Provider connection 与 Agent Adapter 是不同概念：Adapter 描述 Agent 如何运行，Model connection 提供它调用模型所需的 owner-scoped credential。不要把 key 粘贴到 Adapter/Profile manifest。 Codex 不出现在这条 Pi/OpenCode V1 设置路径中，直到它的真实 provider acceptance 完成。

使用 registered Server 上已有的 Agent 配置

existing-server-config 适合凭据已经由 owner 或组织保存在自有 registered Server 上的场景。 它不是挂载 SSH 登录用户或 root 的 HOME。Cloud Console 会返回一个 serverHomePath，例如：

/var/lib/appaloft/runtime/agent-homes/tenant_alpha/organization/org_alpha/opencode

在目标 Server 上创建这个目录并设为 0700，再从你已登录的 Agent HOME 复制所需文件。源文件必须是 普通文件、不能是 symlink、单个文件不超过 1 MiB，物化后的文件权限为 0600。

APPALOFT_AGENT_HOME=/var/lib/appaloft/runtime/agent-homes/tenant_alpha/organization/org_alpha/opencode
sudo install -d -m 700 "$APPALOFT_AGENT_HOME/.local/share/opencode"
sudo install -m 600 "$HOME/.local/share/opencode/auth.json" \
  "$APPALOFT_AGENT_HOME/.local/share/opencode/auth.json"

随后在 Cloud Console 的 Existing server config 中选择 owner、OpenCode 或 Pi、Server pool、 允许的 Project/Profile 与 unattended policy。ownerScopedHomeRef 默认按 owner 和 Agent 自动生成； 不要指向文件路径，也不要改成其他 owner。Codex 的此模式仍明确 deferred。

每个 Agent Runtime 使用独立的 /workspace/.appaloft-agent/runtime-home/<runtimeId> 作为 HOME，因此同一 Sandbox 内多个 Runtime 不会共用凭据或 session。凭据文件在同一台 registered Server 内直接复制，不经过 control-plane response、日志或 argv。Run 结束只清理对应 Runtime 的 allowlist 文件；Sandbox pause、snapshot 或 terminate 前会清理全部 Runtime 的 allowlist 文件，Agent session 和其他持久状态仍保留。恢复或控制 进程重启时会重新校验 Connection 并幂等物化。

为 Agent Workspace 配置 Remote MCP

组织 Owner 或 Admin 可以在 Cloud Console 的 Model connections 页面把外部 HTTPS MCP server 连接到 Pi 或 OpenCode Workspace：

1. 先创建一个 Named MCP credential，填写稳定名称、显示名称和 bearer token。Appaloft 只返回 opaque reference；原始 token 不会显示在响应、日志、审计、Workspace Profile 或 Sandbox 中。
2. 创建 Remote MCP Connection，选择该命名凭据，填写无用户名、密码、query 或 fragment 的 HTTPS Streamable HTTP endpoint，并分别声明允许的 read tools 与明确批准的 write tools。
3. 把 Connection 绑定到 Workspace Profile 中声明的 MCP requirement。之后用该 Profile 打开的 Workspace 会收到短期、精确到 Runtime/Run/tool 的 Gateway capability，而不是上游 endpoint 或 token。

命名 MCP 凭据属于整个组织，但不会伪装成 Agent credential 或 Model Connection。轮换凭据时 opaque reference 不变，新请求立即使用新版本；撤销凭据后，即使 Connection 仍存在，新的解析与调用也会 fail closed。撤销或禁用 Connection 会进一步 fence 已签发的访问能力。不要把 token 写进 Adapter manifest、Workspace Profile、环境变量模板或自定义启动参数。

配额与可用性

Sandbox 的并发数量、运行时长（TTL）、资源规格等由你组织当前的 entitlement 决定。达到配额上限时， 创建/恢复请求会返回明确的配额错误，而不是排队等待或静默降级；具体配额数值请以 Cloud Console 中 组织设置页面展示的当前值为准，本页不维护会随定价调整而变化的具体数字。托管 worker 的容量还会 计算仍在运行的 managed Sandbox allocation；terminate 或受控 orphan cleanup 后才释放，短期创建 reservation 不会被误当成完整的运行容量记录。

常见问题

Sandbox 和部署（Deployment）是同一个概念吗？ 不是。Deployment 面向长期运行的应用；Sandbox 面向 短时、交互式或 Agent 驱动的执行环境，有自己的暂停/恢复/快照/清理生命周期。两者可以共存，但不要 把 Sandbox 当作部署目标使用。

普通 Docker 容器和 Cloud 托管 Sandbox 有什么区别？ Cloud 托管 Sandbox 在容器边界之上叠加了 租户隔离、admission 策略、凭据代理和审计；一个裸容器不提供这些保证。

相关任务

• Agent 与 Sandbox 分组下的 Agent Workspace 页面：了解 Agent Workspace 如何使用 Sandbox 承载 运行环境。
• CLI/HTTP/API 参考：sandboxes operation 的完整命令与字段说明。