Sandbox Configuration Guide

This guide explains how to enable agent sandboxing in OpenClaw. Sandboxing isolates tool execution from the host system, providing an extra layer of security.

Note: This guide is for the openclaw-deploy repository. For the full OpenClaw sandboxing documentation, see Gateway Sandboxing.

Why Enable Sandboxing?

Without sandboxing, agent tool execution (file operations, shell commands) runs directly on your VPS. If the agent is compromised or makes a mistake, the blast radius is your entire server.

With sandboxing enabled, tools run in isolated containers or remote environments.

Security Considerations

Quick Start

To enable sandboxing, add this to your openclaw.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",           // "off", "non-main", or "all"
        "scope": "session",      // "session", "agent", or "shared"
        "workspaceAccess": "none"  // "none", "ro", or "rw"
      }
    }
  }
}

Mode Options

Scope Options

Workspace Access

Docker Sandbox Setup

The sandbox image is built automatically when you run make deploy REBUILD=1 — no manual setup required.

Per-Agent Override

You can enable sandboxing for specific agents only:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "agents": {
    "defaults": {
      "sandbox": { "mode": "off" }
    },
    "list": [
      {
        "id": "untrusted-code-review",
        "sandbox": {
          "mode": "all",
          "scope": "session"
        }
      }
    ]
  }
}

Tool Policy with Sandbox

Tool policies still apply inside sandbox. To deny specific tools even in sandbox:

1
2
3
4
5

{
  "tools": {
    "deny": ["group:runtime", "group:automation"]
  }
}

Elevated Exec (Bypasses Sandbox)

The tools.elevated setting allows certain users to run exec on the host, bypassing sandboxing. This is an escape hatch — use with caution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "tools": {
    "elevated": {
      "enabled": true,
      "allowFrom": {
        "telegram": ["<your-user-id>"]
      }
    }
  }
}

Troubleshooting

Sandbox container not starting

1
2
3
4
5

# Check sandbox status
docker ps -a | grep openclaw-sandbox

# Check logs
docker logs <container-id>

Permission errors

Ensure your workspace directory is owned by the correct UID:

1

sudo chown -R 1000:1000 ~/.openclaw/workspace

See Also

• OpenClaw Sandboxing Docs
• OpenClaw Security
• OpenShell Backend