pikasTech-unidesk/docs/reference/code-agent-sandbox.md

Code Agent Sandbox

Code Agent Sandbox 是独立于 Code Queue 的沙箱微服务骨架。它负责统一记录 Codex/OpenCode/未来 agent 的运行态、适配器契约、状态恢复边界和凭证语义边界。

Boundary

• Code Agent Sandbox 不依赖 Code Queue 作为前置条件。
• Code Queue 只在后续契约接入时读取这里定义的状态机和 adapter 语义。
• 不承诺 live migration；只承诺任务状态可恢复、未开始任务可重调度、中断 attempt 可 retry/resume、结果不丢。

Runtime Modes

• full-isolation：允许 sandbox 管理自己的 config.toml、auth.json、环境变量和 token provider 切换。
• half-isolation：允许读取/写入边界由配置显式控制，适合本机调试和受限挂载。
• bridge：只读宿主现状，不改写宿主配置，不切换 token provider。

Adapter Contract

Sandbox 以 adapter 一等抽象统一下面的动作：

• start
• attach
• prompt
• steer
• interrupt
• resume
• fork
• trace
• terminal status
• artifact summary

Diagnostics

/health、/diagnostics、/trace 和 /logs 是首批只读入口。它们用于验证模式、适配器状态、恢复边界和凭证边界，不承诺连接真实 Code Queue。