clawker

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.

Planned features and fixes

• Linux support (untested)
• Windows support
• Versioning and releases with CI/CD integration
• Terminal UI improvements (redraw on reattach, status indicators, progress bars, styling); current output can conflict with Claude's Ink-based TUI (see Known Issues)
• Auto pruning to manage disk usage
• Man pages and helper docs
• Docker MCP Toolkit support (currently a known “feature-not-a-bug”: MCP plugin inside a container doesn’t detect Docker Desktop)
• Host proxy browser auth: re-attach before authenticating can break the flow (low priority)
• Grafana pre-built dashboard improvements (currently basic POC)
• Improved host Claude directory mounting strategy to avoid permission issues and settings

Quick Start

Prerequisites: Docker running, Go 1.25+

# Install
git clone https://github.com/schmitthub/clawker.git
cd clawker && go build -o ./bin/clawker ./cmd/clawker
export PATH="$PWD/bin:$PATH"

# One-time user setup (creates ~/.local/clawker/settings.yaml)
clawker init

# Start a project
cd your-project
clawker project init  # Creates clawker.yaml

Cuztomize your build in clawker.yaml (see below), then build your project's image:

clawker build

Create and run some agents. In this example you'll create a main agent for interactive working sessions, and another for YOLO unattended work.

# Create a fresh container, start it, and connect interactively.
# Use Claude Code as normal. This will feel just like running it on your host.
# Clawker adds a status line so you know this session is containerized by clawker and which agent you're using.
# Subscription users will need authenticate via browser.
# The @ symbol auto-resolves your project's image (clawker-<project>:latest)
clawker run -it --agent main @

# hit crtl+p, ctrl+q to detach without stopping the container. You can leave sessions running

# Re-attach to the main agent
clawker attach --agent main

# Stop the agent with ctrl-c, this is like exiting Claude Code normally. When Claude exits, the container stops.

# Start the main agent and attach to it in interactive mode
clawker start -a -i --agent main

# Detach with crtl+p, ctrl+q

# Stop the main agent from the host
clawker stop --agent main

# Lets start a new agent in interactive mode and give it a modified start command for YOLOing
# authenticate if needed, then use Claude Code as normal. hit crtl+p, ctrl+q to detach, or ctlr+c to stop the container
clawker run -it --agent ralph @ -- --dangerously-skip-permissions

clawker stop --agent ralph # if you detached instead of exiting

# start up ralph (subscription users need to run interactively first to authenticate like above)
clawker start --agent ralph
# send a prompt to run your ralph agent, you can use this in scripts
echo "hi" | clawker container exec --agent ralph claude -p

You now have two specialized claude code containers that can be attached to or started/stopped as needed for different purposes

Customizing Your Build

The default clawker image includes essentials for most projects: git, curl, vim, zsh, ripgrep, and more. But your project likely needs language-specific tools. Here's how to customize your clawker.yaml.

Example: TypeScript/React Project

Let's add Node.js (via nvm) and pnpm to a project:

version: "1"
project: "my-react-app"

build:
  # Start with Debian bookworm (has build essentials)
  image: "buildpack-deps:bookworm-scm"

  # System packages (apt-get install)
  packages:
    - git
    - curl
    - ripgrep

  instructions:
    # Environment variables baked into the image
    env:
      NVM_DIR: "/home/claude/.nvm"
      NODE_VERSION: "22"

    # Commands run as the claude user
    user_run:
      # Install nvm
      - cmd: |
          curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

      # Install Node.js and pnpm
      - cmd: |
          . "$NVM_DIR/nvm.sh" && \
          nvm install $NODE_VERSION && \
          npm install -g pnpm

      # Add nvm to shell profile
      - cmd: |
          echo '. "$NVM_DIR/nvm.sh"' >> ~/.bashrc

Build Properties

More Examples

See the examples/ directory for complete configurations:

• typescript-react.yaml - Node.js via nvm, pnpm
• python.yaml - Python via uv (fast package manager)
• rust.yaml - Rust via rustup
• go.yaml - Go with gopls and delve
• csharp.yaml - .NET SDK
• php.yaml - PHP with Composer

Workflows

The @ image shortcut

Use @ as the image argument 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 @

Resolution order: project image (clawker-<project>:latest) → default_image from settings/config.

Starting containers

# Bind mode (default) - changes workspace sync to host immediately
clawker start --agent dev

# Snapshot mode - isolated copy, use git to sync changes back to host
clawker start --agent sandbox --mode snapshot

Passing Claude Code options

# Using --agent to select the container? Use -- to separate clawker flags from Claude flags
clawker run -it --rm --agent ralph @ -- --dangerously-skip-permissions

# or give it an explicit image to use
clawker image list
clawker run -it --rm clawker-myproject:latest -- --dangerously-skip-permissions

Detach and reattach

# Detach from running container: Ctrl+P, Ctrl+Q

# Reattach later
clawker container attach --agent ralph
# or
clawker container attach clawker.myproject.ralph

List and manage containers

clawker container ls              # List all clawker containers
clawker ps                     # Alias for container ls
clawker container stop --agent ralph

Scripted Workflows (Wiggum Pattern)

The wiggum pattern runs Claude Code in autonomous loops with scripted prompts.

Subscription users: You must authenticate interactively first. Run clawker run -it --agent <name> @, complete browser OAuth, then exit. After that, scripted usage works because credentials persist in the config volume.

Keep container running and use exec

# Create and auth, then detach with Ctrl+P, Ctrl+Q
clawker run -it --agent ralph @ -- --dangerously-skip-permissions

# Send prompts via exec (new claude process per task)
echo "Fix the tests" | clawker exec -i --agent ralph claude -p

# Stop when done
clawker stop --agent ralph

Continuous loop (wiggum style)

#!/bin/bash
# wiggum.sh - Run Claude in a loop until task complete. Requires prior container creation and auth.

AGENT="worker"
TASK="Review the codebase and fix any bugs you find"

while true; do
  echo "$TASK" | clawker exec --agent "$AGENT" claude -p

  read -p "Continue? [y/N] " -n 1 -r
  echo
  [[ ! $REPLY =~ ^[Yy]$ ]] && break
done

Parallel agents with worktrees

#!/bin/bash
# parallel-agents.sh - Run multiple agents on different branches. Requires prior container creation and auth.

# Create worktrees
git worktree add ../myapp-w1 -b feature/auth
git worktree add ../myapp-w2 -b feature/tests

# Auth each agent first (one-time, interactive)
# cd ../myapp-w1 && clawker run -it --agent w1 @  # complete OAuth, then exit with Ctrl+C
# cd ../myapp-w2 && clawker run -it --agent w2 @  # complete OAuth, then exit with Ctrl+C

# Run tasks in parallel
cd ../myapp-w1 && echo "Implement user auth" | clawker exec --agent w1 claude -p &
cd ../myapp-w2 && echo "Write integration tests" | clawker exec --agent w2 claude -p &
wait

echo "Both agents finished"

Autonomous Loops with Ralph

Ralph runs Claude Code in autonomous loops with built-in stagnation detection, progress tracking, and circuit breaker protection. It's the "Ralph Wiggum" technique - let Claude keep going until it's done or stuck.

Quick Start (API Key Users)

# 1. Setup project (if not done)
cd your-project
clawker project init

# 2. Add RALPH_STATUS instructions to CLAUDE.md (see Step 3 below)

# 3. Build image
clawker build

# 4. Create container with API key
export ANTHROPIC_API_KEY="sk-ant-..."
clawker run -it --agent ralph @

# 5. Run ralph (in another terminal, or after exiting)
clawker ralph run --agent ralph --prompt "Fix all failing tests"

Quick Start (Subscription Users)

# 1. Setup project (if not done)
cd your-project
clawker project init

# 2. Add RALPH_STATUS instructions to CLAUDE.md (see Step 3 below)

# 3. Build image
clawker build

# 4. Create and authenticate (one-time per agent)
clawker run -it --agent ralph @
# Complete browser OAuth when prompted
# Then Ctrl+C to exit (credentials persist in config volume)

# 5. Run ralph
clawker ralph run --agent ralph --prompt "Fix all failing tests"

Step-by-Step Setup

Step 1: Prerequisites

• Docker running
• clawker installed (go build -o ./bin/clawker ./cmd/clawker)
• User settings initialized (clawker init)
• Project with clawker.yaml (clawker project init)

Step 2: Add Ralph Configuration to clawker.yaml

Add this section to your clawker.yaml:

ralph:
  max_loops: 50                   # Maximum loops before stopping (default: 50)
  stagnation_threshold: 3         # Loops without progress before circuit trips (default: 3)
  timeout_minutes: 15             # Per-loop timeout in minutes (default: 15)
  calls_per_hour: 100             # Rate limit: max calls per hour, 0 to disable (default: 100)
  completion_threshold: 2         # Completion indicators required for strict mode (default: 2)
  session_expiration_hours: 24    # Session TTL, auto-reset if older (default: 24)
  same_error_threshold: 5         # Same error repetitions before circuit trips (default: 5)
  output_decline_threshold: 70    # Output decline percentage that triggers trip (default: 70)
  max_consecutive_test_loops: 3   # Test-only loops before circuit trips (default: 3)
  loop_delay_seconds: 3           # Seconds to wait between loop iterations (default: 3)
  safety_completion_threshold: 5  # Force exit after N loops with completion indicators (default: 5)
  skip_permissions: false         # Pass --dangerously-skip-permissions to claude (default: false)

Step 3: Add RALPH_STATUS Instructions to CLAUDE.md

This is the critical step. Add this section to your project's CLAUDE.md file:

## Ralph Autonomous Loop Integration

When running in an autonomous loop via `clawker ralph run`, output a RALPH_STATUS
block at the end of EVERY response. This tells the loop controller your progress.

### RALPH_STATUS Block Format

```
---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one line summary>
---END_RALPH_STATUS---
```

### Field Definitions

| Field | Values | Description |
|-------|--------|-------------|
| STATUS | IN_PROGRESS, COMPLETE, BLOCKED | Current work state |
| TASKS_COMPLETED_THIS_LOOP | 0-N | Discrete tasks finished this iteration |
| FILES_MODIFIED | 0-N | Files changed this iteration |
| TESTS_STATUS | PASSING, FAILING, NOT_RUN | Current test suite state |
| WORK_TYPE | IMPLEMENTATION, TESTING, DOCUMENTATION, REFACTORING | What you did |
| EXIT_SIGNAL | true/false | Set true when ALL work is complete |
| RECOMMENDATION | text | Brief note on progress or next steps |

### Important Rules

1. **Always output the block** - Every response must end with RALPH_STATUS
2. **Be honest about progress** - TASKS_COMPLETED must reflect real work
3. **Signal completion clearly** - Set EXIT_SIGNAL: true only when truly done
4. **Include completion phrases** - When done, use phrases like:
   - "all tasks complete"
   - "project ready"
   - "work is done"
   - "implementation complete"
   - "no more work"
   - "finished"
   - "task complete"
   - "all done"
   - "nothing left to do"
   - "completed successfully"

### Example: Work in Progress

```
---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 2
FILES_MODIFIED: 4
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Continue with user authentication module
---END_RALPH_STATUS---
```

### Example: All Work Complete

```
All tasks are now complete. The feature has been fully implemented and tested.

---RALPH_STATUS---
STATUS: COMPLETE
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 2
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: true
RECOMMENDATION: All work complete, ready for review
---END_RALPH_STATUS---
```

### Example: Blocked

```
---RALPH_STATUS---
STATUS: BLOCKED
TASKS_COMPLETED_THIS_LOOP: 0
FILES_MODIFIED: 0
TESTS_STATUS: FAILING
WORK_TYPE: TESTING
EXIT_SIGNAL: false
RECOMMENDATION: Tests failing due to missing database fixture
---END_RALPH_STATUS---
```

Step 4: Build and Authenticate

# Build your project's image
clawker build

# For API key users:
export ANTHROPIC_API_KEY="sk-ant-..."
clawker run -it --agent ralph @
# Exit with Ctrl+C when ready

# For subscription users:
clawker run -it --agent ralph @
# Complete browser OAuth when prompted
# Then either:
#   - Continue working interactively, OR
#   - Exit with Ctrl+C (container stops, credentials persist)
#   - Detach with Ctrl+P, Ctrl+Q (container stays running)

Step 5: Run Ralph

# Basic run with initial prompt
clawker ralph run --agent ralph --prompt "Fix all failing tests"

# Run from a prompt file
clawker ralph run --agent ralph --prompt-file task.md

# Continue an existing session (no prompt needed)
clawker ralph run --agent ralph

# YOLO mode (skip all permission prompts)
clawker ralph run --agent ralph --skip-permissions --prompt "Build feature X"

# With live monitoring
clawker ralph run --agent ralph --monitor --prompt "Implement auth"

# With custom limits
clawker ralph run --agent ralph --max-loops 100 --stagnation-threshold 5

# With rate limiting (5 calls per hour)
clawker ralph run --agent ralph --calls 5

Step 6: Monitor Progress

# Check current session status
clawker ralph status --agent ralph

# Output as JSON for scripting
clawker ralph status --agent ralph --json

# View container logs
clawker container logs --agent ralph --follow

# Attach to see live output
clawker container attach --agent ralph
# Detach with Ctrl+P, Ctrl+Q

Step 7: Troubleshooting

Circuit breaker tripped?

# Check why
clawker ralph status --agent ralph

# Reset circuit breaker
clawker ralph reset --agent ralph

# Reset circuit AND session history
clawker ralph reset --agent ralph --all

# Retry
clawker ralph run --agent ralph

Session expired? Sessions expire after 24 hours by default. Run again to start fresh.

Rate limit hit? Ralph detects Claude's API rate limits. Wait ~5 hours and retry.

Circuit Breaker Protection

Ralph's circuit breaker automatically stops loops when it detects problems:

Completion indicators detected: all tasks complete, project ready, work is done, implementation complete, no more work, finished, task complete, all done, nothing left to do, completed successfully

YOLO Mode (Skip All Permission Prompts)

YOLO mode allows Claude to execute any command without asking for permission.

# Via CLI flag
clawker ralph run --agent ralph --skip-permissions --prompt "Build feature X"

# Or configure in clawker.yaml
ralph:
  skip_permissions: true

Warning: YOLO mode allows Claude to run any command without asking. Use only in sandboxed containers where you trust the task definition.

Dockerfile Generation

Want to use Docker directly without clawker's management? The generate command creates clawker boilerplate Dockerfiles using any Claude Code npm tag or version.

# Generate Dockerfiles for latest version
clawker generate latest

# Generate for multiple versions
clawker generate latest stable 2.1

# Output to specific directory
clawker generate --output ./dockerfiles latest

Files are saved to ~/.local/clawker/build/dockerfiles/$claudeCodeVersion-$baseImage.dockerfile by default. Then build with Docker:

docker build -t my-claude:latest ~/.local/clawker/build/dockerfiles/2.1.12-bookworm.dockerfile

You can also use the standalone clawker-generate in ./cmd/clawker-generate/ if all you need is Dockerfile generation.

go build -o ./bin/clawker-generate ./cmd/clawker-generate
./bin/clawker-generate latest next stable 2.1

Commands

LLM-friendly docs: Complete command documentation with all flags and examples is available in docs/markdown/ for AI assistants and tooling.

Clawker mirrors Docker's CLI structure for familiarity. If you know Docker, you know clawker.

Management commands (container, image, volume, network, project) support the same verbs as Docker: ls, inspect, rm, prune.

Isolation Features

Clawker is a port of the Docker CLI, not just a passthrough. It adds isolation features to keep your system safe from rogue Claude Code agents, and provides clawker-only isolation when running docker-like commands.

• clawker-only resource isolation when running docker-like commands, you don't have to worry about filters. Clawker only sees its own resources, so you don't accidentally delete or modify other docker resources. This is done via labels under the hood.
• per-project resource namespacing, so you can have multiple projects on the same host without conflicts. Each project gets its own set of containers, images, volumes, and networks, identified by labels.
• per-agent containerization, so each agent runs in its own isolated container. You can have multiple agents running simultaneously without interference.
• Network firewalling, so you can restrict outbound network access from containers. By default, all outbound traffic is blocked except for allowed domains in a firewall init script.
• All clawker resources are added to a docker network clawker-net so they can communicate if needed.

Authentication & Git

API Key Users

Using an API key? Just pass it as an environment variable:

clawker run -it --rm -e ANTHROPIC_API_KEY @

Or set it in your shell and clawker forwards it automatically.

Subscription Users

The problem: Containers have their own localhost. When Claude Code opens a browser for OAuth, the callback goes to the wrong place.

The solution: Clawker runs a lightweight host proxy that bridges the gap.

Auth Flow:

Container                    Host Proxy (:18374)              Browser
    |                               |                             |
    | Claude needs auth             |                             |
    | ---------------------------->| intercepts OAuth URL         |
    |                              | rewrites callback ---------->|
    |                              |                  user logs in|
    |                              |<-------- callback redirect   |
    |<-- forwards to container     |                             |
    | Auth complete!               |                             |

Git Credentials

• HTTPS: Forwarded via host proxy (GitHub CLI, macOS Keychain, Git Credential Manager all work)
• SSH: Agent forwarding (your keys never leave the host)
• Config: ~/.gitconfig copied automatically

Zero config - if git works on your host, it works in containers.

Monitoring

Optional observability stack for tracking resource usage across all your clawker containers.

clawker monitor start    # Starts Prometheus + Grafana
clawker monitor stop     # Stops the stack
clawker monitor status   # Check if running

Protip You can also monitor your host's claude sessions with this stack just by setting these env vars:

OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_METRICS_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES=agent=host.clawker # ie host.project name
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

Dashboard: http://localhost:3000

System Overview

+---------------------------------------------------------------------+
|                              HOST                                    |
|                                                                      |
|  +--------------+         +--------------------------------------+  |
|  |              |         |            CONTAINER                  |  |
|  |  clawker CLI |-------->|  +--------------------------------+  |  |
|  |              |         |  |         Claude Code            |  |  |
|  +--------------+         |  +--------------------------------+  |  |
|         |                 |                                       |  |
|         |                 |  /workspace (bind or snapshot)        |  |
|         |                 |  /home/claude/.claude (persisted)     |  |
|         |                 |  /commandhistory (persisted)          |  |
|         v                 |                                       |  |
|  +--------------+         |  Scripts:                             |  |
|  |  Host Proxy  |<--------|  - host-open (browser URLs)           |  |
|  |   (:18374)   |         |  - callback-forwarder (OAuth)         |  |
|  |              |         |  - git-credential-clawker (HTTPS)     |  |
|  | - OAuth      |         |  - clawker-socket-server (SSH/GPG)    |  |
|  | - Git creds  |         +--------------------------------------+  |
|  | - URL open   |                                                    |
|  +--------------+         +--------------------------------------+  |
|         |                 |         MONITORING (optional)         |  |
|         |                 |  Prometheus + Grafana (:3000)         |  |
|         v                 +--------------------------------------+  |
|  +--------------+                                                    |
|  |    Docker    |                                                    |
|  |    Daemon    |                                                    |
|  +--------------+                                                    |
+---------------------------------------------------------------------+

Configuration

User Settings (~/.local/clawker/settings.yaml)

Global defaults that apply across all projects. Local clawker.yaml takes precedence.

project:
  # Default image when not specified in project config or CLI
  default_image: "node:20-slim"

# Registered project directories (managed by 'clawker init')
projects:
  - /Users/you/Code/project-a
  - /Users/you/Code/project-b

# Logging configuration (all values shown are defaults)
logging:
  file_enabled: true   # Enable file logging
  max_size_mb: 50      # Max size before rotation
  max_age_days: 7      # Days to keep old logs
  max_backups: 3       # Number of rotated files to keep

Log location: ~/.local/clawker/logs/clawker.log

Logs are JSON-formatted and include project/agent context when available, making it easy to filter logs when running multiple containers:

# View recent logs
cat ~/.local/clawker/logs/clawker.log | jq .

# Filter by project
cat ~/.local/clawker/logs/clawker.log | jq 'select(.project == "myapp")'

# Filter by agent
cat ~/.local/clawker/logs/clawker.log | jq 'select(.agent == "ralph")'

Project Config (clawker.yaml)

Project-specific configuration. Run clawker init to generate a template.

version: "1"
project: "my-app"

build:
  # Base image for the container
  image: "node:20-slim"
  # Optional: path to custom Dockerfile (skips generation)
  # dockerfile: "./.devcontainer/Dockerfile"
  # System packages to install
  packages:
    - git
    - curl
    - ripgrep
  # Build arguments
  # build_args:
  #   NODE_VERSION: "20"
  # Dockerfile instructions
  instructions:
    env:
      NODE_ENV: "production"
    # copy:
    #   - { src: "./config.json", dest: "/etc/app/" }
    # root_run:
    #   - { cmd: "mkdir -p /opt/app" }
    # user_run:
    #   - { cmd: "npm install -g typescript" }
  # Raw Dockerfile injection (escape hatch)
  # inject:
  #   after_from: []
  #   after_packages: []

agent:
  # Files to include in Claude's context
  includes:
    - "./README.md"
    - "./.claude/memory.md"
  # Environment variables for Claude
  env:
    NODE_ENV: "development"
  # Shell, editor, visual settings
  # shell: "/bin/bash"
  # editor: "vim"
  # visual: "vim"

workspace:
  # Container path for your code
  remote_path: "/workspace"
  # Default mode: "bind" or "snapshot"
  default_mode: "bind"

security:
  # Network firewall configuration
  firewall:
    enable: true              # Enable network firewall (default: true)
    # add_domains:            # Add to default allowed domains
    #   - "api.openai.com"
    # remove_domains:         # Remove from default allowed domains
    #   - "registry.npmjs.org"
    # override_domains:       # Replace entire domain list (ignores add/remove)
    #   - "github.com"
  # Docker socket access (disabled for security)
  docker_socket: false
  # Host proxy for browser auth (enabled by default)
  # enable_host_proxy: true
  # Git credential forwarding (all enabled by default)
  # git_credentials:
  #   forward_https: true   # Forward HTTPS credentials via host proxy
  #   forward_ssh: true     # Forward SSH agent for git+ssh
  #   copy_git_config: true # Copy host ~/.gitconfig
  # Add Linux capabilities
  # cap_add:
  #   - NET_ADMIN

Security Defaults

The whail Engine

Under the hood, clawker uses whail (whale jail) - a reusable Go package that decorates the Docker client with label-based resource isolation.

What it does:

• Applies com.clawker.managed=true labels during resource creation
• Injects label filters on list/inspect operations
• Refuses to operate on resources it didn't create

This means clawker can never accidentally touch your other Docker resources.

# Docker sees everything
docker image list
# IMAGE                         ID             ...
# buildpack-deps:bookworm-scm   9be56c3e5291   ...
# clawker-myproject:latest      83a204a19dcb   ...
# postgres:15                   abc123def456   ...

# Clawker only sees its own resources
clawker image list
# IMAGE                    ID            ...
# clawker-myproject:latest 83a204a19dcb  ...

whail is designed to be reusable for building similar containerized AI agent wrappers.

Known Issues

Exiting a container (ctrl+c) pre-authenticating breaks input

If you start a container and try to exit it with ctrl+c before authenticating and accepting use risk warnings, claude code will sometimes hijack the input, not letting you actually exit. Workaround is to detach with ctrl+p, ctrl+q instead, then stop the container with clawker container stop --agent NAME.

Docker MCP Gateway doesn't work inside containers

The Docker MCP Gateway doesn't start inside of containers. This is a known "feature not a bug" situation. see: https://github.com/docker/mcp-gateway/issues/112#issuecomment-3263238111

Contributing

# Development setup
git clone https://github.com/schmitthub/clawker.git
cd clawker
go build -o ./bin/clawker ./cmd/clawker
go test ./...

Issues and PRs welcome at github.com/schmitthub/clawker.

License

MIT