OpenShell sandbox — DefenseClaw

Overview

OpenShell sandbox standalone mode is the hardened Linux topology: OpenClaw runs as the unprivileged sandbox user inside a tightly-scoped systemd unit, egress is constrained by resolv.conf and firewall rules, and DefenseClaw is the only process allowed to act as a gateway between the sandboxed agent and the internet. This page describes defenseclaw sandbox setup — the bundled provisioner that builds the sandbox environment from scratch.

When to use it

One-command setup

sudo defenseclaw sandbox setup \
  --policy default \
  --sandbox-ip 10.200.0.2 \
  --host-ip 10.200.0.1 \
  --dns 8.8.8.8,1.1.1.1 \
  --non-interactive

This is the happy path: default admission policy, host/sandbox bridge addresses, DNS settings, and automatic device pre-pairing unless --no-auto-pair is supplied.

Flags

See the autogenerated sandbox subcommand page for the complete list.

What it provisions

1. User and group: sandbox:sandbox with a home at /home/sandbox, login shell /bin/bash, empty .bashrc that auto-launches openclaw.
2. Network namespace: sandbox0 veth pair at --sandbox-ip/--host-ip, restricted egress to the DefenseClaw sidecar and the allowed --resolv-upstream DNS servers.
3. Policy directory: ~sandbox/.defenseclaw/policy/ seeded from the --policy template; includes Rego modules, guardrail rule packs, and an admission bundle.
4. OpenClaw config patch: ~sandbox/.openclaw/openclaw.json gets the guardrail section pointing at the sidecar on the host IP.
5. Systemd units:
   • defenseclaw-gateway@sandbox.service — the sidecar itself (runs as the invoking admin user on the host).
   • openshell-sandbox.service — the OpenClaw agent runtime as sandbox, bound to the network namespace.
   • defenseclaw-sandbox.target — enables both units at once.
6. Launcher scripts: ~sandbox/run-sandbox.sh and ~sandbox/pair.sh for manual operation.
7. Device pre-pairing: writes ~sandbox/.defenseclaw/device.key when automatic pairing is enabled by default.
8. Bundled extras:
   • CodeGuard proactive skill into ~sandbox/.claw/skills/codeguard/.
   • DefenseClaw guardrail plugin into ~sandbox/.claw/extensions/defenseclaw/.

Verify it worked

sudo systemctl status defenseclaw-sandbox.target
sudo -u sandbox defenseclaw-gateway status
ip netns exec sandbox0 ping -c 1 -W 1 $(cat ~sandbox/.defenseclaw/.host-ip)
sudo -u sandbox jq '.guardrail' ~sandbox/.openclaw/openclaw.json

A green defenseclaw-sandbox.target plus a response from /health inside the namespace proves end-to-end wiring.

Undo

sudo defenseclaw sandbox setup --disable

Disable tears down:

• Systemd units (disable --now + file removal).
• The openclaw.json patch (restored from .bak written at setup time).
• The sandbox0 veth pair and egress rules.

It does not remove the sandbox user, their home directory, their OpenClaw profile, their audit DB, or the DefenseClaw install itself. Use userdel -r sandbox and rm -rf ~sandbox/ manually if you want to purge.

Troubleshooting

Related

• init
• Gateway sidecar
• Firewall
• Watcher
• Developer deployment patterns