---
title: "Quickstart"
description: "Install clawker, initialize a project, and run your first containerized Claude Code agent"
icon: "rocket"
---

## 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

<CodeGroup>
```bash Homebrew
brew install schmitthub/tap/clawker
```

```bash curl
curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | bash
```
</CodeGroup>

Verify it's installed:

```bash
clawker version
```

## 2. Initialize and Configure Your Project

```bash
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
clawker project edit
```

<Tip>
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.

<CodeGroup>
```bash clawker CLI
clawker skill install
```

```bash manual
claude plugin marketplace add schmitthub/claude-plugins
claude plugin install clawker-support@schmitthub-plugins
```
</CodeGroup>
</Tip>

See the [Configuration](/configuration) guide for the full reference.

## 3. Build the Image

```bash
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

```bash
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, plus persistent volumes for Claude Code config (`~/.claude`) and shell history
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
3. Streams the container's mTLS bootstrap material (per-agent cert + key + CA + a single-use Hydra JWT) into the container before starting it
4. 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
5. 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
6. Issues `AgentReady`, at which point `clawkerd` 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
# 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.

```bash
# See all worktrees
clawker worktree list

# Clean up when done
clawker worktree remove --delete-branch feature/auth
```

See the [Worktrees](/worktrees) guide for more.

## 6. Monitoring (Optional)

Start the monitoring stack before your agents to get real-time dashboards:

```bash
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), and Prometheus at `http://localhost:9090` for metrics. Index patterns for all five indices (`claude-code`, `clawker-cli`, `clawker-cp`, `clawker-envoy`, `clawker-coredns`) 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.

```bash
clawker monitor down    # Stop when done
```

See the [Monitoring](/monitoring) guide for details.

## Managing Resources

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

```bash
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

```bash
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

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Full `.clawker.yaml` reference with layered config and monorepo support
  </Card>
  <Card title="Security & Firewall" icon="shield" href="/security">
    Understand the deny-by-default firewall and how to configure domain access
  </Card>
  <Card title="Custom Images" icon="layer-group" href="/custom-images">
    Packages, Dockerfile instructions, injection points, and custom Dockerfiles
  </Card>
  <Card title="Credential Forwarding" icon="key" href="/credentials">
    SSH, GPG, Git HTTPS, and Claude Code authentication forwarding
  </Card>
</CardGroup>
