Skip to main content
Clawker is a free, open-source, self-hosted AI coding agent sandbox. It runs coding agents — Claude Code, OpenAI Codex, and harnesses you add yourself — inside isolated Docker containers on your own machine — no cloud, no subscription, your repo stays on your own machine, never uploaded to a vendor sandbox. Each agent runs in its own container behind a deny-by-default egress firewall and full host isolation, so you can hand agents --dangerously-skip-permissions knowing they can’t touch your host or phone home to anywhere you haven’t allowed. This guide takes you from install to your first sandboxed agent, then on to parallel agents with Git worktrees.

​
Prerequisites

  • Docker must be installed and running
  • An account or API key for the harness you’ll run — an Anthropic API key or Claude Code subscription for the claude harness, an OpenAI account or API key for codex
  • macOS or Linux (Windows is not currently supported)

​
1. Install Clawker

See Installation for the install script and build-from-source options. Verify it’s installed:

​
[Optional] Monitoring

Start the monitoring stack before your agents to get real-time dashboards Monitoring is optional but highly recommended to understand what’s happening inside your agents. It provides visibility into costs, token usage, tool calls, session events, firewall egress, DNS queries:
Open OpenSearch Dashboards at http://localhost:5601 to explore logs (costs, token usage, tool calls, session events, firewall egress, DNS queries, per-decision eBPF egress events including bypass windows), and Prometheus at http://localhost:9090 for metrics. Index patterns for all six indices (claude-code, clawker-cli, clawkercp, clawker-envoy, clawker-coredns, clawker-ebpf-egress) and the index field mappings + retention policy are preconfigured on every monitor up by the clawker-opensearch-bootstrap service. Open Discover and pick a pattern. See Monitoring for the bootstrap pipeline details and Egress Observability for the per-decision eBPF event record shape.
See the Monitoring guide for details.

​
2. Initialize and Configure Your Project

A guided setup walks you through:
  1. Project name — defaults to the current directory name (must be lowercase)
  2. Language preset — Python, Go, Rust, Node, Java, Ruby, C/C++, C#/.NET, Bare, or “Build from scratch”
  3. Save or customize — accept the preset as-is, or step through each field to tailor it
This creates:
  • A .clawker.yaml config file pre-filled with the right packages, language stacks, and firewall domains for your language
  • A .clawkerignore file (.gitignore-style syntax) that controls which files and directories are excluded from the container workspace — in snapshot mode, matching paths are excluded from the copy; in bind mode, matching directories are masked with empty tmpfs overlays. Useful for platform-specific build artifacts (e.g., dist/, build/, node_modules/) that can cause issues when switching between macOS and Linux
  • A project entry in Clawker’s registry so it always knows the project root
User settings (~/.config/clawker/settings.yaml) and XDG directories are bootstrapped automatically on first run. (Run clawker settings edit to update Clawker CLI settings, like disabling the global firewall, monitoring stack changes, etc.)

​
Customizing Your Config

You can edit .clawker.yaml directly, or use the interactive TUI editor:
Install the clawker-support plugin to get hands-on help from a clawker specialist agent. It can walk you through configuration, MCP wiring, dependency installation, firewall rules, troubleshooting, and more.
See the Configuration guide for the full reference.

​
3. Build the Image

This builds the image for your default harness. Two stages come out of it: a shared base image (clawker-<project>:base) holding the harness-agnostic layers from your .clawker.yaml — system packages, language stacks, custom instructions — and a harness image layered on top, tagged with the harness name (e.g. clawker-<project>:claude). The default harness image also gets the :default alias. The default is claude out of the box; the build.harness config key picks another. To build a specific harness instead, pass its name: clawker build -t codex. Docker’s layer cache is used, so unchanged layers are skipped; use --no-cache to force a full rebuild.

​
4. Run Your First Agent

You’re now inside a containerized coding-agent session, running whichever harness your default image was built with. Your project code is bind-mounted (live sync), your Git credentials are forwarded, and the network firewall is active. On first run the harness asks you to log in — the browser flow opens on your host automatically, and the login persists in the agent’s config volume, so you only do this once per agent.
The “go” command is a built-in alias for
So clawker go dev expands to the full command above with $1=dev. The flags mean:
  • -it — interactive mode with a terminal attached
  • --rm — removes the container when it finishes (recommended, volumes are preserved)
  • --agent dev — names this container clawker.<project>.dev
  • @ — shortcut that resolves to your built image: the default harness image inside a project (use @:<harness>, e.g. @:codex, to select a specific harness); outside a project it resolves to the global image from a global clawker build
Anything after the @ is passed to the harness CLI as normal arguments, and arguments after an alias are appended — with the out-of-box claude default, clawker go dev -c continues your previous Claude Code session, and clawker go dev --dangerously-skip-permissions hands it the infamous yolo flag, safe here because the agent is boxed in.There are also per-harness aliases that pick the harness and skip its permission prompts in one word: clawker claude dev (Claude Code with --dangerously-skip-permissions) and clawker codex dev (Codex with --yolo).
Want to try the experimental harnesses under development — opencode and pi? Install the example bundle: clawker bundle install schmitthub/clawker-bundle-example. Fork the repo, or use it as a reference to tweak your own bundle with the clawker plugin’s bundle-creator skill.
Clawker ships command aliases that expand to full invocations, and you can define your own with clawker alias set. See the Command Aliases guide.

​
What Happens Behind the Scenes

When you run this command, Clawker:
  1. Creates the container with your project directory mounted at its real host path, plus persistent volumes — the config volume declared by the harness bundle (~/.claude for the claude harness, ~/.codex for codex) and a separate shell-history volume — and streams the container’s mTLS bootstrap material (per-agent cert + key + CA + a single-use Hydra JWT, minted in your host’s clock) into it
  2. Brings up the clawker control plane if it isn’t already running — a long-lived per-host daemon that owns the firewall lifecycle, eBPF program attachment, and the mTLS command channel to every agent — and waits for it to be fully ready (including a host↔CP clock-sync check) before starting the container
  3. Starts the container with clawkerd as PID 1; the control plane attaches eBPF firewall programs from outside and dials into clawkerd over mTLS to drive in-container init. When the monitoring stack is running, every firewall decision from those eBPF programs (allowed / denied / bypassed) begins streaming to the clawker-ebpf-egress OpenSearch index — see Egress Observability
  4. Forwards SSH/GPG agent sockets and Git HTTPS credentials from your host, stages the harness’s managed config from your host (for the claude harness: settings, plugins, skills, agents — never credentials; you authenticate once inside the container and the token persists in the config volume), runs any post_init script you’ve configured
  5. Signals the agent is ready, at which point the agent daemon forks the harness CLI as the unprivileged container user (clawker) — a kernel-side privilege drop
When running the Claude Code harness, an automatically loaded prompt exists at /etc/claude-code/CLAUDE.md, so the agent knows it’s in a clawker container and can help troubleshoot issues and provide guidance when running into constraints.

​
5. Parallel Agents with Worktrees

Run multiple agents on separate branches using Git worktrees:
The --worktree branch:base flag creates a Git worktree off the base branch and mounts it into the container. Each agent works on its own branch with no conflicts.
Worktree containers apply extra security lockdown for unattended sessions — .git/hooks and .git/config are masked read-only, which changes a few git behaviors (notably git push -u). See Worktree Caveats before your first worktree session.
The shipped wt alias collapses the boilerplate — it expands to run --rm -it --agent $1 --worktree $2 @, and arguments after it pass through to the harness, so the commands above become:
See the Worktrees guide for more.

​
Managing Resources

Clawker mirrors Docker CLI patterns but only operates on Clawker-managed resources:

​
Firewall Management

​
What’s Next

Configuration

Full .clawker.yaml reference with layered config and monorepo support

Command Aliases

One-word shortcuts for full agent launches — shipped defaults, placeholders, team sharing

Security & Firewall

Understand the deny-by-default firewall and how to configure domain access

Custom Images

Packages, language stacks, Dockerfile instructions, and injection points

Harnesses

Select and run coding-agent harnesses beyond the built-in claude and codex

Stacks

Language toolchains you layer into an image — the built-in stacks and how to author your own

Bundles

Install distributed bundles of harnesses, stacks, and monitoring extensions

Credential Forwarding

SSH, GPG, and Git HTTPS forwarding, plus in-container harness authentication