OpenShell sandbox

DefenseClaw's sandbox commands configure an experimental, Linux-only OpenShell standalone environment for OpenClaw. The sandbox combines Linux network namespaces with OpenShell's Landlock and seccomp isolation, while the DefenseClaw sidecar remains the policy and audit authority.

Before you start

You need:

• a Linux host and permission to run the narrowly scoped privileged operations requested through sudo;
• a completed DefenseClaw v8 initialization with OpenClaw active;
• an existing OpenClaw home containing openclaw.json; and
• a verified openshell-sandbox on PATH.

Install the binary independently for source checkouts, virtual environments, and other per-user layouts. When the binary is absent, sandbox init can invoke the bundled installer for the OpenShell 0.0.16 OCI image only when the installer itself and every ancestor directory form a root-owned, non-group/world-writable packaged layout. An ordinary user-owned checkout does not satisfy that trust boundary, so automatic acquisition is skipped.

Because the OCI tag is mutable, the installer refuses before downloading a layer unless OPENSHELL_SANDBOX_SHA256 (or the legacy DEFENSECLAW_OPENSHELL_BINARY_SHA256) pins the final binary. An optional DEFENSECLAW_OPENSHELL_ARCH_DIGEST also pins the platform manifest. Those values are explicitly preserved through the narrow sudo invocation. The explicit DEFENSECLAW_OPENSHELL_ALLOW_UNPINNED=1 escape hatch gives up that integrity guarantee and is not recommended.

Initialization also checks for iptables when host networking or the guardrail redirect needs it; on systems with apt-get, it attempts that installation. Treat a failed automatic dependency installation as a stop condition and install the reported dependency through your normal host-management process.

Initialize

defenseclaw init

defenseclaw sandbox init

sudo systemctl start defenseclaw-sandbox.target
defenseclaw-gateway start

sudo ~/.defenseclaw/scripts/run-sandbox.sh

defenseclaw-gateway status
defenseclaw status
defenseclaw doctor
defenseclaw tui

What setup changes

defenseclaw sandbox setup validates that sandbox init created the sandbox user and home, then generates the following intended topology:

• sets openshell.mode: standalone and records the sandbox home;
• points the OpenClaw gateway client at the sandbox bridge address and port;
• points guardrail inspection at the host bridge address when enabled;
• enables the gateway watcher and skill watcher/action settings;
• points claw.home_dir and claw.config_file at the sandbox OpenClaw tree;
• installs the selected OpenShell Rego/data policy, generates DNS and launcher assets, and patches OpenClaw's port, bind address, and guardrail base URL;
• pre-pairs a regular, owner-only gateway device key with gateway-minted provenance; otherwise pairing is skipped or refused. The legacy DEFENSECLAW_PREPAIR_TRUST_DEVICE_KEY=1 override bypasses only the provenance proof, retains the file-type/ownership/mode checks, and is unsafe;
• stores a detected OpenClaw gateway token by environment reference rather than in YAML;
• grants the invoking user the group/ACL access needed by the watcher, stops a conflicting host OpenClaw process, and generates systemd plus non-systemd launchers; and
• skips CodeGuard assets, which always require a separate explicit opt-in.

Setup pins the operator-confirmed OpenClaw home before privileged writes and recursive ownership changes. A changed symlink target is refused.

It does not currently populate /home/sandbox/.defenseclaw/config.yaml, provision a corresponding sandbox-user sidecar-token source, set gateway.api_bind, or create loopback DNAT for extension/interceptor calls. Those omissions are why the acceptance gate is mandatory.

Customize networking and policy

Use the lower-level command after initialization:

defenseclaw sandbox setup --policy strict

Do not select a policy only by its name. Review the generated ~/.defenseclaw/openshell-policy.rego and ~/.defenseclaw/openshell-policy.yaml against the egress your OpenClaw workload actually needs.

Operate and monitor

On systemd:

systemctl status openshell-sandbox.service
systemctl status defenseclaw-sandbox.target
sudo journalctl -u openshell-sandbox -f
sudo systemctl stop openshell-sandbox.service

Without systemd:

sudo ~/.defenseclaw/scripts/run-sandbox.sh stop

Run that stop command before disabling sandbox mode on a host without systemd. The disable command does not execute the user-writable launcher as root.

The OpenShell service writes to the systemd journal. The separately started DefenseClaw gateway writes its detached process output to ~/.defenseclaw/gateway.log; canonical verdict, judge, and lifecycle history is in local SQLite and the TUI. Review all three surfaces when diagnosing a traffic or policy problem.

Troubleshooting

Disable sandbox mode

defenseclaw sandbox setup --disable

On a non-systemd host, first stop the generated launcher:

sudo ~/.defenseclaw/scripts/run-sandbox.sh stop
defenseclaw sandbox setup --disable

Disable stops and disables generated units when systemd is available, removes owned networking rules, removes the sandbox link, switches DefenseClaw back to its built-in host defaults, and disables the watcher. It does not snapshot and restore custom OpenClaw gateway/provider values: it writes gateway.mode: local, port 18789, loopback binding, and a localhost DefenseClaw provider host. Record custom values before setup and reapply them afterward.

The ownership record contains one top-level UID/GID and disable applies it recursively; it cannot reconstruct mixed ownership. Cleanup is best effort, not transactional, so inspect command output and retained files before relying on the result. Then rerun defenseclaw setup guardrail so the host OpenClaw base URL matches the intended topology.

Disabling does not promise to remove the sandbox system account or erase generated evidence. Review retained files before any manual cleanup.

Implementation sources

• cmd_sandbox.py defines the public Linux-only command group.
• cmd_init_sandbox.py owns initialization, dependency acquisition, OpenClaw transfer, and provenance guards.
• cmd_setup_sandbox.py owns flags, config changes, networking, pairing, launchers, and disable behavior.
• install-openshell-sandbox.sh resolves the OCI image and requires an independent binary integrity anchor unless the operator explicitly opts out.