Skip to main content

​
Prerequisites

  • Docker must be installed and running
  • An Anthropic API key or Claude Code subscription
  • macOS or Linux (Windows is not currently supported)

​
1. Install Clawker

brew install schmitthub/tap/clawker
Verify it’s installed: 
clawker version

​
2. Initialize and Configure Your Project

cd your-project
clawker init
A guided setup walks you through:
  1. Project name — defaults to the current directory name (must be lowercase)
  2. Language preset — Python, Go, Rust, TypeScript, 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 base image, packages, 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: 
clawker project edit
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.
clawker skill install
See the Configuration guide for the full reference.

​
3. Build the Image

clawker build
This builds a Docker image tagged clawker-<project>:latest using the settings in your .clawker.yaml — base image, system packages, Claude Code, and any custom instructions. The image is content-addressed, so rebuilds only happen when the config changes.

​
4. Run Your First Agent

clawker run -it --rm --agent dev @ --dangerously-skip-permissions
  • -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 project’s built image
You’re now inside a containerized Claude Code session. Your project code is bind-mounted (live sync), your Git credentials are forwarded, and the network firewall is active. Arguments after the image (@) are passed directly to Claude Code inside the container.

​
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
  2. Creates persistent volumes for Claude Code config (~/.claude) and shell history
  3. Starts the firewall daemon (Envoy + CoreDNS) if it isn’t already running
  4. Applies iptables rules inside the container to redirect traffic through the firewall
  5. Copies your host Claude Code settings, plugins, and authentication into the container
  6. Forwards SSH/GPG agent sockets and Git HTTPS credentials from your host
  7. Runs any post_init script you’ve configured
  8. Launches Claude Code
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: 
# Agent on a feature branch (creates worktree automatically)
clawker run -it --rm --agent auth --worktree feature/auth:main @ --dangerously-skip-permissions

# Another agent on a different branch
clawker run -it --rm --agent cache --worktree feature/cache:main @ --dangerously-skip-permissions
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. 
# See all worktrees
clawker worktree list

# Clean up when done
clawker worktree remove --delete-branch feature/auth
See the Worktrees guide for more.

​
6. Monitoring (Optional)

Start the monitoring stack before your agents to get real-time dashboards: 
clawker monitor init    # Scaffold configs (one-time)
clawker monitor up      # Start Grafana, Prometheus, Loki, Jaeger
Open Grafana at http://localhost:3000 to see costs, token usage, tool calls, and session timelines for every agent. 
clawker monitor down    # Stop when done
See the Monitoring guide for details.

​
7. Autonomous Loops (Experimental)

Run Claude Code in iterative loops with a fresh container per iteration: 
clawker loop iterate \
  --prompt "Fix all failing tests and open a PR" \
  --max-loops 10 \
  --skip-permissions \
  --worktree fix/tests:main
A TUI dashboard shows progress, tool calls, costs, and circuit breaker status in real time. See the Loop Mode guide for configuration.

​
Managing Resources

Clawker mirrors Docker CLI patterns but only operates on Clawker-managed resources: 
clawker ps                            # List containers
clawker image ls                      # List images
clawker volume ls                     # List volumes

clawker stop --agent dev              # Stop a container
clawker rm --agent dev                # Remove a container
clawker volume prune                  # Clean up orphaned volumes

​
Firewall Management

clawker firewall status               # Health check
clawker firewall list                 # Show active rules
clawker firewall add pypi.org         # Allow a domain at runtime
clawker firewall remove pypi.org      # Revoke access
clawker firewall bypass 5m --agent dev  # Temporary unrestricted access

​
What’s Next

Configuration

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

Security & Firewall

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

Custom Images

Packages, Dockerfile instructions, injection points, and custom Dockerfiles

Credential Forwarding

SSH, GPG, Git HTTPS, and Claude Code authentication forwarding