Skip to main content
A harness is the coding-agent CLI clawker runs inside a container — Claude Code, OpenAI Codex, or one you supply. A harness definition carries everything clawker needs to build and run that agent: the install steps, the persisted volumes it keeps state in, the host state it stages at container creation, and the egress floor the firewall must allow for the agent to function.

​
Selecting a harness

Images are per-project and per-harness. You choose the harness at build time, and the image tag is the harness name:
The default harness image also gets a :default alias. At run time the @ shortcut resolves against these tags:
The harness name accepts a bare name (a built-in or loose harness) or a qualified namespace.bundle.component address (a bundled harness):

​
Setting the default harness

Out of the box the default is the built-in claude harness. Set the build.harness key to make any harness the default — in your user-level clawker.yaml to apply across every project, or in a project’s clawker.yaml to override it there. The highest layer that sets it wins; an explicit -t or @:<harness> always beats it.
With that set, clawker build builds that harness and stamps its image with the :default alias, so a bare @ runs it. Images and containers carry a harness label recording exactly which harness they were built for — the same spelling you selected.
A container refuses to start if its harness label names a harness that is no longer declared or cached. This is deliberate: a container never starts with a weaker egress floor than it was built for. The error names the label and the remedy.

​
Where harnesses come from

Harness names resolve across the same three tiers as every component. A bare name resolves user convention directory, then project convention directory, then the built-in floor; a qualified name resolves from an installed bundle. See where components come from for the canonical resolution model.

​
Built-in harnesses

Clawker ships claude and codex. They resolve by bare name and update with the clawker binary. Each declares its own egress floor — the claude harness’s floor covers Anthropic domains, codex’s covers OpenAI domains — composed with your project’s security.firewall rules.

​
Loose local harnesses

Drop a harness directory into a convention directory and it exists immediately, bare-named:
A user harness shadows a project one of the same name, which shadows a built-in; shadows are visible in clawker harness list.

​
Bundled harnesses

A harness shipped in a bundle is addressed by its qualified name and becomes available once the bundle is declared and installed. See Bundles.

​
Per-harness project configuration

Container-initialization settings for a harness live under a harnesses.<name> map in clawker.yaml — environment overlays, post_init/pre_run hooks (appended after the harness-agnostic agent.* hooks), and host-state staging. The key is the harness name you build and run. To add build steps to a single harness’s image — extra stacks, packages, or Dockerfile injection — use the per-harness build overlay under build.harnesses.<name>, covered in Image Customization.

​
Authenticating

Host credentials are never copied into a container. You authenticate once inside the container — browser OAuth flows are proxied to your host browser automatically — and the token persists in the harness’s config volume, so restarts and recreates that reuse the volume stay logged in. See Credential Forwarding.

​
Authoring a harness

Writing your own harness — the harness.yaml manifest, its Dockerfile fragment, and its stack dependencies — is covered in Authoring harnesses.