Modes, scope, and backend

The mode, scope, and backend settings, how a creator-role requirement overrides agent mode, and what the runtime identity includes.

Modes, scope, and backend

Three independent settings control sandbox behavior:

Mode controls when sandboxing applies:

• off: no agent-wide sandboxing; sessions whose creator role requires a sandbox still run sandboxed.
• non-main: sandbox every session except the agent's main session. The main session key is always agent:<agentId>:main (or global when session.scope is "global"); it is not configurable. Group/channel sessions use their own keys, so they always count as non-main and get sandboxed.
• all: every session runs in a sandbox.

Set a named operator role's sandbox policy to "required" to sandbox that role's newly created sessions regardless of agent mode. The creator requirement is immutable for the session; unavailable backends fail closed, and elevated execution or Gateway/node host overrides cannot bypass it. The default "inherit" preserves existing agent-mode behavior. See Named operator roles.

Scope controls how many containers/environments are created:

• agent: one container per agent.
• session: one container per session.
• shared: one container shared by all sandboxed sessions (per-agent docker/ssh/browser overrides are ignored under this scope).

Required sandboxes with proven Gateway-profile creators use that profile as their isolation boundary. Different guests on the same agent receive separate environments and workspaces, regardless of configured scope. Sessions created by the same profile reuse its existing environment and workspace, including when the configured scope is session; this upgrade does not rekey those paths. Channel, unknown, and other non-profile creators instead receive a separate required sandbox per canonical session. A matching raw ID cannot reuse a profile's resources. Required sandboxing and the read-only workspace cap remain in force; backend failure never falls back to host execution. Sessions without a role-required sandbox keep the configured scope behavior.

The creator namespace migration does not delete or adopt old ambiguous workspaces or containers. Such sessions start with separate resources after upgrade. Preserve any needed old data before normal sandbox retention or manual cleanup, then recover selected files explicitly as an operator; do not copy an entire ambiguous environment into a trusted profile workspace automatically.

Non-shared runtime identity also includes the resolved agent workspace path. This prevents co-hosted workspaces that reuse the same agent or session keys from sharing Docker, browser, SSH, OpenShell, or plugin-provided sandbox state. shared scope intentionally remains workspace-independent.

The first use after upgrading from an older release creates non-shared runtimes and sandbox workspaces under the workspace-qualified identity. Existing non-shared runtimes are not adopted; this is an intentional one-time reset. They can age out through configured prune settings or be removed with openclaw sandbox recreate; the next use provisions the current identity.

Backend controls which runtime executes sandboxed tools. Docker and Podman share agents.defaults.sandbox.docker; SSH-specific config lives under agents.defaults.sandbox.ssh; OpenShell-specific config lives under plugins.entries.openshell.config.