<!-- source: https://deepwiki.com/openclaw/openclaw/7.3-sandboxing-and-isolation -->

# Sandboxing & Isolation

- .env.example
- .github/workflows/docker-release.yml
- .github/workflows/install-smoke.yml
- .github/workflows/plugin-prerelease.yml
- Dockerfile
- docker-compose.yml
- docs/cli/agents.md
- docs/help/faq-models.md
- docs/install/docker-vm-runtime.md
- docs/install/docker.md
- docs/install/podman.md
- docs/providers/anthropic.md
- docs/providers/claude-max-api-proxy.md
- scripts/ci-docker-pull-retry.sh
- scripts/clawdock/README.md
- scripts/clawdock/clawdock-helpers.sh
- scripts/dev/gateway-smoke.ts
- scripts/dev/ios-node-e2e.ts
- scripts/docker/cleanup-smoke/Dockerfile
- scripts/docker/install-sh-e2e/Dockerfile
- scripts/docker/install-sh-smoke/Dockerfile
- scripts/docker/install-sh-smoke/run.sh
- scripts/docker/sandbox/Dockerfile
- scripts/docker/setup.sh
- scripts/docs-i18n/localized_links.go
- scripts/docs-i18n/localized_links_test.go
- scripts/e2e/Dockerfile
- scripts/e2e/Dockerfile.qr-import
- scripts/e2e/bun-global-install-smoke.sh
- scripts/e2e/kitchen-sink-plugin-docker.sh
- scripts/e2e/kitchen-sink-rpc-docker.sh
- scripts/e2e/kitchen-sink-rpc-walk.mjs
- scripts/e2e/onboard-docker.sh
- scripts/e2e/plugin-binding-command-escape-docker.sh
- scripts/e2e/plugin-binding-command-escape.Dockerfile
- scripts/e2e/plugins-docker.sh
- scripts/e2e/qr-import-docker.sh
- scripts/lib/docker-e2e-container.sh
- scripts/lib/docker-e2e-image.sh
- scripts/lib/docker-e2e-package.sh
- scripts/lib/openclaw-e2e-instance.sh
- scripts/lib/plugin-prerelease-test-plan.mjs
- scripts/podman/setup.sh
- scripts/run-openclaw-podman.sh
- scripts/run-opengrep.sh
- scripts/test-install-sh-docker.sh
- scripts/test-projects-serial.mjs
- src/cli/npm-resolution.test.ts
- src/cli/plugin-install-plan.test.ts
- src/cli/plugin-install-plan.ts
- src/cli/plugins-cli.install.test.ts
- src/cli/plugins-install-command.ts
- src/commands/agents.bind.commands.test.ts
- src/commands/agents.bindings.ts
- src/docker-image-digests.test.ts
- src/docker-setup.e2e.test.ts
- src/dockerfile.test.ts
- src/hooks/update.test.ts
- src/hooks/update.ts
- src/security/audit-plugins-trust.test.ts
- test/scripts/ci-docker-pull-retry.test.ts
- test/scripts/clawdock-helpers.test.ts
- test/scripts/docker-build-helper.test.ts
- test/scripts/gateway-smoke.test.ts
- test/scripts/kitchen-sink-rpc-walk.test.ts
- test/scripts/openclaw-e2e-instance.test.ts
- test/scripts/plugin-prerelease-test-plan.test.ts
- test/scripts/test-install-sh-docker.test.ts

OpenClaw employs a multi-layered sandboxing and isolation system to securely execute agent tools, primarily utilizing Docker containers, environment sanitization, network controls, and granular execution approval workflows. This page details the implementation of OpenClaw's Docker sandbox configuration, security profiles, workspace bind mount validation, and the execution approval logic.

## Sandbox Architecture Overview

OpenClaw supports multiple sandbox and execution backends, determining where commands run based on tool policy and sandbox availability.

- Local Docker Sandbox: Containerized runtime with hardened images and strict execution policies.
- Node Host (Device Nodes): Remote execution on paired devices (e.g., iOS, Android, or macOS clients) via the node.invoke RPC.
- OpenShell: A managed cloud sandbox backend offering remote isolated execution as an alternative to local Docker.

The system uses a target resolution phase to decide if a command should run on the host, in a local sandbox, or on a remote node.

### Tool Execution Isolation Flow

```

```

**Sources:**
[src/agents/bash-tools.exec-host-node.ts85-164](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node.ts#L85-L164) [src/agents/bash-tools.exec-host-node-phases.ts177-201](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L177-L201) [Dockerfile1-133](https://github.com/openclaw/openclaw/blob/fbdf5937/Dockerfile#L1-L133)

## Docker Sandbox Implementation

Docker provides the primary isolation layer for untrusted code. OpenClaw's Docker image setup emphasizes security, reproducibility, and a minimal runtime footprint.

### Dockerfile Build Strategy and Hardening

- Multi-stage build : The Dockerfile uses multi-stage builds to produce a minimal runtime image, stripping away build tools like pnpm and source code Dockerfile 4-7
- Base image pinning : Base images are pinned to SHA256 digests ( node:24-bookworm-slim@sha256:... ) to ensure reproducible and reviewed snapshots Dockerfile 12-14
- Init system : tini is utilized as the ENTRYPOINT to handle signal forwarding and prevent zombie process accumulation src/dockerfile.test.ts 64-80
- Permission normalization : The build process explicitly normalizes permissions for extensions and agent directories to 755 for directories and 644 for files Dockerfile 101-108
- Native Addon Verification : Critical native addons like matrix-sdk-crypto are verified during build to prevent runtime failures in isolated environments Dockerfile 82-97

### Docker Setup and Orchestration

The `scripts/docker/setup.sh` script handles the initial configuration of the Docker environment:

- Network Isolation : It pins gateway.bind to specific interfaces and manages allowedOrigins for the Control UI scripts/docker/setup.sh 125-155
- Non-root Execution : The system supports running in a non-root context, which is validated by smoke tests to ensure the runtime floor (Node.js 22.19.0+) is met test/scripts/test-install-sh-docker.test.ts 147-164
- Timeout Awareness : Standalone Docker smoke runs are routed through a timeout-aware helper to prevent stalled containers from consuming CI resources test/scripts/docker-build-helper.test.ts 132-137

**Sources:**
[Dockerfile1-133](https://github.com/openclaw/openclaw/blob/fbdf5937/Dockerfile#L1-L133) [src/dockerfile.test.ts30-80](https://github.com/openclaw/openclaw/blob/fbdf5937/src/dockerfile.test.ts#L30-L80) [scripts/docker/setup.sh125-155](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/docker/setup.sh#L125-L155) [test/scripts/test-install-sh-docker.test.ts147-164](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/test-install-sh-docker.test.ts#L147-L164) [test/scripts/docker-build-helper.test.ts132-137](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L132-L137)

## Exec Approval & Security Profiles

OpenClaw implements a "Human-in-the-loop" security model for shell execution. Commands are analyzed before execution to determine if they violate safety boundaries.

### Approval Analysis Logic

The `analyzeNodeApprovalRequirement` function checks several conditions [src/agents/bash-tools.exec-host-node-phases.ts57-67](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L57-L67):

- Allowlist Check : Commands are evaluated against a shell allowlist src/agents/bash-tools.exec-host-node-phases.ts 14-17
- Durable Approvals : The system checks if the exact command has a "persistent" approval from the user src/agents/bash-tools.exec-host-node-phases.ts 99-118
- Inline Eval Detection : Dangerous patterns like python3 -c "..." or node -e "..." are detected as "inline eval hits" and typically require strict approval src/agents/bash-tools.exec-host-node-phases.ts 120-132

### Approval Data Flow

```

```

**Sources:**
[src/agents/bash-tools.exec-host-node.ts85-164](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node.ts#L85-L164) [src/agents/bash-tools.exec-host-node-phases.ts57-132](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L57-L132) [src/agents/bash-tools.exec-host-node-phases.ts99-118](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L99-L118)

## Network & Bind Mount Isolation

### Network Isolation

Docker containers are configured via `docker-compose.yml` to limit network exposure. The gateway typically manages network access, while the sandbox containers can be restricted to internal-only communication or specific SSRF-safe proxies. The `gateway-network` E2E lane specifically tests these boundaries [test/scripts/docker-build-helper.test.ts79](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L79-L79)

### Bind Mount Validation

The setup scripts validate mount paths to ensure they do not contain disallowed characters or whitespace, preventing path injection or misconfiguration during the `docker compose run` phase [scripts/docker/setup.sh212-224](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/docker/setup.sh#L212-L224)

## OpenShell Cloud Sandbox

OpenShell is an alternative backend for OpenClaw that provides managed cloud sandboxes [extensions/openshell/openclaw.plugin.json1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openshell/openclaw.plugin.json#L1-L10) This allows execution in a remote, isolated environment without requiring a local Docker daemon.

- Managed Lifecycle : OpenShell handles the creation and destruction of isolated execution environments.
- Configurable : Users can configure OpenShell via the plugin settings extensions/openshell/src/config.ts 1-20
- Kitchen Sink Validation : The kitchen-sink-rpc E2E suite validates that external plugin RPC calls, such as those used by sandbox providers, maintain resource ceilings and handle teardown gracefully scripts/e2e/kitchen-sink-rpc-walk.mjs 35-37

**Sources:**
[extensions/openshell/openclaw.plugin.json1-10](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openshell/openclaw.plugin.json#L1-L10) [extensions/openshell/src/config.ts1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/extensions/openshell/src/config.ts#L1-L20) [scripts/e2e/kitchen-sink-rpc-walk.mjs35-37](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/e2e/kitchen-sink-rpc-walk.mjs#L35-L37)

## Bridge Diagrams: Code Entity Mapping

### Execution & Sandbox Components Map

```

```

### Security & Validation Map

```

```

**Sources:**
[src/agents/bash-tools.exec-host-node-phases.ts1-205](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node-phases.ts#L1-L205) [src/agents/bash-tools.exec-host-node.ts1-164](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/bash-tools.exec-host-node.ts#L1-L164) [Dockerfile1-133](https://github.com/openclaw/openclaw/blob/fbdf5937/Dockerfile#L1-L133) [scripts/e2e/kitchen-sink-plugin-docker.sh83-86](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/e2e/kitchen-sink-plugin-docker.sh#L83-L86) [test/scripts/docker-build-helper.test.ts15-21](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/docker-build-helper.test.ts#L15-L21)
