README
¶
Clawker
Claude Code in YOLO mode can wreak havoc on your system. Setting up Docker manually is tedious — Dockerfiles, volumes, networking. OAuth doesn't work because container localhost isn't host localhost. Git credentials from your keychain don't exist inside containers. And you have no visibility into what's happening.
Clawker (claude + docker) wraps Claude Code in Docker containers with a familiar CLI. It handles auth seamlessly via a host proxy, forwards your git credentials, and provides optional monitoring — so you can let Claude Code loose without worrying about your system.
Status: Alpha (macOS tested). Issues and PRs welcome — if clawker helps you, please star the repo.
Features
- Containerized Claude Code sessions with familiar Docker CLI
- Per-project image building from
clawker.yaml - Per-agent isolation — multiple agents, no interference
- Seamless auth: host proxy bridges OAuth for subscription users
- Git credential forwarding (HTTPS, SSH — zero config)
- Network firewall (outbound blocked by default, allowlist domains)
- Loop: autonomous loop engine with circuit breaker protection
- Optional monitoring stack (Prometheus + Grafana)
- Bind or snapshot workspace modes
- Label-based resource isolation (clawker never touches your other Docker resources)
Quick Start
Prerequisites: Docker running
Install
curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | bash
Other installation methods
Specific version:
curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_VERSION=v0.1.3 bash
Custom directory:
curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_INSTALL_DIR=$HOME/.local/bin bash
Build from source (requires Go 1.25+):
git clone https://github.com/schmitthub/clawker.git
cd clawker && make clawker
export PATH="$PWD/bin:$PATH"
Setup
# One-time user setup
clawker init
# Start a project
cd your-project
clawker project init # Creates clawker.yaml
# Customize your clawker.yaml (see examples/ for language-specific configs)
clawker build # Build your project image
Cheatsheet
Creating and Using Containers
# Create a fresh container and connect interactively
# The @ symbol auto-resolves your project image (clawker-<project>:latest)
clawker run -it --agent main @
# Detach without stopping: Ctrl+P, Ctrl+Q
# Re-attach to the agent
clawker attach --agent main
# Stop the agent (Ctrl+C exits Claude Code and stops the container)
# Or from another terminal:
clawker stop --agent main
# Start a stopped agent and attach
clawker start -a -i --agent main
The @ Image Shortcut
Use @ anywhere an image argument is expected to auto-resolve your project's image:
clawker run -it @ # Uses clawker-<project>:latest
clawker run -it --agent dev @ # Same, with agent name
clawker container create --agent test @
Working with Worktrees
Run separate agents per git worktree for parallel development:
# Create worktrees
git worktree add ../myapp-feature -b feature/auth
git worktree add ../myapp-tests -b feature/tests
# Each worktree gets its own agent containers
cd ../myapp-feature && clawker run -it --agent feature @
cd ../myapp-tests && clawker run -it --agent tests @
Managing Resources
clawker ps # List all clawker containers
clawker container ls # Same thing
clawker container stop --agent NAME
clawker container logs --agent NAME
clawker image ls # List clawker images
clawker volume ls # List clawker volumes
Autonomous Loops (Loop)
Loop runs Claude Code in autonomous loops with stagnation detection and circuit breaker protection:
# Start a new autonomous loop; this prints a generated agent name like "loop-abc123"
clawker loop iterate --prompt "Fix all failing tests"
# Use the printed agent name with status/reset
clawker loop status --agent loop-abc123
clawker loop reset --agent loop-abc123
See clawker loop --help for all options and configuration.
Scripted Workflows
# Keep a container running and send prompts via exec
clawker run -it --agent worker @ -- --dangerously-skip-permissions
# Detach with Ctrl+P, Ctrl+Q
echo "Fix the tests" | clawker exec -i --agent worker claude -p
clawker stop --agent worker
Passing Claude Code Options
Use -- to separate clawker flags from Claude Code flags:
clawker run -it --agent dev @ -- --dangerously-skip-permissions
Monitoring
clawker monitor start # Starts Prometheus + Grafana
clawker monitor stop
clawker monitor status
# Dashboard at http://localhost:3000
Customizing Your Build
The default image includes essentials (git, curl, vim, zsh, ripgrep). Customize for your stack in clawker.yaml:
version: "1"
project: "my-react-app"
build:
image: "buildpack-deps:bookworm-scm"
packages: [git, curl, ripgrep]
instructions:
env:
NVM_DIR: "/home/claude/.nvm"
user_run:
- cmd: |
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
- cmd: |
. "$NVM_DIR/nvm.sh" && nvm install 22 && npm install -g pnpm
See examples/ for complete configs: TypeScript, Python, Rust, Go, C#, PHP.
CLI Reference
Complete command documentation with all flags and examples: docs/cli-reference/
Environment Variables
| Variable | Purpose |
|---|---|
CLAWKER_VERSION |
Pin install script to a specific release |
CLAWKER_INSTALL_DIR |
Custom binary install directory |
CLAWKER_HOME |
Override clawker config directory (default: ~/.local/clawker) |
CLAWKER_NO_UPDATE_NOTIFIER |
Disable "new version available" notifications |
Known Issues
See GitHub Issues for current known issues and limitations.
Contributing
Contributions welcome! See CONTRIBUTING.md for development setup, testing, and PR process.
Please read our Code of Conduct before participating.
License
MIT — see LICENSE
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
clawker
command
|
|
|
clawker-generate
command
clawkergenerate is a standalone binary for generating versions.json.
|
clawkergenerate is a standalone binary for generating versions.json. |
|
fawker
command
Fawker container command — uses the real container command tree with faked Factory deps.
|
Fawker container command — uses the real container command tree with faked Factory deps. |
|
gen-docs
command
gen-docs is a standalone binary for generating CLI documentation.
|
gen-docs is a standalone binary for generating CLI documentation. |
|
internal
|
|
|
build
Package build holds build-time metadata injected via ldflags.
|
Package build holds build-time metadata injected via ldflags. |
|
bundler
Package bundler provides Docker image generation tooling for Claude Code.
|
Package bundler provides Docker image generation tooling for Claude Code. |
|
bundler/registry
Package registry provides clients for fetching package version information from npm and other registries.
|
Package registry provides clients for fetching package version information from npm and other registries. |
|
bundler/semver
Package semver provides semantic versioning utilities with support for partial version matching (e.g., "2.1" matches "2.1.x").
|
Package semver provides semantic versioning utilities with support for partial version matching (e.g., "2.1" matches "2.1.x"). |
|
cmd/bridge
Package bridge provides the hidden bridge command group for socket bridge management.
|
Package bridge provides the hidden bridge command group for socket bridge management. |
|
cmd/container
Package container provides the container management command and its subcommands.
|
Package container provides the container management command and its subcommands. |
|
cmd/container/attach
Package attach provides the container attach command.
|
Package attach provides the container attach command. |
|
cmd/container/cp
Package cp provides the container cp command.
|
Package cp provides the container cp command. |
|
cmd/container/create
Package create provides the container create command.
|
Package create provides the container create command. |
|
cmd/container/exec
Package exec provides the container exec command.
|
Package exec provides the container exec command. |
|
cmd/container/rename
Package rename provides the container rename command.
|
Package rename provides the container rename command. |
|
cmd/container/restart
Package restart provides the container restart command.
|
Package restart provides the container restart command. |
|
cmd/container/run
Package run provides the container run command.
|
Package run provides the container run command. |
|
cmd/container/shared
Package shared provides domain logic and shared options for container commands.
|
Package shared provides domain logic and shared options for container commands. |
|
cmd/container/stats
Package stats provides the container stats command.
|
Package stats provides the container stats command. |
|
cmd/container/top
Package top provides the container top command.
|
Package top provides the container top command. |
|
cmd/container/update
Package update provides the container update command.
|
Package update provides the container update command. |
|
cmd/container/wait
Package wait provides the container wait command.
|
Package wait provides the container wait command. |
|
cmd/hostproxy
Package hostproxy provides the hidden host-proxy command group for daemon management.
|
Package hostproxy provides the hidden host-proxy command group for daemon management. |
|
cmd/image
Package image provides the image management command and its subcommands.
|
Package image provides the image management command and its subcommands. |
|
cmd/image/build
Package build provides the image build command.
|
Package build provides the image build command. |
|
cmd/image/inspect
Package inspect provides the image inspect command.
|
Package inspect provides the image inspect command. |
|
cmd/image/list
Package list provides the image list command.
|
Package list provides the image list command. |
|
cmd/image/prune
Package prune provides the image prune command.
|
Package prune provides the image prune command. |
|
cmd/image/remove
Package remove provides the image remove command.
|
Package remove provides the image remove command. |
|
cmd/loop
Package loop provides the loop command for autonomous Claude Code loops.
|
Package loop provides the loop command for autonomous Claude Code loops. |
|
cmd/loop/iterate
Package iterate provides the `clawker loop iterate` command.
|
Package iterate provides the `clawker loop iterate` command. |
|
cmd/loop/shared
Package shared provides common flag types and options for loop subcommands.
|
Package shared provides common flag types and options for loop subcommands. |
|
cmd/loop/tasks
Package tasks provides the `clawker loop tasks` command.
|
Package tasks provides the `clawker loop tasks` command. |
|
cmd/network
Package network provides the network management command and its subcommands.
|
Package network provides the network management command and its subcommands. |
|
cmd/network/create
Package create provides the network create command.
|
Package create provides the network create command. |
|
cmd/network/inspect
Package inspect provides the network inspect command.
|
Package inspect provides the network inspect command. |
|
cmd/network/list
Package list provides the network list command.
|
Package list provides the network list command. |
|
cmd/network/prune
Package prune provides the network prune command.
|
Package prune provides the network prune command. |
|
cmd/network/remove
Package remove provides the network remove command.
|
Package remove provides the network remove command. |
|
cmd/project
Package project provides the project management command and its subcommands.
|
Package project provides the project management command and its subcommands. |
|
cmd/project/init
Package init provides the project initialization subcommand.
|
Package init provides the project initialization subcommand. |
|
cmd/project/register
Package register provides the project register subcommand.
|
Package register provides the project register subcommand. |
|
cmd/volume
Package volume provides the volume management command and its subcommands.
|
Package volume provides the volume management command and its subcommands. |
|
cmd/volume/create
Package create provides the volume create command.
|
Package create provides the volume create command. |
|
cmd/volume/inspect
Package inspect provides the volume inspect command.
|
Package inspect provides the volume inspect command. |
|
cmd/volume/list
Package list provides the volume list command.
|
Package list provides the volume list command. |
|
cmd/volume/prune
Package prune provides the volume prune command.
|
Package prune provides the volume prune command. |
|
cmd/volume/remove
Package remove provides the volume remove command.
|
Package remove provides the volume remove command. |
|
cmd/worktree
Package worktree provides commands for managing git worktrees.
|
Package worktree provides commands for managing git worktrees. |
|
cmd/worktree/add
Package add provides the worktree add command.
|
Package add provides the worktree add command. |
|
cmd/worktree/list
Package list provides the worktree list command.
|
Package list provides the worktree list command. |
|
cmd/worktree/prune
Package prune provides the worktree prune command.
|
Package prune provides the worktree prune command. |
|
cmd/worktree/remove
Package remove provides the worktree remove command.
|
Package remove provides the worktree remove command. |
|
config/configtest
Package configtest provides test fakes for config types.
|
Package configtest provides test fakes for config types. |
|
containerfs
Package containerfs prepares host Claude Code configuration for container injection.
|
Package containerfs prepares host Claude Code configuration for container injection. |
|
docker
Package docker provides clawker-specific Docker middleware.
|
Package docker provides clawker-specific Docker middleware. |
|
docker/dockertest
Package dockertest provides test doubles for internal/docker.Client.
|
Package dockertest provides test doubles for internal/docker.Client. |
|
docs
Package docs provides documentation generation for Cobra commands in multiple formats including Markdown, man pages, YAML, and reStructuredText.
|
Package docs provides documentation generation for Cobra commands in multiple formats including Markdown, man pages, YAML, and reStructuredText. |
|
git
Package git provides Git repository operations, including worktree management.
|
Package git provides Git repository operations, including worktree management. |
|
git/gittest
Package gittest provides test utilities for the git package.
|
Package gittest provides test utilities for the git package. |
|
hostproxy
Package hostproxy provides a host-side HTTP server that containers can call to perform actions on the host, such as opening URLs in the browser.
|
Package hostproxy provides a host-side HTTP server that containers can call to perform actions on the host, such as opening URLs in the browser. |
|
hostproxy/internals
Package internals provides embedded container-side scripts and source code that run inside clawker containers to communicate with the host proxy and socketbridge.
|
Package internals provides embedded container-side scripts and source code that run inside clawker containers to communicate with the host proxy and socketbridge. |
|
hostproxy/internals/cmd/callback-forwarder
command
callback-forwarder polls the host proxy for captured OAuth callback data and forwards it to the local HTTP server (Claude Code's callback listener).
|
callback-forwarder polls the host proxy for captured OAuth callback data and forwards it to the local HTTP server (Claude Code's callback listener). |
|
hostproxy/internals/cmd/clawker-socket-server
command
socket-forwarder is a multiplexing socket forwarder that runs inside clawker containers.
|
socket-forwarder is a multiplexing socket forwarder that runs inside clawker containers. |
|
iostreams
Package cmdutil provides utilities for command-line applications.
|
Package cmdutil provides utilities for command-line applications. |
|
keyring
Package keyring wraps the zalando/go-keyring package with timeouts and provides a service-credential registry for fetching, parsing, and validating secrets stored in the OS keychain.
|
Package keyring wraps the zalando/go-keyring package with timeouts and provides a service-credential registry for fetching, parsing, and validating secrets stored in the OS keychain. |
|
signals
Package signals provides OS signal utilities for graceful shutdown and terminal resize propagation.
|
Package signals provides OS signal utilities for graceful shutdown and terminal resize propagation. |
|
socketbridge
Package socketbridge provides host-side socket forwarding via docker exec.
|
Package socketbridge provides host-side socket forwarding via docker exec. |
|
socketbridge/socketbridgetest
Package socketbridgetest provides test utilities for the socketbridge package.
|
Package socketbridgetest provides test utilities for the socketbridge package. |
|
text
Package text provides pure text/string utility functions.
|
Package text provides pure text/string utility functions. |
|
update
Package update checks GitHub for newer clawker releases and caches results.
|
Package update checks GitHub for newer clawker releases and caches results. |
|
pkg
|
|
|
whail
Package whail provides a reusable Docker isolation library ("whale jail").
|
Package whail provides a reusable Docker isolation library ("whale jail"). |
|
whail/buildkit
Package buildkit provides BuildKit client connectivity for whail.
|
Package buildkit provides BuildKit client connectivity for whail. |
|
whail/whailtest
Package whailtest provides test doubles and helpers for testing code that uses the whail engine.
|
Package whailtest provides test doubles and helpers for testing code that uses the whail engine. |
|
test
|
|
|
harness/builders
Package testutil provides shared test utilities for clawker tests.
|
Package testutil provides shared test utilities for clawker tests. |
Click to show internal directories.
Click to hide internal directories.