Ayuriel/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand openshell sandbox docs

Browse Source
This commit is contained in:
Peter Steinberger 2026-03-15 20:35:56 -07:00
parent ae7f18e503
commit be8fef3840
No known key found for this signature in database
3 changed files with 155 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/cli/sandbox.md
View File

@ -1,17 +1,22 @@
---
title: Sandbox CLI
summary: "Manage sandbox containers and inspect effective sandbox policy"
read_when: "You are managing sandbox containers or debugging sandbox/tool-policy behavior."
summary: "Manage sandbox runtimes and inspect effective sandbox policy"
read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
status: active
---
# Sandbox CLI
Manage Docker-based sandbox containers for isolated agent execution.
Manage sandbox runtimes for isolated agent execution.
## Overview
OpenClaw can run agents in isolated Docker containers for security. The `sandbox` commands help you manage these containers, especially after updates or configuration changes.
OpenClaw can run agents in isolated sandbox runtimes for security. The `sandbox` commands help you inspect and recreate those runtimes after updates or configuration changes.
Today that usually means:
- Docker sandbox containers
- OpenShell sandbox runtimes when `agents.defaults.sandbox.backend = "openshell"`
## Commands
@ -28,7 +33,7 @@ openclaw sandbox explain --json
### `openclaw sandbox list`
List all sandbox containers with their status and configuration.
List all sandbox runtimes with their status and configuration.
```bash
openclaw sandbox list
@ -38,15 +43,16 @@ openclaw sandbox list --json # JSON output
**Output includes:**
- Container name and status (running/stopped)
- Docker image and whether it matches config
- Runtime name and status
- Backend (`docker`, `openshell`, etc.)
- Config label and whether it matches current config
- Age (time since creation)
- Idle time (time since last use)
- Associated session/agent
### `openclaw sandbox recreate`
Remove sandbox containers to force recreation with updated images/config.
Remove sandbox runtimes to force recreation with updated config.
```bash
openclaw sandbox recreate --all # Recreate all containers
@ -64,11 +70,11 @@ openclaw sandbox recreate --all --force # Skip confirmation
- `--browser`: Only recreate browser containers
- `--force`: Skip confirmation prompt
**Important:** Containers are automatically recreated when the agent is next used.
**Important:** Runtimes are automatically recreated when the agent is next used.
## Use Cases
### After updating Docker images
### After updating a Docker image
```bash
# Pull new image
@ -91,6 +97,21 @@ openclaw sandbox recreate --all
openclaw sandbox recreate --all
```
### After changing OpenShell source, policy, or mode
```bash
# Edit config:
# - agents.defaults.sandbox.backend
# - plugins.entries.openshell.config.from
# - plugins.entries.openshell.config.mode
# - plugins.entries.openshell.config.policy
openclaw sandbox recreate --all
```
For OpenShell `remote` mode, recreate deletes the canonical remote workspace
for that scope. The next run seeds it again from the local workspace.
### After changing setupCommand
```bash
@ -108,16 +129,16 @@ openclaw sandbox recreate --agent alfred
## Why is this needed?
**Problem:** When you update sandbox Docker images or configuration:
**Problem:** When you update sandbox configuration:
- Existing containers continue running with old settings
- Containers are only pruned after 24h of inactivity
- Regularly-used agents keep old containers running indefinitely
- Existing runtimes continue running with old settings
- Runtimes are only pruned after 24h of inactivity
- Regularly-used agents keep old runtimes alive indefinitely
**Solution:** Use `openclaw sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
**Solution:** Use `openclaw sandbox recreate` to force removal of old runtimes. They'll be recreated automatically with current settings when next needed.
Tip: prefer `openclaw sandbox recreate` over manual `docker rm`. It uses the
Gateway’s container naming and avoids mismatches when scope/session keys change.
Tip: prefer `openclaw sandbox recreate` over manual backend-specific cleanup.
It uses the Gateway’s runtime registry and avoids mismatches when scope/session keys change.
## Configuration
@ -129,6 +150,7 @@ Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sand
"defaults": {
"sandbox": {
"mode": "all", // off, non-main, all
"backend": "docker", // docker, openshell
"scope": "agent", // session, agent, shared
"docker": {
"image": "openclaw-sandbox:bookworm-slim",

46
docs/gateway/configuration-reference.md
View File

@ -1200,6 +1200,14 @@ Optional sandboxing for the embedded agent. See [Sandboxing](/gateway/sandboxing
<Accordion title="Sandbox details">
**Backend:**
- `docker`: local Docker runtime (default)
- `openshell`: OpenShell runtime
When `backend: "openshell"` is selected, runtime-specific settings move to
`plugins.entries.openshell.config`.
**Workspace access:**
- `none`: per-scope sandbox workspace under `~/.openclaw/sandboxes`
@ -1212,6 +1220,39 @@ Optional sandboxing for the embedded agent. See [Sandboxing](/gateway/sandboxing
- `agent`: one container + workspace per agent (default)
- `shared`: shared container and workspace (no cross-session isolation)
**OpenShell plugin config:**
```json5
{
plugins: {
entries: {
openshell: {
enabled: true,
config: {
mode: "mirror", // mirror | remote
from: "openclaw",
remoteWorkspaceDir: "/sandbox",
remoteAgentWorkspaceDir: "/agent",
gateway: "lab", // optional
gatewayEndpoint: "https://lab.example", // optional
policy: "strict", // optional OpenShell policy id
providers: ["openai"], // optional
autoProviders: true,
timeoutSeconds: 120,
},
},
},
},
}
```
**OpenShell mode:**
- `mirror`: seed remote from local before exec, sync back after exec; local workspace stays canonical
- `remote`: seed remote once when the sandbox is created, then keep the remote workspace canonical
In `remote` mode, host-local edits made outside OpenClaw are not synced into the sandbox automatically after the seed step.
**`setupCommand`** runs once after container creation (via `sh -lc`). Needs network egress, writable root, root user.
**Containers default to `network: "none"`** — set to `"bridge"` (or a custom bridge network) if the agent needs outbound access.
@ -1261,10 +1302,7 @@ noVNC observer access uses VNC auth by default and OpenClaw emits a short-lived
</Accordion>
When `backend: "openshell"` is selected, runtime-specific settings move to
`plugins.entries.openshell.config` (for example `mode: "mirror" | "remote"` and
`remoteWorkspaceDir`). Browser sandboxing and `sandbox.docker.binds` are
currently Docker-only.
Browser sandboxing and `sandbox.docker.binds` are currently Docker-only.
Build images:

76
docs/gateway/sandboxing.md
View File

@ -59,7 +59,7 @@ Not sandboxed:
`agents.defaults.sandbox.backend` controls **which runtime** provides the sandbox:
- `"docker"` (default): local Docker-backed sandbox runtime.
- `"openshell"`: OpenShell-backed sandbox runtime provided by the bundled `openshell` plugin.
- `"openshell"`: OpenShell-backed sandbox runtime.
OpenShell-specific config lives under `plugins.entries.openshell.config`.
@ -102,6 +102,72 @@ Current OpenShell limitations:
- `sandbox.docker.binds` is not supported on the OpenShell backend
- Docker-specific runtime knobs under `sandbox.docker.*` still apply only to the Docker backend
## OpenShell workspace modes
OpenShell has two workspace models. This is the part that matters most in practice.
### `mirror`
Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local workspace to stay canonical**.
Behavior:
- Before `exec`, OpenClaw syncs the local workspace into the OpenShell sandbox.
- After `exec`, OpenClaw syncs the remote workspace back to the local workspace.
- File tools still operate through the sandbox bridge, but the local workspace remains the source of truth between turns.
Use this when:
- you edit files locally outside OpenClaw and want those changes to show up in the sandbox automatically
- you want the OpenShell sandbox to behave as much like the Docker backend as possible
- you want the host workspace to reflect sandbox writes after each exec turn
Tradeoff:
- extra sync cost before and after exec
### `remote`
Use `plugins.entries.openshell.config.mode: "remote"` when you want the **OpenShell workspace to become canonical**.
Behavior:
- When the sandbox is first created, OpenClaw seeds the remote workspace from the local workspace once.
- After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate directly against the remote OpenShell workspace.
- OpenClaw does **not** sync remote changes back into the local workspace after exec.
- Prompt-time media reads still work because file and media tools read through the sandbox bridge instead of assuming a local host path.
Important consequences:
- If you edit files on the host outside OpenClaw after the seed step, the remote sandbox will **not** see those changes automatically.
- If the sandbox is recreated, the remote workspace is seeded from the local workspace again.
- With `scope: "agent"` or `scope: "shared"`, that remote workspace is shared at that same scope.
Use this when:
- the sandbox should live primarily on the remote OpenShell side
- you want lower per-turn sync overhead
- you do not want host-local edits to silently overwrite remote sandbox state
Choose `mirror` if you think of the sandbox as a temporary execution environment.
Choose `remote` if you think of the sandbox as the real workspace.
## OpenShell lifecycle
OpenShell sandboxes are still managed through the normal sandbox lifecycle:
- `openclaw sandbox list` shows OpenShell runtimes as well as Docker runtimes
- `openclaw sandbox recreate` deletes the current runtime and lets OpenClaw recreate it on next use
- prune logic is backend-aware too
For `remote` mode, recreate is especially important:
- recreate deletes the canonical remote workspace for that scope
- the next use seeds a fresh remote workspace from the local workspace
For `mirror` mode, recreate mainly resets the remote execution environment
because the local workspace remains canonical anyway.
## Workspace access
`agents.defaults.sandbox.workspaceAccess` controls **what the sandbox can see**:
@ -110,6 +176,12 @@ Current OpenShell limitations:
- `"ro"`: mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
- `"rw"`: mounts the agent workspace read/write at `/workspace`.
With the OpenShell backend:
- `mirror` mode still uses the local workspace as the canonical source between exec turns
- `remote` mode uses the remote OpenShell workspace as the canonical source after the initial seed
- `workspaceAccess: "ro"` and `"none"` still restrict write behavior the same way
Inbound media is copied into the active sandbox workspace (`media/inbound/*`).
Skills note: the `read` tool is sandbox-rooted. With `workspaceAccess: "none"`,
OpenClaw mirrors eligible skills into the sandbox workspace (`.../skills`) so
@ -193,7 +265,7 @@ Sandboxed browser image:
scripts/sandbox-browser-setup.sh
```
By default, sandbox containers run with **no network**.
By default, Docker sandbox containers run with **no network**.
Override with `agents.defaults.sandbox.docker.network`.
The bundled sandbox browser image also applies conservative Chromium startup defaults