Sandboxing

GoClaw implements multiple layers of sandboxing to protect your system from unintended or malicious actions by the agent.

Overview

File Tools Sandbox

The read, write, and edit tools validate all paths to restrict file access.

Protections

• Workspace Containment — All paths must resolve within the workspace
• Symlink Prevention — Symlinks in paths are rejected to prevent escapes
• Denied Files — Sensitive files are always blocked, even within the workspace
• Unicode Normalization — Unicode space characters normalized to prevent confusion attacks

Denied Files

These files are blocked to protect credentials:

• users.json — User credentials and hashes
• goclaw.json — API keys and tokens
• openclaw.json — API keys and tokens
• .env — Environment secrets

User Override

Users with sandbox: false in users.json bypass path validation:

{
  "name": "Admin",
  "role": "owner",
  "sandbox": false
}

Warning: This allows the agent to access any file the GoClaw process can read/write.

Managed Exec/Browser Sandbox

GoClaw can sandbox the exec tool and managed browser launches using the platform backend:

• Linux: bubblewrap (bwrap)
• macOS: sandbox-exec (Seatbelt)

Prerequisites

Linux (bubblewrap):

# Debian/Ubuntu
sudo apt install bubblewrap

# Arch
sudo pacman -S bubblewrap

macOS uses the system sandbox-exec binary.

Sandbox Modes

GoClaw supports explicit modes. Availability depends on platform backend:

Configuration

{
  "sandbox": {
    "general": {
      "enabled": true,
      "mode": "home",
      "dataDir": "",
      "extraPaths": [],
      "execEnabled": true,
      "browserEnabled": true,
      "fileToolsEnabled": true
    },
    "bubblewrap": {
      "path": "",
      "volumes": []
    },
    "seatbelt": {
      "path": ""
    }
  }
}

Setup Wizard Security Presets

The setup wizard Security step exposes these preset labels:

Consent behavior in the wizard:

• Assistant, Permissive, and Hardened require explicit acknowledgment before continuing.
• Custom (advanced) is an explicit manual path and does not require preset consent.

Home Mode

On Linux, the default mode creates a full isolated home directory at ~/.goclaw/sandbox/home/. Agent-installed tools persist across runs, but are isolated from your real home.

On macOS, home mode is policy-managed over real home paths (Seatbelt + file-tools policy), with hidden dot-directories blocked by default.

Recommendation:

• Linux: home is the recommended default for strong isolation with persistence.
• macOS: use autodocs-read or autodocs-write when you want visible-directory-only access; use home only when broader real-home policy access is intentional.

{
  "sandbox": {
    "general": {
      "mode": "home"
    }
  }
}

Autodocs Modes

Autodocs modes expose selected real-home directories (top-level, non-hidden, non-symlinked) such as ~/Desktop, ~/Documents, ~/Pictures, and similar.

Policy scope in autodocs modes applies consistently to managed exec, managed browser launchers, and file tools:

• Visible non-hidden autodocs roots are accessible.
• Hidden dot-directories (for example ~/.ssh, ~/.goclaw) are outside allowed roots.

autodocs-read

• Exposed autodocs directories are read-only
• Writes to those roots are blocked
• Hidden directories like ~/.ssh are outside allowed roots

autodocs-write

• Same roots as autodocs-read
• Exposed autodocs directories are writable

Darwin note:

• In macOS seatbelt-backed autodocs modes, listing the home root (for example ls /Users/your-user) is allowed for discovery.
• Hidden paths remain outside allowed roots for file tools, and sensitive hidden content access remains denied by policy/rules.

Linux note:

• In Linux bubblewrap-backed autodocs modes, hidden dot-directories are not exposed in the sandbox home view.
• For hidden paths, exec may return filesystem-level errors such as ENOENT, while file tools return policy errors such as path escapes sandbox root; both are expected deny outcomes.

Volumes Mode (Linux)

Only specific directories persist. Useful when you want controlled isolation:

{
  "sandbox": {
    "general": {
      "mode": "volumes"
    },
    "bubblewrap": {
      "volumes": ["~/.local", "~/.config", "~/.npm-global"]
    }
  }
}

Ephemeral Mode (Linux)

Nothing persists between runs. Maximum security but agent-installed tools are lost:

{
  "sandbox": {
    "general": {
      "mode": "ephemeral"
    }
  }
}

What Commands Can Access

Inside the sandbox:

What Commands Cannot Access

• Hidden/sensitive home paths outside allowed roots (for example ~/.ssh, ~/.goclaw)
• Other users’ files
• Host environment variables (API keys, tokens)
• System configuration outside allowed paths

PATH Inside Sandbox

The sandbox automatically includes common user binary directories:

• ~/.local/bin
• ~/.npm-global/bin
• ~/go/bin
• ~/.cargo/bin
• ~/.bun/bin
• ~/pip-tools/bin

Add custom paths via extraPaths:

{
  "sandbox": {
    "general": {
      "extraPaths": ["/opt/mytools/bin", "~/.custom/bin"]
    }
  }
}

Enabling via Setup

Run goclaw setup edit and select “Sandbox” to configure modes and options.

Or during initial setup, the wizard detects the platform sandbox backend and offers to enable sandboxing.

Browser URL Safety

The browser tool validates URLs before navigation to prevent SSRF (Server-Side Request Forgery) attacks. This protection is always active, regardless of sandbox backend status, because filesystem sandboxing does not restrict outbound network destinations.

Blocked Destinations

Evasion Prevention

The URL safety check resolves hostnames to IPs before validation, catching common evasion techniques:

• Decimal IP encoding (2130706433 = 127.0.0.1)
• Hex IP encoding (0x7f000001 = 127.0.0.1)
• Octal encoding (0177.0.0.1 = 127.0.0.1)
• DNS rebinding (localtest.me → 127.0.0.1)
• Short forms (127.1 → 127.0.0.1)
• IPv4-mapped IPv6 (::ffff:127.0.0.1)

Allowed

Only http:// and https:// URLs to public internet addresses are allowed.

Security Considerations

Defense in Depth

The layers complement each other:

1. File tools sandbox — Prevents direct file access outside workspace
2. Managed exec/browser sandbox — Prevents shell commands from escaping
3. Isolated home — Agent tools don’t mix with your real environment

What Sandboxing Does NOT Protect Against

• Network-based attacks (network access is allowed)
• Side-channel attacks
• Bugs in the OS sandbox backend itself
• Actions within the workspace (agent can still modify workspace files)

Recommendations

1. Use home mode for general use — good balance of security and usability
2. Use autodocs-read when the agent needs common user docs/media directories but should not modify them
3. Use ephemeral mode for untrusted prompts — nothing persists
4. Use sandbox: false sparingly — only for trusted admin users
5. Review extraPaths — they become accessible inside sandbox

Troubleshooting

“bwrap not found”

Install bubblewrap on Linux (see Prerequisites above).

“namespace operation not permitted”

Some container environments restrict namespace creation:

1. Run GoClaw outside the container
2. Use --privileged flag with Docker
3. Use a different sandbox mode or disable

Commands fail inside sandbox

The command may need paths not available. Add them to extraPaths:

{
  "sandbox": {
    "bubblewrap": {
      "extraPaths": ["/opt/mytools"]
    }
  }
}

Agent-installed tools not found

In ephemeral mode, tools don’t persist. Switch to home or volumes mode.

In volumes mode, ensure the tool’s install location is in your volumes list.

See Also

• Configuration — Full config reference
• Tools — Tool documentation
• Deployment — Production setup