diff --git a/README.md b/README.md index 039a8660a44..c8e14b25685 100644 --- a/README.md +++ b/README.md @@ -157,9 +157,9 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies. ## Security model (important) - Default: tools run on the host for the `main` session, so the agent has full access when it is just you. -- Group/channel safety: set `agents.defaults.sandbox.mode: "non-main"` to run non-`main` sessions inside per-session Docker sandboxes. +- Group/channel safety: set `agents.defaults.sandbox.mode: "non-main"` to run non-`main` sessions inside sandboxes. Docker is the default sandbox backend; SSH and OpenShell backends are also available. - Typical sandbox default: allow `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`; deny `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`. -- Before exposing anything remotely, read [Security](https://docs.openclaw.ai/gateway/security), [Docker sandboxing](https://docs.openclaw.ai/install/docker), and [Configuration](https://docs.openclaw.ai/gateway/configuration). +- Before exposing anything remotely, read [Security](https://docs.openclaw.ai/gateway/security), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing), and [Configuration](https://docs.openclaw.ai/gateway/configuration). ## Operator quick refs @@ -173,7 +173,7 @@ Run `openclaw doctor` to surface risky/misconfigured DM policies. - New here: [Getting started](https://docs.openclaw.ai/start/getting-started), [Onboarding](https://docs.openclaw.ai/start/wizard), [Updating](https://docs.openclaw.ai/install/updating) - Channel setup: [Channels index](https://docs.openclaw.ai/channels), [WhatsApp](https://docs.openclaw.ai/channels/whatsapp), [Telegram](https://docs.openclaw.ai/channels/telegram), [Discord](https://docs.openclaw.ai/channels/discord), [Slack](https://docs.openclaw.ai/channels/slack) - Apps + nodes: [macOS](https://docs.openclaw.ai/platforms/macos), [iOS](https://docs.openclaw.ai/platforms/ios), [Android](https://docs.openclaw.ai/platforms/android), [Nodes](https://docs.openclaw.ai/nodes) -- Config + security: [Configuration](https://docs.openclaw.ai/gateway/configuration), [Security](https://docs.openclaw.ai/gateway/security), [Docker sandboxing](https://docs.openclaw.ai/install/docker) +- Config + security: [Configuration](https://docs.openclaw.ai/gateway/configuration), [Security](https://docs.openclaw.ai/gateway/security), [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing) - Remote + web: [Gateway](https://docs.openclaw.ai/gateway), [Remote access](https://docs.openclaw.ai/gateway/remote), [Tailscale](https://docs.openclaw.ai/gateway/tailscale), [Web surfaces](https://docs.openclaw.ai/web) - Tools + automation: [Tools](https://docs.openclaw.ai/tools), [Skills](https://docs.openclaw.ai/tools/skills), [Cron jobs](https://docs.openclaw.ai/automation/cron-jobs), [Webhooks](https://docs.openclaw.ai/automation/webhook), [Gmail Pub/Sub](https://docs.openclaw.ai/automation/gmail-pubsub) - Internals: [Architecture](https://docs.openclaw.ai/concepts/architecture), [Agent](https://docs.openclaw.ai/concepts/agent), [Session model](https://docs.openclaw.ai/concepts/session), [Gateway protocol](https://docs.openclaw.ai/reference/rpc) diff --git a/docs/channels/groups.md b/docs/channels/groups.md index 655b0e5c764..e841ad92cf2 100644 --- a/docs/channels/groups.md +++ b/docs/channels/groups.md @@ -82,12 +82,12 @@ If you want... Yes — this works well if your “personal” traffic is **DMs** and your “public” traffic is **groups**. -Why: in single-agent mode, DMs typically land in the **main** session key (`agent:main:main`), while groups always use **non-main** session keys (`agent:main::group:`). If you enable sandboxing with `mode: "non-main"`, those group sessions run in Docker while your main DM session stays on-host. +Why: in single-agent mode, DMs typically land in the **main** session key (`agent:main:main`), while groups always use **non-main** session keys (`agent:main::group:`). If you enable sandboxing with `mode: "non-main"`, those group sessions run in the configured sandbox backend while your main DM session stays on-host. Docker is the default backend if you do not choose one. This gives you one agent “brain” (shared workspace + memory), but two execution postures: - **DMs**: full tools (host) -- **Groups**: sandbox + restricted tools (Docker) +- **Groups**: sandbox + restricted tools > If you need truly separate workspaces/personas (“personal” and “public” must never mix), use a second agent + bindings. See [Multi-Agent Routing](/concepts/multi-agent). diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 7c88a628542..bc9f20388a5 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -298,7 +298,7 @@ placeholders such as `***` or shortened token values. - Run agent sessions in isolated Docker containers: + Run agent sessions in isolated sandbox runtimes: ```json5 { diff --git a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md index c5168722f85..8051c838825 100644 --- a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md +++ b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md @@ -9,7 +9,7 @@ status: active OpenClaw has three related (but different) controls: -1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host). +1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (sandbox backend vs host). 2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**. 3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run outside the sandbox when you’re sandboxed (`gateway` by default, or `node` when the exec target is configured to `node`). diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md index aa13fa18451..5656ccc3f7b 100644 --- a/docs/gateway/sandboxing.md +++ b/docs/gateway/sandboxing.md @@ -58,7 +58,7 @@ Not sandboxed: `agents.defaults.sandbox.backend` controls **which runtime** provides the sandbox: -- `"docker"` (default): local Docker-backed sandbox runtime. +- `"docker"` (default when sandboxing is enabled): local Docker-backed sandbox runtime. - `"ssh"`: generic SSH-backed remote sandbox runtime. - `"openshell"`: OpenShell-backed sandbox runtime. @@ -79,7 +79,10 @@ OpenShell-specific config lives under `plugins.entries.openshell.config`. ### Docker backend -The Docker backend is the default runtime, executing tools and sandbox browsers locally via the Docker daemon socket (`/var/run/docker.sock`). Sandbox container isolation is determined by Docker namespaces. +Sandboxing is off by default. If you enable sandboxing and do not choose a +backend, OpenClaw uses the Docker backend. It executes tools and sandbox browsers +locally via the Docker daemon socket (`/var/run/docker.sock`). Sandbox container +isolation is determined by Docker namespaces. **Docker-out-of-Docker (DooD) Constraints**: If you deploy the OpenClaw Gateway itself as a Docker container, it orchestrates sibling sandbox containers using the host's Docker socket (DooD). This introduces a specific path mapping constraint: diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 66c0ad8a4be..ce0e4e7edc5 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -1109,7 +1109,7 @@ Dedicated doc: [Sandboxing](/gateway/sandboxing) Two complementary approaches: - **Run the full Gateway in Docker** (container boundary): [Docker](/install/docker) -- **Tool sandbox** (`agents.defaults.sandbox`, host gateway + Docker-isolated tools): [Sandboxing](/gateway/sandboxing) +- **Tool sandbox** (`agents.defaults.sandbox`, host gateway + sandbox-isolated tools; Docker is the default backend): [Sandboxing](/gateway/sandboxing) Note: to prevent cross-agent access, keep `agents.defaults.sandbox.scope` at `"agent"` (default) or `"session"` for stricter per-session isolation. `scope: "shared"` uses a diff --git a/docs/help/faq.md b/docs/help/faq.md index 6101e6c07db..9320589deda 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1293,7 +1293,7 @@ for usage/billing and raise limits as needed. Yes - if your private traffic is **DMs** and your public traffic is **groups**. - Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`. + Use `agents.defaults.sandbox.mode: "non-main"` so group/channel sessions (non-main keys) run in the configured sandbox backend, while the main DM session stays on-host. Docker is the default backend if you do not choose one. Then restrict what tools are available in sandboxed sessions via `tools.sandbox.tools`. Setup walkthrough + example config: [Groups: personal DMs + public groups](/channels/groups#pattern-personal-dms-public-groups-single-agent) diff --git a/docs/install/ansible.md b/docs/install/ansible.md index 06eebc2ff2c..c26e90e5da0 100644 --- a/docs/install/ansible.md +++ b/docs/install/ansible.md @@ -47,13 +47,15 @@ The Ansible playbook installs and configures: 1. **Tailscale** -- mesh VPN for secure remote access 2. **UFW firewall** -- SSH + Tailscale ports only -3. **Docker CE + Compose V2** -- for agent sandboxes +3. **Docker CE + Compose V2** -- for the default agent sandbox backend 4. **Node.js 24 + pnpm** -- runtime dependencies (Node 22 LTS, currently `22.14+`, remains supported) 5. **OpenClaw** -- host-based, not containerized 6. **Systemd service** -- auto-start with security hardening -The gateway runs directly on the host (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details. +The gateway runs directly on the host (not in Docker). Agent sandboxing is +optional; this playbook installs Docker because it is the default sandbox +backend. See [Sandboxing](/gateway/sandboxing) for details and other backends. ## Post-Install Setup diff --git a/docs/install/docker.md b/docs/install/docker.md index aa38e1b33e4..07a4369cbde 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -14,7 +14,7 @@ Docker is **optional**. Use it only if you want a containerized gateway or to va - **Yes**: you want an isolated, throwaway gateway environment or to run OpenClaw on a host without local installs. - **No**: you are running on your own machine and just want the fastest dev loop. Use the normal install flow instead. -- **Sandboxing note**: agent sandboxing uses Docker too, but it does **not** require the full gateway to run in Docker. See [Sandboxing](/gateway/sandboxing). +- **Sandboxing note**: the default sandbox backend uses Docker when sandboxing is enabled, but sandboxing is off by default and does **not** require the full gateway to run in Docker. SSH and OpenShell sandbox backends are also available. See [Sandboxing](/gateway/sandboxing). ## Prerequisites @@ -311,10 +311,11 @@ including binary baking, persistence, and updates. ## Agent Sandbox -When `agents.defaults.sandbox` is enabled, the gateway runs agent tool execution -(shell, file read/write, etc.) inside isolated Docker containers while the -gateway itself stays on the host. This gives you a hard wall around untrusted or -multi-tenant agent sessions without containerizing the entire gateway. +When `agents.defaults.sandbox` is enabled with the Docker backend, the gateway +runs agent tool execution (shell, file read/write, etc.) inside isolated Docker +containers while the gateway itself stays on the host. This gives you a hard wall +around untrusted or multi-tenant agent sessions without containerizing the entire +gateway. Sandbox scope can be per-agent (default), per-session, or shared. Each scope gets its own workspace mounted at `/workspace`. You can also configure diff --git a/docs/tools/skills-config.md b/docs/tools/skills-config.md index 84dfbdadc00..74f7154e3aa 100644 --- a/docs/tools/skills-config.md +++ b/docs/tools/skills-config.md @@ -122,12 +122,12 @@ Per-skill fields: ### Sandboxed skills + env vars -When a session is **sandboxed**, skill processes run inside Docker. The sandbox -does **not** inherit the host `process.env`. +When a session is **sandboxed**, skill processes run inside the configured +sandbox backend. The sandbox does **not** inherit the host `process.env`. Use one of: -- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`) -- bake the env into your custom sandbox image +- `agents.defaults.sandbox.docker.env` for the Docker backend (or per-agent `agents.list[].sandbox.docker.env`) +- bake the env into your custom sandbox image or remote sandbox environment Global `env` and `skills.entries..env/apiKey` apply to **host** runs only.