{"id":44844408,"url":"https://github.com/schmitthub/clawker","last_synced_at":"2026-05-23T01:11:57.485Z","repository":{"id":338904446,"uuid":"1129396406","full_name":"schmitthub/clawker","owner":"schmitthub","description":"Claude Code agent-in-container orchestration and automation ","archived":false,"fork":false,"pushed_at":"2026-05-13T09:08:02.000Z","size":11576,"stargazers_count":15,"open_issues_count":28,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-13T10:14:59.572Z","etag":null,"topics":["agent-container","agent-containment","agent-safety","agent-sandbox","agent-sandboxes","ai","ai-agent","ai-agents","ai-container","ai-sandbox","ai-sandboxes","claude","claude-code","containerization","docker","go","golang","llm"],"latest_commit_sha":null,"homepage":"https://docs.clawker.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/schmitthub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T03:18:22.000Z","updated_at":"2026-05-12T05:28:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"08b05f96-1031-4e95-aa7d-66db901f2105","html_url":"https://github.com/schmitthub/clawker","commit_stats":null,"previous_names":["schmitthub/clawker"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/schmitthub/clawker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmitthub%2Fclawker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmitthub%2Fclawker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmitthub%2Fclawker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmitthub%2Fclawker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/schmitthub","download_url":"https://codeload.github.com/schmitthub/clawker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/schmitthub%2Fclawker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33233074,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-19T15:49:41.270Z","status":"ssl_error","status_checked_at":"2026-05-19T15:49:22.917Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-container","agent-containment","agent-safety","agent-sandbox","agent-sandboxes","ai","ai-agent","ai-agents","ai-container","ai-sandbox","ai-sandboxes","claude","claude-code","containerization","docker","go","golang","llm"],"created_at":"2026-02-17T04:14:51.198Z","updated_at":"2026-05-19T21:01:33.661Z","avatar_url":"https://github.com/schmitthub.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Clawker: Claude Code agent-in-container orchestration and automation\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://golang.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat\u0026logo=go\" alt=\"Go\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://deepwiki.com/schmitthub/clawker\"\u003e\u003cimg src=\"https://deepwiki.com/badge.svg\" alt=\"Ask DeepWiki\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/Platform-macOS-lightgrey?logo=apple\" alt=\"macOS\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/Platform-Linux-4DA3FF?logo=linux\u0026logoColor=fff\u0026labelColor=0057B8\" alt=\"Linux\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"https://img.shields.io/badge/Claude-D97757?logo=claude\u0026logoColor=fff\" alt=\"Claude\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Vibe coded with love\" src=\"https://img.shields.io/badge/Vibe%20coded%20with-%F0%9F%92%97-1f1f1f?labelColor=ff69b4\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ccode\u003eclawker\u003c/code\u003e is a cli for orchestrating, monitoring, and automating portable \u003ccode\u003edevcontainers\u003c/code\u003e for \u003ccode\u003eClaude Code\u003c/code\u003e agents. It works on any MacOS/Linux host with docker installed. I wrote this because I didn't want to have to pay someone to run claude code agents with \u003ccode\u003e--dangerously-skip-permissions\u003c/code\u003e when containers have been around for a decade, and claude code's sandbox mode is the temu version of a container. \u003ccode\u003eclawker\u003c/code\u003e offers many 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).\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/threat-model.png\" alt=\"Threat Model: Bare Metal vs Sandbox vs Clawker Container\" width=\"700\"\u003e\n\u003c/div\u003e\n\n\u003e Read more about clawker's threat model and security philosophy at [docs.clawker.dev/threat-model](https://docs.clawker.dev/threat-model)\n\n\u003e ! 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\n\n---\n\n## Table of Contents\n\n- [Clawker: Claude Code agent-in-container orchestration and automation](#clawker-claude-code-agent-in-container-orchestration-and-automation)\n  - [Table of Contents](#table-of-contents)\n  - [High-Level Feature Overview](#high-level-feature-overview)\n  - [Installation](#installation)\n  - [Quick Start](#quick-start)\n  - [Walkthrough](#walkthrough)\n    - [Initialize a project](#initialize-a-project)\n      - [Run a container](#run-a-container)\n  - [Creating and Using Containers](#creating-and-using-containers)\n  - [The `@` Image Shortcut](#the--image-shortcut)\n  - [Working with Worktrees](#working-with-worktrees)\n  - [Managing Resources](#managing-resources)\n  - [Monitoring](#monitoring)\n  - [Roadmap / Known Issues](#roadmap--known-issues)\n  - [Contributing](#contributing)\n  - [License](#license)\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003eBoring TLDR backstory\u003c/summary\u003e\nThe 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.\n\nWhen I began experimenting with Claude Code to keep up with the Agentic AI trend, I was surprised by the total absence of local development container offerings for using it. Claude Code's sandbox mode is lackluster; the only other options for isolation and orchestration involve paid remote services, which seems silly to me—we've had containers for over a decade now. The Claude Code docs recommend using containers, but they only offer a devcontainer example, which is a step in the right direction but leaves you coupled to the IDE. The DIY approach results in managing multiple Claude Code Dockerfiles, maybe a container registry, per language stack/project, which also sucks, and there are a lot of internals that devcontainers offer that vanilla containers don't have. So I decided to build something that abstracts away all the complexity of creating, managing, automating, and running Claude Code in containers with Docker. It served as a good project to learn the ways of \"Agentic Engineering\" and \"vibing\" (exhausting btw, beware of some hilarious slop I've been cleaning up in this code base), but Clawker has become very useful for me, so I've decided to open source it for anyone yearning for a better local development container experience.\n\u003c/details\u003e\n\n## High-Level Feature Overview\n\n- **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. The per-container `clawkerd` daemon runs as PID 1, handles signal forwarding, drops privilege to the unprivileged `claude` user kernel-side, and supervises the user CMD for the container's lifetime\n- **Per-host clawker control plane** (`clawker-controlplane` container) runs as a long-lived supervisor — it owns the firewall lifecycle, eBPF program lifetime, agent identity registry (sqlite), mTLS auth, and the command channel to every agent's `clawkerd`. The CLI talks to it over mTLS gRPC + OAuth2; see `clawker controlplane status`, `clawker controlplane agents`\n- **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)\n- **Injectable build-time instructions** to customize images per project: packages, environment variables, root run commands, user run commands, and more\n- **Bind or snapshot workspace modes**: mount your repository to the container for live editing, or copy it at runtime for pure isolation\n- **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\n- **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\n- **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`\n- **Configurable environment variables**: set or copy environment variables and env files from the host into containers at runtime\n- **Injectable post-initialization bash script** that runs after the container starts but before Claude Code launches, letting you set up MCPs, etc.\n- **Envoy + custom CoreDNS + eBPF network firewall** enabled by default — Envoy and a custom CoreDNS build run as managed Docker containers on the shared `clawker-net` network, while eBPF cgroup programs (loaded and attached from outside agent containers by the control plane) redirect TCP to Envoy and DNS to CoreDNS. Provides DNS-level deny-by-default (unlisted domains return NXDOMAIN), per-domain TCP routing via a real-time BPF DNS cache, and TLS inspection with per-domain MITM certificates for path-level filtering. Agent containers themselves get **no Linux capabilities** — all enforcement happens kernel-side, outside the container's privilege scope. System-required rules (Claude API, Docker registry) are always present; project rules merge additively. Manage rules dynamically with `clawker firewall add/remove/list/status`, temporarily bypass with `clawker firewall bypass 5m --agent \u003cagent_name\u003e`, or disable entirely. A great security layer to mitigate runaway agents or prompt injections while giving them the network access they need.\n- **Toggleable read-only global share**: volume mount from the host giving all containers real-time access to files you place in it\n- **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.\n- **Dedicated Docker network** that all containers run in\n- **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.\n- **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\n- **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\n- **Optional monitoring stack** — OTel Collector + OpenSearch (logs) + OpenSearch Dashboards + Prometheus (metrics) on `clawker-net`. Every container has the environment variables baked in to push OTLP telemetry when the stack is running, and is silenced when it isn't\n- **Interactive configuration editing**: TUI-based editors for project config (`clawker project edit`) and user settings (`clawker settings edit`) with tabbed field browsing, per-field type-appropriate editors (text, boolean, list, multiline), layer-aware provenance display showing which file each value comes from, and per-field save targeting to choose which config layer to write to\n\n## Installation\n\n**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).\n\n**Homebrew** (macOS):\n```bash\nbrew install schmitthub/tap/clawker\n```\n\n**Install script** (macOS / Linux):\n```bash\ncurl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | bash\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eMore options\u003c/summary\u003e\n\n**Specific version:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_VERSION=v0.1.3 bash\n```\n\n**Custom directory:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/schmitthub/clawker/main/scripts/install.sh | CLAWKER_INSTALL_DIR=$HOME/.local/bin bash\n```\n\n**Build from source** (requires Go 1.25+):\n```bash\ngit clone https://github.com/schmitthub/clawker.git\ncd clawker \u0026\u0026 make clawker\nexport PATH=\"$PWD/bin:$PATH\"\n```\n\u003c/details\u003e\n\n## Quick Start\n\nThe 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.\n\n```bash\ncd your-project\nclawker init \nclawker build\nclawker run -it --rm --agent dev @ --dangerously-skip-permissions\n```\n\nYou can ask claude code to assist you in writing a more appropriate config file for the project using this prompt: \n\n```bash\ncreate a @.clawker.yaml file appropriate for this repos stack. Clawker configuration can be understood here: https://docs.clawker.dev/configuration.md\n```\n\nThis:\n- Builds a project-scoped container image (`clawker-\u003cproject\u003e:latest`, with `@` as a shortcut when you are in the project directory), using the default Dockerfile template\n- Starts and attaches your terminal to the container (`clawker.\u003cproject\u003e.dev`) using that image (via the `@` identifier), with your current working directory bind-mounted (i.e., live share)\n- Copies your host Claude Code settings, plugins, authentication, skills, etc. for a seamless transition from host to container development.\n \nThe `--rm` flag removes the container when you exit, so it's perfect for quick tasks or experimentation.\nIf you want persistence, omit `--rm` and start the same container again later with `clawker start -a -i --agent example`.\nYou can also keep it running by detaching (`Ctrl+P`, `Ctrl+Q`) and reattach later with `clawker attach --agent example` to the same terminal session.\n\nIf you want to learn more about image customization, worktree support, monitoring, and other bells and whistles, keep reading for the walkthrough below.\n\n## Walkthrough\n\nHere are ways I'm using `clawker` today and how I'm finding it useful. \n\n### Initialize a project\n\n```bash\ncd your-project\nclawker init            # Guided setup: pick a language preset → creates .clawker.yaml, .clawkerignore, registers project\n```\n\n`clawker init` walks you through a guided setup with language-based presets (Python, Go, Rust, TypeScript, Java, Ruby, C/C++, C#/.NET, Bare). Choose a preset or \"Build from scratch\" to customize every field. User settings (`~/.config/clawker/settings.yaml`) and XDG directories are bootstrapped automatically on first run.\n\n\u003e **Tip:** Install the **clawker-support plugin** to get hands-on help from a clawker specialist agent. It can walk you through configuration, MCP wiring, firewall rules, troubleshooting, and more — it reads the real Dockerfile template and config schema and gives you the exact YAML you need.\n\u003e ```bash\n\u003e # Via clawker CLI (recommended)\n\u003e clawker skill install\n\u003e\n\u003e # Or manually\n\u003e claude plugin marketplace add schmitthub/claude-plugins\n\u003e claude plugin install clawker-support@schmitthub-plugins\n\u003e ```\n\u003e You can also customize your image using `clawker project edit` or point Claude Code at the LLM-friendly [docs site](https://docs.clawker.dev/configuration) for the full config reference. I dogfood clawker to build clawker, so also check out my `clawker.yaml` to see how I customized the build config for golang development.\n\n\u003e **Tip** You can alternatively use `.clawker/clawker.yaml` (which takes precedence). 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.\n\n```bash\nclawker build           # Builds your project's image (referenced as \"@\" when within a project directory)\n```\n\n#### Run a container \n\nMy 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`. \n\nSo 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...\n\n```bash\nclawker run -it --rm --agent dev --worktree hotfix/example:main @ --dangerously-skip-permissions\n```\n\nThis 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 dev`. 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.  \n\nI 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`. \n\n```bash\n$ clawker worktree list\nBRANCH     PATH                                                                      HEAD     MODIFIED     STATUS\na/example  /Users/schmitthub/.local/share/clawker/worktrees/repo-project-uuidsha256  f20aa37  1 hour ago   healthy\n```\n\nWhen I'm done I easily remove the worktree \n\n```bash\nclawker 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\n```\n\nIf 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)\n\n```bash\nclawker monitor init\nclawker monitor up\nclawker monitor status \n# stop it later on \nclawker monitor down\n```\n\nNow I can go to OpenSearch Dashboards at http://localhost:5601 and inspect logs from every agent — costs, tokens, tool executions, decisions, prompts, api calls — and pull metrics from Prometheus at http://localhost:9090. (you can also set env vars in your host shell and it will report to this stack)\n\n```bash\n# Host ENV var example\n# Add these to your shell profile / .env etc\nOTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318\nOTEL_METRICS_EXPORTER=otlp\nOTEL_LOGS_EXPORTER=otlp\nOTEL_TRACES_EXPORTER=otlp\nOTEL_LOGS_EXPORT_INTERVAL=5000\nOTEL_METRIC_EXPORT_INTERVAL=10000\nOTEL_METRICS_INCLUDE_ACCOUNT_UUID=true\nOTEL_METRICS_INCLUDE_SESSION_ID=true\nCLAUDE_CODE_ENABLE_TELEMETRY=1\nCLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1\nOTEL_LOG_TOOL_DETAILS=1\nOTEL_LOG_USER_PROMPTS=1\n\n# Add this to a project level .env \nPROJECT_NAME=MyGroundbreakingTodoApp\nOTEL_RESOURCE_ATTRIBUTES=service.name=claude-code,project=$PROJECT_NAME,agent=host\n```\n\nWhen 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.\n\nAll containers get named volume mounts for their claude config directories and command history for persistence.\n\n```bash\n$ clawker volume ls\nVOLUME NAME                                  DRIVER  MOUNTPOINT\nclawker.clawker.example-config               local   ...er/volumes/clawker.clawker.example-config/_data\nclawker.clawker.example-history              local   ...r/volumes/clawker.clawker.example-history/_data\n# You can see the resources naming conventions here (clawker.{project}.{agent}). Labeling works similarly\n```\n\nYou can also see how clawker is jailed from other docker resource access...\n\n```bash\n$ docker create alpine:latest\n6c6896073eb1a2baa91450d0b5b795808f0ea4a052f729383a2d166d87fa0c17\n$ clawker ps -a\nNAME                     STATUS                  PROJECT                AGENT                  IMAGE                   CREATED\nclawker.clawker.example  exited                  clawker                example                clawker-clawker:latest  9 hours ago\n$ docker ps -a \nCONTAINER ID   IMAGE                    COMMAND                  CREATED         STATUS                    PORTS     NAMES\n6c6896073eb1   alpine:latest            \"/bin/sh\"                7 seconds ago   Created                             great_dubinsky\n73b4ac14c2b3   clawker-clawker:latest   \"/usr/local/bin/clawk…\"   10 hours ago    Exited (0) 10 hours ago             clawker.clawker.example\n```\n\n## Creating and Using Containers\n\n```bash\n# Create a fresh container and connect interactively\n# The @ symbol auto-resolves your project image (clawker-\u003cproject\u003e:latest)\nclawker run -it --agent main @\n\n# Detach without stopping: Ctrl+P, Ctrl+Q\n\n# Re-attach to the agent\nclawker attach --agent main\n\n# Stop the agent (Ctrl+C exits Claude Code and stops the container)\n# Or from another terminal:\nclawker stop --agent main\n\n# Start a stopped agent and attach\nclawker start -a -i --agent main\n```\n\n## The `@` Image Shortcut\n\nUse `@` anywhere an image argument is expected to auto-resolve your project's image:\n\n```bash\nclawker run -it @                     # Uses clawker-\u003cproject\u003e:latest\nclawker run -it --agent dev @         # Same, with agent name\nclawker container create --agent test @\n```\n\n## Working with Worktrees\n\nRun separate agents per git worktree for parallel development:\n\n```bash\n# Use the --worktree flag for automatic worktree creation and mounting in containers\nclawker run --worktree feature/todo-apps-are-dope:main -it --agent todo-apps @ --dangerously-skip-permissions\n\n# Create worktrees manually\nclawker worktree add feature/todo-apps-are-dope\nclawker worktree add feat-feet --base main\n\n# list your worktrees\nclawker worktree list\n```\n\n## Managing Resources\n\nAs 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\n\n```bash\nclawker ps                          # List all clawker containers\nclawker container ls                # Same thing\nclawker container stop --agent NAME\nclawker image ls                    # List clawker images\nclawker volume ls                   # List clawker volumes\n\n# Firewall management\nclawker firewall status             # Health, rule count, running containers\nclawker firewall list               # List active egress rules\nclawker firewall add docs.clawker.dev # Allow a domain\nclawker firewall remove docs.clawker.dev\nclawker firewall disable --agent dev   # Unrestricted egress for one agent\nclawker firewall enable --agent dev    # Re-apply firewall rules\nclawker firewall bypass 5m --agent dev      # Temporary unrestricted egress with auto-re-enable\nclawker firewall bypass --stop --agent dev  # End bypass early, re-enable firewall\n\n# Control plane (break-glass — normally bootstrapped automatically)\nclawker controlplane status             # Show CP health + firewall subsystem state\nclawker controlplane up                 # Bring CP up (idempotent)\nclawker controlplane down               # Stop CP cleanly (drains eBPF + Envoy/CoreDNS)\nclawker controlplane agents             # List agents registered with the CP\n\n# Auth material\nclawker auth rotate                     # Rotate CA, server certs, and OAuth2 signing key\n\n# Configuration editing\nclawker project edit                    # Interactive TUI editor for .clawker.yaml\nclawker settings edit                   # Interactive TUI editor for settings.yaml\n\n# Skill plugin management\nclawker skill install                   # Install the clawker-support Claude Code plugin\nclawker skill install --scope project   # Install with project scope\nclawker skill show                      # Show manual install commands\nclawker skill remove                    # Remove the clawker-support plugin\n```\n\n## Monitoring \n\nAll containers have the environment variables to push logs and metrics to an OpenTelemetry collector by default. The optional monitoring stack runs four Docker Compose services on `clawker-net`: the **OTEL Collector** (receivers + routing), **OpenSearch** (logs), **OpenSearch Dashboards** (UI over OpenSearch), and **Prometheus** (metrics + UI). Claude Code agents push OTLP/HTTP to the collector, which writes logs to OpenSearch and exposes a Prometheus scrape endpoint. See [`docs/monitoring.mdx`](docs/monitoring.mdx) for the full pipeline reference.\n\n```bash\nclawker monitor init\nclawker monitor up\nclawker monitor status \n# stop it later on \nclawker monitor down\n```\n\nOnce the stack is up:\n\n- **OpenSearch Dashboards** — http://localhost:5601 — Discover view for log exploration\n- **Prometheus UI** — http://localhost:9090 — metrics + ad-hoc PromQL\n- **OpenSearch API** — http://localhost:9200 — REST access to the `claude-code` (Claude Code logs), `clawker-cli` (host CLI logs), `clawker-cp` (control-plane logs), `clawker-envoy` (firewall egress access logs), and `clawker-coredns` (firewall DNS query logs) indices\n\n\u003e **Preconfigured out-of-box.** Every `monitor up` runs a one-shot `clawker-opensearch-bootstrap` container that applies index templates (with explicit field mappings per source), ingest pipelines, a default 7-day ISM retention policy, a `clawker_prometheus` direct-query datasource, and a **`Clawker` analytics workspace** with index patterns + example visualizations imported. `otel-collector` and `prometheus` don't start until bootstrap exits cleanly.\n\u003e\n\u003e **Get into the workspace:** from the OSD splash / welcome screen click **Clawker** under the **Analytics** panel on the far right. **See logs or metrics:** in the workspace UI's left navbar, under **Explore**, click **Logs** or **Metrics**.\n\u003e\n\u003e Robust pre-made dashboards are planned. For now, build your own from the index patterns and the Prometheus datasource — an example dashboard + KPI visualizations ship under the workspace's **Dashboards** view for inspiration or direct use.\n\n## Roadmap / Known Issues\n\n- Currently, clawker containers use stdout/stderr as a poor man's event transport for monitoring. A proper control plane with container agent daemon for managing container lifecycles, configs, and events via gRPC is on the roadmap. This will keep container stdout/err sacred and allow for more robust features, better monitoring, peering communications, and a more seamless experience overall\n- **Firewall: one domain per TCP/SSH port.** Raw TCP/SSH has no domain metadata (unlike TLS and HTTP where Envoy does full HTTP inspection), so for a given TCP/SSH port eBPF can only route all traffic to the single whitelisted destination configured for that port. Two SSH hosts on port 22 isn't supported yet — first rule wins. Deferred for after the control plane work ([#235](https://github.com/schmitthub/clawker/issues/235))\n- Linux might have a bug involving accessing the keychain for creds, I haven't focused on linux extensively yet\n- 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 \n\nSee [GitHub Issues](https://github.com/schmitthub/clawker/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue) for current known issues and limitations.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and PR process.\n\nPlease read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n\u003e 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 and this has no relation to openclaw.  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmitthub%2Fclawker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fschmitthub%2Fclawker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fschmitthub%2Fclawker/lists"}