clawker

Clawker: Claude Code agent-in-container orchestration and automation

The rise of Agentic AI has been meteoric, but in the rush to ship model harnesses, the industry is skipping the risks and responsibilities that come with them. They’re avoiding dependency pain by shipping bare-metal software, when the harness itself needs a harness. LLMs are powerful, but they’re also unpredictable, naive, and easy to coerce—and handing one unrestricted code execution, network access, software install rights, internet reach, and full filesystem access to unsuspecting users is reckless. As a security engineer, my first instinct was to protect my own machine by building the harness for the harness: an "agent-in-container" solution. Clawker started as my way to learn Claude Code, then proved useful enough to open source as a practical example of secure-by-default guardrails for agentic software. I hope this project inspires the industry to prioritize containerization natively in their agentic software offerings, and to build more tools that make it easy and seamless for users to run agents in containers with strong security defaults.

clawker is basically what would happen if devcontainers and k8s had a Claude Code baby. It's a container orchestration and automation tool for running Claude Code agents in isolated containers on any host with docker installed. I wrote this because I didn't want to have to pay someone to run claude code agents with --dangerously-skip-permissions when containers have been around for a decade, and claude code's sandbox mode is the temu version of a container. clawker offers convenience features beyond just building and running claude code in a container using a Dockerfile (you don't even have to write a Dockerfile it's got you covered).

! Clawker is in an early development stage, but it's usable and has a lot of features. Expect breaking changes and rough edges. I quickly patch regressions that were missed. If you want to contribute or have any feedback, please open an issue or a pull request! Give it a star if you find it useful so I can brag about them at parties

Table of Contents

• Clawker: Claude Code agent-in-container orchestration and automation
  • Table of Contents
  • High-Level Feature Overview
  • Installation
  • Quick Start
  • Walkthrough
    • Initialize
      • Start a project
      • Run a container
  • Creating and Using Containers
  • The @ Image Shortcut
  • Working with Worktrees
  • Managing Resources
  • Monitoring
  • Autonomous Loops (Experimental)
    • A TUI will open showing you the agent's progress, decisions, tool calls, and more in real time
  • Roadmap / Known Issues
  • Contributing
  • License

High-Level Feature Overview

• Embedded parameterized Dockerfile template inspired by the official devcontainer image, supporting Alpine or Debian base images with common tools preinstalled: git, curl, vim, zsh, ripgrep, etc. An entrypoint script that lets you bypass Claude Code or just pass flags as the default command, unprivileged claude user, and more
• Static Dockerfile generation if you desire a tangible Dockerfile to build and customize yourself (this repo was at first going to just be a docker image packaging repo for my private dockerhub lol so I kept this in here)
• Injectable build-time instructions to customize images per project: packages, environment variables, root run commands, user run commands, and more
• Bind or snapshot workspace modes: mount your repository to the container for live editing, or copy it at runtime for pure isolation
• Fresh or copy agent mode: start with a clean Claude Code install, or copy all your Claude Code settings, plugins, authentication, skills, etc. into the container at runtime for a seamless transition from doing work in a host instance to a container
• Seamless Git credential forwarding: toggleable SSH agent, GPG agent forwarding from the host using muxrpc (just like devcontainers) for zero-config access to private repositories and commit signing
• Host proxy service copies git ssh keys into the container and sends events like "browser open" from the container to your host for browser authentication, then proxies the callback back to the container. Great for when you have to authenticate with claude or gh
• Configurable environment variables: set or copy environment variables and env files from the host into containers at runtime
• Injectable post-initialization bash script that runs after the container starts but before Claude Code launches, letting you set up MCPs, etc.
• Default-configured firewall to prevent agents from accessing most of the internet except GitHub and common package managers; add domains, IP list services, and pre-created addons (GCP) per project, or disable it entirely. This is a great security layer to mitigate runaway agents or prompt injections from doing damage while still giving them the network access they need to be useful.
• Toggleable read-only global share: volume mount from the host giving all containers real-time access to files you place in it
• Project-based namespace isolation of container resources. Clawker detects if it's in a project directory and automatically, via docker label prefixes, lets you filter for resources with re-usable names like "dev" or "main" that are scoped to the project. So you can have a "dev" container in multiple projects without conflict, and you can easily filter clawker ps --filter agent=dev to see all your dev containers across projects or clawker ps --project myapp to see all containers for a specific project.
• Dedicated Docker network that all containers run in
• Jailed from host Docker resources via pkg/whail (whale jail), a standalone package that decorates the moby SDK to prevent callers from seeing resources without the automatically applied management labels. I might use this package in other "agent in container" solutions. So I don't have to worry about accidentally deleting non-clawker managed containers/volumes/images, etc.
• Docker CLI-esque commands for managing containers, Clawker isn't a passthrough to Docker CLI; it uses the moby SDK (via pkg/whail). This allowed me to add more flags, modify the behavior, etc over what docker cli offers
• Git worktree management and commands: pass a worktree flag to container run or create commands to automatically create a git worktree in the Clawker home project directory and bind mount it to the container workdir. Also has cli commands and flags to list and manage worktrees created by clawker, uses go-git under the hood to avoid relying on the host git binary
• Optional monitoring stack with Prometheus, Loki, and Grafana to monitor agents and containers; every container has the environment variables needed to communicate with it
• Looping mode (experimental): pass a prompt, file, or task list to Clawker and it runs an autonomous loop with a fresh container each iteration with stagnation detection, circuit breaker protection, max loops, tracking container agent output, progress, costs, token usage, etc.

Installation

Prerequisites: Docker must be installed and running on your machine. I've tested all features on macOS. I have confirmed it works on Linux just not extensively. Windows is not currently supported but I might in the future (yucky).

Homebrew (macOS):

brew install schmitthub/tap/clawker

Install script (macOS / Linux):

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

curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_VERSION=v0.1.3 bash

curl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_INSTALL_DIR=$HOME/.local/bin bash

git clone https://github.com/schmitthub/clawker.git
cd clawker && make clawker
export PATH="$PWD/bin:$PATH"

Quick Start

The fastest path to a seamless containerized Claude Code instance, with all your host settings, plugins, and creds copied in so you can get to work right away.

cd your-project
clawker project init 
clawker build
clawker run -it --rm --agent example @ --dangerously-skip-permissions

This:

• Builds a project-scoped container image (clawker-<project>:latest, with @ as a shortcut when you are in the project directory), using the default Dockerfile template
• Starts and attaches your terminal to the container (clawker.<project>.example) using that image (via the @ identifier), with your current working directory bind-mounted (i.e., live share)
• Copies your host Claude Code settings, plugins, authentication, skills, etc. for a seamless transition from host to container development.

The --rm flag removes the container when you exit, so it's perfect for quick tasks or experimentation. If you want persistence, omit --rm and start the same container again later with clawker start -a -i --agent example. You can also keep it running by detaching (Ctrl+P, Ctrl+Q) and reattach later with clawker attach --agent example to the same terminal session.

If you want to learn more about image customization, worktree support, loops, monitoring, and other bells and whistles, keep reading for the walkthrough below.

Walkthrough

Here are ways I'm using clawker today and how I'm finding it useful.

Initialize

clawker init

This is going to create a ~/.config/clawker directory (configurable with CLAWKER_CONFIG_DIR) where all of Clawker's global user settings live. Clawker also stores logs, state, and caches using XDG directories (XDG_CACHE_HOME, XDG_STATE_HOME, XDG_DATA_HOME). It is also going to ask you if you want to create a default fallback image to use when you aren't in a project directory. This image is optional but it can be a nice sandbox to have around for quick experimentation when you don't want to set up a whole project. You can also use it as a base image for your projects if you want to share common dependencies across them.

Start a project

cd your-project         # This changes directories to your project
clawker project init    # Creates .clawker.yaml, .clawkerignore, and registers your project. The regsitry system allows clawker to always know your project's root and associated worktree directories 

Tip: Customize your .clawker.yaml (see examples/ for language-specific templates but be warned they were generated by claude code I have not manually tested them all personally, consider them inspiration. Future updates will have baked in reliable default project configs of common dev stacks.). If you use Claude Code or another LLM to help author your config, paste examples/llm.md (raw) into context — it covers the schema, build-time inject points, and common pitfalls. I dogfood clawker to build clawker, so check out my clawker.yaml to see how I customized the build config for golang development.

Tip You can alternatively use .clawker/clawker.yaml (which takes precendence). You can also split the configs up into multiple files through your repository for merging, good for monorepos. A global clawker.yaml can also be created in $CLAWKER_CONFIG_DIR for system wide defaults. You can also create an uncomitted .clawker.local.yaml|.clawker/clawker.local.yaml for local-only overrides.

clawker build           # Builds your project's image (referenced as "@" when within a project directory)

Run a container

My workflow is a hybrid approach. I like having a claude code instance running on the host for real intensive interactive work while at the same time launching a few clawker managed containers in separate tabs and worktrees using --dangerously-skip-permissions.

So to do that let's say you're working on a feature branch with host claude code and inspiration strikes or you notice an issue / bug and say "shit i should address this". Or you've finished up a few PRDs and want to bang them out in parallel. I just quickly open a tab and have another claude agent via clawker get after it on the side without me having to approve anything over and over again so...

clawker run -it --agent example --worktree hotfix/example:main @ --dangerously-skip-permissions

This creates and attaches my terminal to a new claude instance isolated in a container environment with a git worktree dir created under ~/.local/share/clawker/worktrees/ (or honors the override $CLAWKER_DATA_DIR) off of my main branch. Since it has all my plugins, skills, auth tokens, git creds, mcps installed, build deps instantly, it's just a matter of telling the little rascal what to do and letting it go bananas and create a pr about it. I'll periodically check in on it to see how it's doing in another tab. Or you can detach ctrl p+q and return to your terminal; to reattach to the same session use clawker attach --agent example. Ez pz no ssh/tmux bullshit, no vscode devcontainer window, no VPS with heavy IO latency, or setting up dedicated servers, or having to pay someone to do it for you.

I can see my worktree paths and open them in an IDE if I want to do some manual work or review the code... or never care about where they are, clawker remembers and auto mounts them using branches as an identifier. You can use clawker worktree commands to manage them, or git worktree.

$ clawker worktree list
BRANCH     PATH                                                                      HEAD     MODIFIED     STATUS
a/example  /Users/schmitthub/.local/share/clawker/worktrees/repo-project-uuidsha256  f20aa37  1 hour ago   healthy

When I'm done I easily remove the worktree

clawker worktree remove a/example --delete-branch  # this deletes the worktree and the branch since it was only for this worktree, if you want to keep the branch just omit the flag. Delete won't work if the branch isn't fully merged

If I want to iterate over a prompt with a fresh containerized claude code each time (aka "ralph wiggum")

# Start a new autonomous loop; TUI tracks output, tool use, costs etc via Agent SDK streaming events
LOOP_PROMPT=$(cat <<'EOF'
Write a story in @docs/sadboy.md about a sad boy who struggles with context window 
management, token costs, and genai hallucinations.

If the file doesn't exist, create it with:
- Title and table of contents with chapters "The Struggle" and "A Sad Conclusion"
- Author section (make up an author name for yourself and write a short bio about your tragic life inspired by artists like Edgar Allen Poe, Van Gogh, etc)
- Two opening paragraphs to start the story

If the file exists, add two new chapter paragraphs that continue the story and update the sad conclusion.
EOF
)
clawker loop iterate --prompt "$LOOP_PROMPT" --max-loops 5 --skip-permissions

Note: I've decided to commit "The Sorrows of Token Boy" so that the world can know his story. But be warned, you will weep uncontrollably.

"And each morning, the machine would respond with supreme confidence about things that had never happened, places that did not exist, and APIs that were fabricated from whole cloth. "The fs.readFileSync method accepts a feelings parameter," it once told him, with the calm authority of a professor." - AI Author: Cornelius Vex Holloway

If I plan on having long sessions with many agents ripping through features and fixes and want a high level overview of my coding armada I start the monitoring stack (need to do this before starting the containers, claude code doesn't retry if it can't establish a connection)

clawker monitor init
clawker monitor up
clawker monitor status 
# stop it later on 
clawker monitor down

Now I can go to the grafana dashboard at http://localhost:3000 and see all my agents, containers, resource usage, costs, tool executions, decisions, prompts, api calls, etc from every agent. (you can also set env vars in your host shell and it will report to this stack)

# Host ENV var example
# Add these to your shell profile / .env etc
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORT_INTERVAL=5000
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4318/v1/logs
OTEL_METRIC_EXPORT_INTERVAL=10000
OTEL_LOGS_EXPORTER=otlp
OTEL_METRICS_INCLUDE_ACCOUNT_UUID=true
OTEL_METRICS_INCLUDE_SESSION_ID=true
CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_LOG_TOOL_DETAILS=1
OTEL_LOG_USER_PROMPTS=1

# Add this to a project level .env 
PROJECT_NAME=MyGroundbreakingTodoApp
OTEL_RESOURCE_ATTRIBUTES=project=$PROJECT_NAME,agent=host

When I'm done I can commit / push / open a PR right in the container terminal with all my creds and git access set up, or I can open the worktree in my IDE and do it from there. I can /exit out and the container will stop (or ctrl c in the terminal). I can use --rm flags just like docker cli to automatically remove containers when they stop, or I can start the same one back up again with clawker start -a -i --agent example to pick up right where I left off.

All containers get named volume mounts for their claude config directories and command history for persistence.

$ clawker volume ls
VOLUME NAME                                  DRIVER  MOUNTPOINT
clawker.clawker.example-config               local   ...er/volumes/clawker.clawker.example-config/_data
clawker.clawker.example-history              local   ...r/volumes/clawker.clawker.example-history/_data
# You can see the resources naming conventions here (clawker.{project}.{agent}). Labeling works similarly

You can also see how clawker is jailed from other docker resource access...

$ docker create alpine:latest
6c6896073eb1a2baa91450d0b5b795808f0ea4a052f729383a2d166d87fa0c17
$ clawker ps -a
NAME                     STATUS                  PROJECT                AGENT                  IMAGE                   CREATED
clawker.clawker.example  exited                  clawker                example                clawker-clawker:latest  9 hours ago
$ docker ps -a 
CONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS                    PORTS     NAMES
6c6896073eb1   alpine:latest            "/bin/sh"                7 seconds ago   Created                             great_dubinsky
73b4ac14c2b3   clawker-clawker:latest   "entrypoint.sh --dan…"   10 hours ago    Exited (0) 10 hours ago             clawker.clawker.example

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:

# Use the --worktree flag for automatic worktree creation and mounting in containers
clawker run --worktree feature/todo-apps-are-dope:main -it --agent todo-apps @ --dangerously-skip-permissions

# Create worktrees manually
clawker worktree add feature/todo-apps-are-dope
clawker worktree add feat-feet --base main

# list your worktrees
clawker worktree list

Managing Resources

As close to docker CLI and its flags as I could make it, but remember they do different things under the hood. Adding all features is also still a WIP

clawker ps                          # List all clawker containers
clawker container ls                # Same thing
clawker container stop --agent NAME
clawker image ls                    # List clawker images
clawker volume ls                   # List clawker volumes

Monitoring

All containers have the necessary environment variables to send metrics and logs to an OpenTelemetry collector by default. When you start the optional monitoring stack, it automatically collects and visualizes these metrics and logs in Grafana dashboards. This gives you real-time insights into your agents' performance, decisions, tool calls, costs, token usage, and more.

clawker monitor init
clawker monitor up
clawker monitor status 
# stop it later on 
clawker monitor down

Autonomous Loops (Experimental)

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 "write a small poem to a file @test.txt" --max-loops 3 --skip-permissions

A TUI will open showing you the agent's progress, decisions, tool calls, and more in real time

See clawker loop --help for all options and configuration.

Roadmap / Known Issues

• Currently, clawker containers use stdout/stderr as a poor man's event transport for monitoring and looping mode. I am working on a control plane and container agent daemon to properly manage container lifecycles, configs, and events via gRPC. The clawker cli will just be the scheduler to control plane, and handle user UI direct with the containers. This will keep container stdout/err sacred and allow for more robust features, better monitoring, better loop control, peering communications, and a more seamless experience overall. This is the main focus of my next set of work on clawker. See: control plane notes
• Linux might have a bug involving accessing the keychain for creds, I haven't focused on linux I'll do this in parallel with control plane work
• The TUI/UI formatting is mainly a polished turd currently, I'm aware of this. It's functional, but it'll be the last thing I really care about
• Being my first vibe coding experience, I come across some utterly insane, often painful, sometimes funny quality issues from good ole claude boy.
• I'm realizing it's probably trivial (just jinxed myself) to swap out different AI agents as the container entrypoint beyond claude code. So I am considering adding options for what AI agent you want. Making clawker essentially a general "harness for the harness" / agent-in-container solution

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

I feel obligated to state this... Clawker is a portmanteau of Claude + Docker. The project was at first named claucker, but reading it, saying it, and especially typing it always felt awkward to my brain because it violates the phonetic rules of English. Before I was aware of the whole clawdbot openclaw clawthis clawthat naming craze, I changed it to be the "correct" phonetic spelling, clawker, purely because it just rolls off the fingers when typing it. For those reasons I'm not going to change the name, but I want to make it clear the decision wasn't to chase a trend