Architecture

System Overview

Clawker is a CLI tool plus two long-lived daemons — clawkercp (the control plane, one per host) and clawkerd (one per agent container) — that together manage isolated Docker containers for AI coding agents. The CLI is the root of trust; the daemons hold the security boundary at runtime.

┌────────────────────────────────────────────────────────────────────────────┐
│  CLI Layer                                                                  │
│  cmd/clawker → internal/clawker → internal/cmd/root                         │
│  17 command groups, 80+ subcommands (Cobra, Factory DI)                    │
└──────┬──────────────────────────┬──────────────────────┬────────────────────┘
       │                          │                      │
       ▼                          ▼                      ▼
┌──────────────┐    ┌─────────────────────┐    ┌────────────────────────────┐
│ Container    │    │ Configuration       │    │ Control Plane              │
│ Subsystem    │    │ Subsystem           │    │ (cmd/clawkercp, PID 1     │
│              │    │                     │    │  of clawker-controlplane)  │
│ docker/      │    │ storage/ (engine)   │    │                            │
│ workspace/   │    │ config/ (project)   │    │ AdminService gRPC (mTLS    │
│ containerfs/ │    │ config/ (settings) │    │  + OAuth2): 13 firewall    │
│ bundler/     │    │ project/ (registry) │    │  RPCs + ListAgents         │
│              │    │ storeui/ (TUI edit) │    │ AgentService gRPC (mTLS):  │
│ pkg/whail    │    │                     │    │  clawkerd Register +       │
│ (engine lib) │    │                     │    │  Session command channel   │
└──────┬───────┘    └─────────────────────┘    │ Ory auth stack (Hydra,     │
       │                                       │  Kratos, Oathkeeper)       │
       ▼                                       │ Agent sqlite registry      │
  moby/moby (Docker SDK)                       │ Pub/sub event bus          │
                                               │ Owns: firewall (Envoy +    │
                                               │  CoreDNS) + eBPF cgroup    │
                                               │  programs + dns_cache map  │
                                               │ netlogger (drains          │
                                               │  events_ringbuf → emits    │
                                               │  ebpf-egress OTLP logs)    │
                                               └──────────┬─────────────────┘
                                                          │ mTLS Session
                                                          ▼
                                               ┌────────────────────────────┐
                                               │ clawkerd                   │
                                               │ (PID 1 of every agent      │
                                               │  container; ENTRYPOINT)    │
                                               │                            │
                                               │ Inbound mTLS gRPC :7700    │
                                               │ Forks user CMD with kernel-│
                                               │  side privilege drop       │
                                               │ Two-phase orphan reaper    │
                                               │ Signal forwarding to child │
                                               │  pgroup                    │
                                               └────────────────────────────┘

The control plane is not the firewall — it is the supervisor that, among other things, owns the firewall lifecycle. See Control Plane for the user-facing CP guide and Firewall for the firewall guide.

CLI Command Structure

Commands are organized under internal/cmd/ with subpackages per subcommand:

Command Group	Subcommands	Purpose
`container`	list, run, start, stop, kill, exec, attach, logs, inspect, cp, pause, unpause, restart, rename, remove, stats, top, update, wait, create	Docker container management
`image`	list, build, inspect, remove, prune	Image lifecycle
`volume`	list, create, inspect, remove, prune	Volume management
`network`	list, create, inspect, remove, prune	Network management
`project`	init, register, list, info, edit, remove	Project registration and config
`worktree`	add, list, prune, remove	Git worktree management
`firewall`	status, list, add, remove, reload, refresh, prune, up, down, enable, disable, bypass, rotate-ca	Egress firewall control (all RPCs route through `f.AdminClient` to the CP daemon)
`controlplane`	up, down, status, agents	Break-glass control plane lifecycle + registered agent listing
`auth`	rotate	CLI-side auth material (CA, server certs, OAuth2 signing key)
`monitor`	init, up, reload, down, status, extensions	Observability stack (OTel Collector, OpenSearch, OpenSearch Dashboards, Prometheus)
`settings`	edit	User settings TUI editor
`plugin` (alias `skill`)	install, show, remove	Manage the clawker-support agent skills plugin
`alias`	set, list, delete, export	Manage command aliases
`bundle`	install, list, update, validate, remove, prune	Manage distributed bundles of harnesses, stacks, and monitoring extensions
`harness`	list	Inspect resolvable harnesses
`stack`	list	Inspect resolvable stacks
`prompt`	print	Access clawker’s managed agent briefing

Top-level shortcuts: init → project init, build → image build, run/start → container run/start, version Shared domain logic (container creation) lives in shared/ subpackages within each command group — not in library packages.

Package Dependency Graph

Packages follow a strict DAG with no cycles. Verified via goda.

Leaf Packages (zero internal imports)

Importable by anyone. Depend only on stdlib or external libraries.

Package	Purpose
`storage`	Generic layered YAML store engine (`Store[T]`): discovery, merge, provenance, atomic write
`git`	Git operations, worktree management (go-git)
`logger`	Struct-based zerolog (file rotation + optional OTEL bridge)
`text`	Pure ANSI-aware text utilities (Truncate, PadRight, StripANSI)
`term`	Terminal capabilities + raw mode (sole `x/term` gateway)
`signals`	OS signal utilities (SetupSignalContext, ResizeHandler)
`build`	Build-time metadata (version, date via ldflags)
`update`	Background GitHub release checker (24h cached)
`keyring`	Credential storage service
`pkg/whail`	Reusable Docker engine library with label-based isolation

Foundation Packages (import leaves only)

Universally imported infrastructure. Their imports are leaf-only.

Package	Imports	Purpose
`config`	storage	Config loading/validation, schema types, path resolution. Composes `Store[Project]` + `Store[Settings]`
`iostreams`	term, text	I/O streams, TTY detection, colors, styles, spinners, progress

Domain Packages (import leaves + foundation)

Core business logic. Import leaves and foundation packages only.

Package	Imports	Purpose
`project`	config, git, logger, storage, text	Project registration, worktree lifecycle, registry CRUD
`bundler`	config + own subpkgs	Dockerfile generation, content hashing, semver, npm registry
`tui`	iostreams, text	BubbleTea models, viewports, panels, progress display
`prompter`	iostreams	Interactive prompts with TTY/CI awareness
`storeui`	iostreams, storage, tui	Generic TUI editor for `Store[T]` instances
`controlplane`	config, docker, logger, ory subprocess managers	CP daemon core: AdminService composition, Ory auth stack, startup orchestrator, agent watcher
`controlplane/agent`	auth, consts, dockerevents, pubsub, logger	CP-side agent surface: Dialer, sqlite Registry, Register handler, IdentityInterceptor, session/agent events
`controlplane/pubsub`	logger	Generic typed pub/sub engine (`Topic[T]`/`Event[T]`); each domain (e.g. `controlplane/agent`) projects its own worldview from subscribed events — there is no shared central state store
`controlplane/dockerevents`	pubsub, logger	Docker events feeder (reconnecting stream → typed events on a pub/sub topic)
`controlplane/manager`	config, docker, logger (+ embedded clawkercp + ebpf-manager + bpffs-delegate binaries)	Host-side CP lifecycle: `Manager.Start`/`Stop`/`CPRunning`
`controlplane/adminclient`	auth, consts	CLI-side AdminService gRPC dial (mTLS + auto-refreshing OAuth2 bearer)
`controlplane/firewall`	config, docker, logger, storage, controlplane/firewall/ebpf	Firewall `Handler` (13 RPCs), `Stack` (Envoy+CoreDNS lifecycle), `ActionQueue`, config generators, certificate PKI, rules store
`controlplane/firewall/ebpf`	logger	eBPF program loader/manager, `SyncRoutes` replaces global `route_map` atomically; break-glass `ebpf-manager` CLI under `cmd/`
`controlplane/firewall/ebpf/netlogger`	controlplane/firewall/ebpf, controlplane/pubsub, controlplane/dockerevents, controlplane/otel, config, logger	Per-decision-point egress event emitter — drains the BPF `events_ringbuf`, enriches by cgroup ID with container/agent/project attribution via the eBPF-enrolled pub/sub topic, emits OTLP log records via a `*sdklog.LoggerProvider` (`service.name=ebpf-egress`)
`dnsbpf`	controlplane/firewall/ebpf	CoreDNS plugin that writes DNS resolutions to the BPF `dns_cache` map in real time (embedded in `cmd/coredns-clawker`)
`clawkerd/embed`	(embed only)	embeds the compiled per-container daemon binary; bundler drops it into every per-project image at `/usr/local/bin/clawkerd`
`hostproxy`	config, logger	Host proxy for container-to-host communication
`socketbridge`	config, logger	SSH/GPG agent forwarding via muxrpc
`containerfs`	config, keyring, logger	Host config preparation for container init
`monitor`	config	Observability stack templates (OTel Collector, OpenSearch, OpenSearch Dashboards, Prometheus)
`docs`	config, storage	CLI documentation generation

Composite Packages (import domain packages)

Higher-level subsystems that compose domain packages.

Package	Key Imports	Purpose
`docker`	bundler, config, pkg/whail, pkg/whail/buildkit	Clawker middleware wrapping whail with labels/naming
`workspace`	config, docker, logger	Bind vs Snapshot strategies
`cmdutil`	config, docker, iostreams, tui, + type imports for Factory	Factory struct (DI container), error types, arg validators

Import Rules

  OK:  foundation → leaf           (config → storage)
  OK:  domain → leaf               (firewall → storage)
  OK:  domain → foundation         (project → config)
  OK:  composite → domain          (docker → bundler)

  BAD: leaf → anything internal    (storage must never import config)
  BAD: foundation ↔ foundation     (config must never import iostreams)
  BAD: any cycle                   (A → B → A is always wrong)

Configuration and Storage

Three packages form the configuration subsystem:

storage (leaf) — Generic Store[T] engine. Handles file discovery (static paths + walk-up), YAML loading with migrations, N-way merge with provenance tracking, and atomic writes. Zero domain knowledge.
config — Thin domain wrapper composing Store[Project] + Store[Settings]. Exposes the Config interface with schema types, path helpers, and ~40 accessor methods.
project — Project domain layer. Owns the registry.yaml project registry via its own Store[ProjectRegistry]. Handles registration CRUD, path resolution, worktree lifecycle.

Commands access config through the Config interface and ProjectManager interface — never storage directly.

Dependency Injection: The Factory Pattern

Follows the GitHub CLI’s three-layer pattern:

Wiring (internal/cmd/factory/) — Creates *cmdutil.Factory with all deps as sync.Once closures. Called once at entry point. Tests never import this.
Contract (internal/cmdutil/) — Factory is a pure struct with closure fields. Eager: Version, IOStreams, TUI. Lazy: Config, Client, ProjectManager, GitManager, HostProxy, SocketBridge, AdminClient, ControlPlane, HttpClient, Logger, Prompter.
Consumers (internal/cmd/*/) — Cherry-pick Factory closures into per-command Options structs. Run functions accept *Options only.

func NewCmdStop(f *cmdutil.Factory, runF func(*StopOptions) error) *cobra.Command {
    opts := &StopOptions{
        IOStreams: f.IOStreams,
        Client:   f.Client,  // closure, not call
    }
}

func stopRun(ctx context.Context, opts *StopOptions) error {
    client, err := opts.Client(ctx)  // resolved lazily here
}

Key Abstractions

Abstraction	Package	Purpose
`storage.Store[T]`	`internal/storage`	Generic layered YAML store with merge, provenance, and atomic write
`config.Config`	`internal/config`	Typed config interface composing `Store[Project]` + `Store[Settings]`
`project.ProjectManager`	`internal/project`	Project identity, registration CRUD, worktree orchestration
`whail.Engine`	`pkg/whail`	Reusable Docker engine with label-based resource isolation
`docker.Client`	`internal/docker`	Clawker middleware (labels, naming) wrapping whail
`cmdutil.Factory`	`internal/cmdutil`	DI struct (closure fields); constructor in `cmd/factory`
`CreateContainer()`	`internal/cmd/container/shared`	Single entry point for container creation
`adminclient.Dial`	`controlplane/adminclient`	CLI-side AdminService gRPC dial (mTLS + OAuth2)
`firewall.Handler`	`controlplane/firewall`	13-method AdminService firewall surface inside the CP daemon
`firewall.Stack`	`controlplane/firewall`	Envoy + CoreDNS container lifecycle
`dnsbpf.Handler`	`internal/dnsbpf`	CoreDNS plugin populating the BPF `dns_cache` map in real time
`ebpf.Manager`	`controlplane/firewall/ebpf`	BPF program loader; `SyncRoutes` replaces the global `route_map` atomically
`netlogger.Service`	`controlplane/firewall/ebpf/netlogger`	Drains BPF `events_ringbuf`, enriches by `cgroup_id`, emits OTLP log records (`service.name=ebpf-egress`) on the trusted infra lane
`otel.NewOtelLoggerProvider`	`controlplane/otel`	Generic `*sdklog.LoggerProvider` factory (mTLS + infra cert, BatchProcessor, optional ExporterWrap) reused by netlogger and any future CP-side OTLP log emitter
`manager.Manager`	`controlplane/manager`	Host-side CP container lifecycle (`Manager.Start`/`Stop`/`CPRunning`)
`agent.Registry`	`controlplane/agent`	sqlite-backed agent identity (CP is sole writer)
`pubsub.Topic[T]`	`controlplane/pubsub`	Generic typed pub/sub engine; each domain (e.g. `controlplane/agent`) projects its own worldview from subscribed events
`cmd/clawkercp`	`cmd/clawkercp`	CP daemon entry point — PID 1 of the `clawker-controlplane` container
`cmd/clawkerd`	`cmd/clawkerd`	Entrypoint for the per-container agent daemon — PID 1 of every agent container
`cmd/coredns-clawker`	`cmd/coredns-clawker`	Custom CoreDNS entrypoint embedding `dnsbpf`; built into `clawker-coredns:latest` on demand
`tui.TUI`	`internal/tui`	Factory noun for presentation layer

Container Naming and Labels

Container names: clawker.project.agent (3-segment) or clawker.agent (2-segment when project is empty) Volume names: clawker.project.agent-purpose (reserved purposes: workspace, history, clawker lifecycle volume; plus the volumes the harness bundle declares, e.g. config) Labels (all under dev.clawker.*):

Label	Purpose
`managed`	`true` — authoritative ownership marker
`project`	Project name (omitted when empty)
`agent`	Agent name
`version`	Clawker version
`image`	Source image reference

Labels are authoritative for resource ownership. Names are for human readability. Clawker refuses to operate on resources without dev.clawker.managed=true.

Presentation Layer

Commands follow a 4-scenario output model:

Scenario	Description	Packages
Static	Print and done	`iostreams` + `fmt`
Static-interactive	Output with y/n prompts	`iostreams` + `prompter`
Live-display	Continuous rendering, no input	`iostreams` + `tui`
Live-interactive	Full keyboard input, navigation	`iostreams` + `tui`

Import boundaries (enforced):

Only iostreams imports lipgloss
Only tui imports bubbletea/bubbles
Only term imports golang.org/x/term

Get started

Configuration

Running Agents

Security

Building images

Bundles & extensions

Operations

Under the hood

Developer guide

CLI Reference

Architecture

Architecture

System Overview

CLI Command Structure

Package Dependency Graph

Leaf Packages (zero internal imports)

Foundation Packages (import leaves only)

Domain Packages (import leaves + foundation)

Composite Packages (import domain packages)

Import Rules

Configuration and Storage

Dependency Injection: The Factory Pattern

Key Abstractions

Container Naming and Labels

Presentation Layer

​Architecture

​System Overview

​CLI Command Structure

​Package Dependency Graph

​Leaf Packages (zero internal imports)

​Foundation Packages (import leaves only)

​Domain Packages (import leaves + foundation)

​Composite Packages (import domain packages)

​Import Rules

​Configuration and Storage

​Dependency Injection: The Factory Pattern

​Key Abstractions

​Container Naming and Labels

​Presentation Layer

Architecture

System Overview

CLI Command Structure

Package Dependency Graph

Leaf Packages (zero internal imports)

Foundation Packages (import leaves only)

Domain Packages (import leaves + foundation)

Composite Packages (import domain packages)

Import Rules

Configuration and Storage

Dependency Injection: The Factory Pattern

Key Abstractions

Container Naming and Labels

Presentation Layer