01
Two backends, one interface
local (default) runs /bin/sh -c in the host process for the legacy behaviour. docker ("shell_backend": "docker" in config.json or --backend docker per-run) routes every shell call through a container instead.
// Shell backends
Run shell tools inside a per-session container.
PasClaw factors shell execution behind an IShellBackend interface so operators can choose where commands actually run. The docker backend spawns a per-session container at session start, docker execs every shell_exec and execute_code call into it, and tears it down at session end — escapes from the denylist can only touch the container, not the host.
IShellBackendPer-session containerSame-path bind mountNo config leak
02
Same-path workspace mount
The workspace is bind-mounted at the same path inside the container as on the host. fs_* tools on the host and cat/tee inside the container reference the exact same files with no path translation.
03
Provider keys stay out
~/.pasclaw/config.json is deliberately not mounted into the container, so even a fully compromised shell cannot read provider credentials from inside the sandbox.
04
Wired into agent + heartbeat
Phase 1 wires the docker backend into pasclaw agent (interactive and one-shot) and pasclaw heartbeat, so the highest-risk surfaces benefit first.
From the documentation
Technical details
Implementation notes drawn from the PasClaw repository documentation.
Per-session container lifecycle
The docker backend spawns one container per session, docker execs every shell call into it, and stops it at session end.
- Workspace bind-mounted at the same path on host and inside the container.
- ~/.pasclaw/config.json is deliberately not mounted in.
- Phase 1 covers pasclaw agent (interactive + one-shot) and pasclaw heartbeat.
Per-run override
Choose the backend statically or per invocation.
// config.json
"shell_backend": "docker"
// per-run
pasclaw agent --backend dockerSource documentation
Common questions
Frequently asked questions
Keep exploring
See how the rest of PasClaw fits together.