RFD: Sandbox Capability and Policy

[visionik]

Author: visionik (OpenClaw maintainer)

RFD file

docs/rfds/sandbox-capability-policy.mdx

Summary

Proposes two additive, capability-negotiated types and one relation:

• SandboxCapability — advertised by the agent in AgentCapabilities.sandbox; static per agent; describes the isolation the runtime actually enforces (mode + filesystem/network/process-capability guarantees).
• SandboxPolicy — set by the client per session via the existing acp.sandbox Session Config Option; describes the isolation the operator requires for this session's work.
• satisfies(capability, policy) — a deterministic predicate the agent evaluates at setSessionConfigOption time; rejects with a typed sandbox_policy_unsatisfiable error carrying the agent's capability if the policy cannot be met.

Motivation

ACP has no first-class model for sandbox isolation today. Implementers are reinventing it in incompatible ways:

• _meta knobs without a schema. agentpool's community reference documents claude-code-acp using _meta in NewSessionRequest for per-session configuration. Codex goes further: PR #17763 adds a codex/sandbox-state-meta experimental capability that injects SandboxState into _meta on MCP tool calls so MCPs can opt in to receiving sandbox config. These are not discoverable via capability negotiation, not versioned, and collide in namespace across agents.
• Silent host-only assumption. Codex exposes sandbox_mode as a local config.toml key (read-only / workspace-write / danger-full-access) but nothing about the agent's sandbox posture is surfaced over ACP. A client routing work to a Codex ACP session has no protocol-level way to know what isolation it is actually getting.
• Boolean collapse. OpenClaw needed to enforce that sandbox-required child sessions could not be routed to ACP backends (which run on the host). Because there was no structured capability to check, the only safe option was a hard static rejection of sandbox="require" for runtime="acp" — documented in PR #32254 and GHSA-9q36-67vc-rrwg. A boolean runsInSandbox flag would have the same problem: it cannot distinguish Docker from chroot from seccomp, or filesystem isolation from network isolation.

The capability/policy split is the standard shape for this kind of check (LSP, MCP, WASI, Kubernetes RBAC) — this RFD proposes adopting it in ACP before the ecosystem fragments further.

Relationship to in-flight work

The RFD includes a full accounting of adjacent in-flight RFDs and maintainer priorities that OpenClaw intends to adopt. This proposal covers only the one gap where no existing work was found.

What's in the file

Full proposal including: elevator pitch, status quo with concrete failure modes, typed schema for both types, the satisfies predicate, rationale for Session Config Options placement, backward compatibility analysis, SDK rollout plan, open questions, FAQ (9 questions), and alternatives considered (5 alternatives with rejection rationale).

[anna239]

@visionik hi! Have you considered having a special config option in Session Config Options? It could be a special flag, similar to how it's done for model and thinking level

[visionik]

@visionik hi! Have you considered having a special config option in Session Config Options? It could be a special flag, similar to how it's done for model and thinking level

@anna239 Yes, this proposal uses session config for two of its three components:

SandboxPolicy — set by the client per session via the existing acp.sandbox Session Config Option; describes the isolation the operator requires for this session's work.

satisfies(capability, policy) — a deterministic predicate the agent evaluates at setSessionConfigOption time; rejects with a typed sandbox_policy_unsatisfiable error carrying the agent's capability if the policy cannot be met.

the third part (not session config) is a way for an ACP server to advertise what sandboxing options it has:

SandboxCapability — advertised by the agent in AgentCapabilities.sandbox; static per agent; describes the isolation the runtime actually enforces (mode + filesystem/network/process-capability guarantees).

or am I misunderstanding your question?

Thank yoU!

[anna239]

@visionik my point is that Config options mechanism actually allows you to declare which options there are for a particular config. So I'm not quite sure how this setting is different from agent mode or f.i. thinking level