Skip to main content

​
Design Philosophy

​
The Padded Cell

Clawker creates a “padded cell” for AI coding agents. Clawker uses Docker-like commands to build, bootstrap, and orchestrate infrastructure and isolated devcontainers that protect everything outside the container from what happens inside.

​
What We Protect

  • Host filesystem — from container writes (bind mounts controlled)
  • Host network — via firewall (outbound controlled, inbound open)
  • Other Docker resources — via label-based isolation
  • The container itself — is disposable; a new one can always be created
We do not inherit Docker’s full threat model. If Docker allows a command, Clawker permits it — but only against Clawker-managed resources.

​
Core Concepts

​
Project

A project is defined by .clawker.yaml and registered in the project registry (registry.yaml in the data dir, e.g. ~/.local/share/clawker/registry.yaml). Every Clawker command requires project context, resolved via longest-prefix path matching against the registry. Configuration precedence (highest to lowest):
  1. CLI flags
  2. Project config (./.clawker.yaml)
  3. User settings (~/.config/clawker/settings.yaml)

​
Agent

An agent is a named container instance. One project can have multiple agents, each running in its own isolated container. Naming convention: clawker.<project>.<agent> (e.g., clawker.myapp.dev)

​
Resource Identification

Strict ownership: Clawker refuses to operate on resources without dev.clawker.managed=true, even if they have the clawker. name prefix.

​
Security Model

​
Defaults

​
Credential Handling

API keys pass via environment variables; subscription auth (OAuth callback interception) and Git HTTPS credentials are brokered through the host proxy, and SSH keys are forwarded via the agent socket rather than copied. See Credential Forwarding.

​
Firewall

Deny-by-default egress: eBPF cgroup programs (attached from outside each agent container by the control plane) redirect outbound TCP to an Envoy proxy, while agent containers point their resolver at a custom CoreDNS that returns NXDOMAIN for anything unlisted. Allowed domains compose the selected harness’s minimal egress floor with your per-project security.firewall rules. See the Firewall guide for the full design.

​
Control Plane

The clawker-controlplane container (cmd/clawkercp, its PID 1) is the authoritative host-level supervisor — it owns the firewall lifecycle, eBPF program lifetime, the agent registry, and the mTLS Session over which it dispatches commands to clawkerd. CP is not the firewall; it is the daemon that, among other things, manages it. See Control Plane for the full design.

​
Egress Observability

Every firewall decision — allowed, denied, or bypassed — emits a structured OTLP record (container attribution + destination 4-tuple + resolved domain) into the clawker-ebpf-egress OpenSearch index on the trusted infra lane, so bypass windows are not a forensic blind spot. See Egress Observability for the record shape.

​
Key Design Decisions

  1. All Docker SDK calls go through pkg/whail — never bypass this isolation layer
  2. Labels are authoritative — dev.clawker.managed=true determines ownership, not names
  3. stdout for data and status, stderr for warnings/errors — enables scripting and composability
  4. Factory DI pattern — pure struct in cmdutil, constructor in internal/cmd/factory, Options in commands
  5. Docker holds runtime state — container status, labels, and volumes are the source of truth for what’s running; local YAML files (project clawker.yaml, user settings.yaml, the project registry registry.yaml) hold configuration, not runtime state
  6. config.Config is a gateway — lazy accessor for Project, Settings, Resolution
  7. zerolog is file-only — user-visible output uses fmt.Fprintf to IOStreams

​
State Management

Container runtime state lives in Docker:
  • Container state (running, stopped)
  • Labels (project, agent, metadata)
  • Volumes (workspace, config, history)
Configuration and project registration persist in small local YAML files (project clawker.yaml, user settings.yaml, the project registry registry.yaml). Writes to these files are serialized with advisory file locks, so multiple Clawker instances can operate concurrently with no synchronization issues.

​
Command Taxonomy

Commands mirror Docker’s CLI structure: Top-level shortcuts: init, build, run, start, monitor *, version Management commands: alias, auth, bundle, harness, stack, container, volume, network, image, project, worktree, firewall, controlplane, settings, plugin (alias skill)

​
Multi-Agent Operations

  • One project has many agents
  • Many agents can share one image

​
Error Handling

Errors return typed values to Main() for centralized rendering:
  • fmt.Errorf(...) — general errors
  • cmdutil.FlagError — triggers usage display
  • cmdutil.SilentError — already displayed, just exit non-zero