> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clawker.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart: Self-Hosted AI Coding Agent Sandbox
> Run Claude Code in Docker on your own machine. Install clawker, initialize a project, and launch your first sandboxed AI coding agent — free, local, and open-source.
Clawker is a free, open-source, self-hosted AI coding agent sandbox. It runs Claude Code (and other AI coding agents) 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](https://www.docker.com/get-started/) must be installed and running
* An Anthropic API key or Claude Code subscription
* macOS or Linux (Windows is not currently supported)
## 1. Install Clawker
```bash Homebrew theme={"dark"}
brew install schmitthub/tap/clawker
```
```bash curl theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | bash
```
Verify it's installed:
```bash theme={"dark"}
clawker version
```
## \[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:
```bash theme={"dark"}
clawker monitor init # Scaffold configs (one-time)
clawker monitor up # Start OTel Collector + OpenSearch + OpenSearch Dashboards + Prometheus
```
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](/monitoring) for the bootstrap pipeline details and [Egress Observability](/observability) for the per-decision eBPF event record shape.
```bash theme={"dark"}
clawker monitor down # Stop when done
```
See the [Monitoring](/monitoring) guide for details.
## 2. Initialize and Configure Your Project
```bash theme={"dark"}
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:
```bash theme={"dark"}
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.
```bash clawker CLI theme={"dark"}
clawker skill install
```
```bash manual theme={"dark"}
claude plugin marketplace add schmitthub/claude-plugins
claude plugin install clawker-support@schmitthub-plugins
```
See the [Configuration](/configuration) guide for the full reference.
## 3. Build the Image
```bash theme={"dark"}
clawker build
```
This builds a Docker image tagged `clawker-:latest` using the settings in your `.clawker.yaml` — base image, system packages, Claude Code, and any custom instructions. Docker's layer cache is used, so unchanged layers are skipped; use `--no-cache` to force a full rebuild.
## 4. Run Your First Agent
```bash theme={"dark"}
clawker go dev
```
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.
The "go" command is a built-in alias for
```bash theme={"dark"}
clawker run -it --rm --agent $1 @ --dangerously-skip-permissions
```
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..dev`
* `@` — shortcut that resolves to your built image (the project image here; outside a project it resolves to the global image from a global `clawker build`)
* `--dangerously-skip-permissions` — the infamous claude code yolo flag. You can treat anything after the `@` as a normal `claude` invocation, including `-c` to continue your previous session. You can also pass arguments after an alias, like `clawker go dev -c`.
Clawker ships [command aliases](/aliases) that expand to full invocations, and you can define your own with `clawker alias set`. See the [Command Aliases](/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 for Claude Code config (`~/.claude`) and shell history, 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](/observability)
4. Forwards SSH/GPG agent sockets and Git HTTPS credentials from your host, copies your Claude Code settings/plugins/auth into the container, runs any `post_init` script you've configured
5. Signals the agent is ready, at which point the agent daemon forks Claude Code as the unprivileged `claude` user (kernel-side privilege drop)
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:
```bash theme={"dark"}
# 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.
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](/worktrees#worktree-caveats) before your first worktree session.
The shipped `wt` [alias](/aliases) collapses each of those commands to three words:
```bash theme={"dark"}
clawker wt auth feature/auth:main
clawker wt cache feature/cache:main
```
```bash theme={"dark"}
# See all worktrees
clawker worktree list
# Clean up when done
clawker worktree remove --delete-branch feature/auth
```
See the [Worktrees](/worktrees) guide for more.
## Managing Resources
Clawker mirrors Docker CLI patterns but only operates on Clawker-managed resources:
```bash theme={"dark"}
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 # Remove unused agent volumes — config, history, workspace (add --all for infra volumes like monitoring stack)
```
### Firewall Management
```bash theme={"dark"}
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 refresh # Apply .clawker.yaml egress edits without a restart
clawker firewall bypass 5m --agent dev # Temporary unrestricted access
```
## What's Next
Full `.clawker.yaml` reference with layered config and monorepo support
One-word shortcuts for full agent launches — shipped defaults, placeholders, team sharing
Understand the deny-by-default firewall and how to configure domain access
Packages, Dockerfile instructions, injection points, and custom Dockerfiles
SSH, GPG, Git HTTPS, and Claude Code authentication forwarding