Clawker — Self-Hosted AI Coding Agent Sandbox

Clawker forwards your host git credentials into containers so agents can push to Git and sign commits without manual key copying. All git credential forwarding is enabled by default. Harness authentication (Claude Code, Codex, etc.) works differently: host credentials are never copied into containers. You authenticate once inside the container, and the token persists in the harness’s config volume. See Harness Authentication below.

Overview

Credential	Method	Default	Config Key
SSH agent	Socket bridge (muxrpc)	On	`security.git_credentials.forward_ssh`
GPG agent	Socket bridge (muxrpc)	On	`security.git_credentials.forward_gpg`
Git HTTPS	Host proxy (HTTP)	On	`security.git_credentials.forward_https`
`.gitconfig`	Bind mount (read-only)	On	`security.git_credentials.copy_git_config`
Harness auth	In-container login, persisted in the config volume	—	`harnesses.<name>.config.strategy` (managed config only, never credentials)

Before a container starts, clawker checks each enabled lane against the host: GPG key material and the gpg-agent socket, a reachable SSH agent, a git credential helper, and the .gitconfig file. A lane the host cannot serve prints one warning on stderr; the container still starts, and that lane fails when it is used. Lanes you disable in config are not checked.

SSH Agent Forwarding

SSH agent forwarding lets the agent use your host SSH keys for Git operations, without exposing the private keys inside the container.

SSH agent forwarding handles the authentication side (your keys). But the firewall must also allow SSH traffic to your Git host. By default, no SSH destinations are allowed. You need an explicit rule:

security:
  firewall:
    rules:
      - dst: github.com
        proto: ssh
        port: 22
        action: allow

The clawker project init template includes this rule for GitHub. See the Firewall guide for more examples.

How it works:

When a container starts, Clawker spawns a socket bridge daemon on the host
The daemon uses docker exec to establish a muxrpc connection with a socket server inside the container
The container-side server creates a Unix socket at ~/.ssh/agent.sock
SSH_AUTH_SOCK is set automatically inside the container
Git SSH operations (git clone [email protected]:...) use the forwarded agent transparently

Disable:

security:
  git_credentials:
    forward_ssh: false

GPG Agent Forwarding

GPG forwarding lets the agent sign commits with your host GPG key. How it works:

The same socket bridge daemon handles GPG forwarding alongside SSH
A socket is created at ~/.gnupg/S.gpg-agent inside the container
Your GPG public key is exchanged via the muxrpc protocol
The container’s gpg.conf is configured with no-autostart to prevent a local GPG agent from conflicting

Disable:

security:
  git_credentials:
    forward_gpg: false

Git HTTPS Credential Forwarding

HTTPS credential forwarding lets the agent authenticate with Git remotes over HTTPS using your host’s credential store (e.g., macOS Keychain, Windows Credential Manager). How it works:

The host proxy daemon runs on your machine (default port 18374)
Inside the container, a git-credential-clawker helper is configured
When Git needs HTTPS credentials, the helper sends a request to the host proxy
The host proxy queries your host’s native git credential fill command
Credentials are returned to the container without being stored there

Requirements:

The host proxy must be running (security.enable_host_proxy: true)
forward_https defaults to follow the enable_host_proxy setting

Disable:

security:
  git_credentials:
    forward_https: false

Setting forward_https: true has no effect if enable_host_proxy is false. HTTPS credential forwarding requires the host proxy.

Git Config Copying

By default, Clawker copies your host ~/.gitconfig into the container so Git operations use your name, email, aliases, and other settings. Important: The credential.helper lines are filtered out during copying. This forces the container to use Clawker’s forwarded credential helpers instead of trying to access a host-side credential store that doesn’t exist inside the container. Disable:

security:
  git_credentials:
    copy_git_config: false

Harness Authentication

Host harness credentials — OAuth tokens, API keys stored in keyrings, credential files — are never copied into containers. Each container authenticates on its own:

On first run, the harness prompts for login (e.g. /login in Claude Code, codex login for Codex)
Browser-based OAuth flows are proxied to your host browser automatically — the container’s BROWSER handler forwards the auth URL through the host proxy, and the OAuth callback is forwarded back into the container
The resulting token is written to the harness’s config directory (e.g. ~/.claude, ~/.codex), which is backed by a named Docker volume scoped to the harness that declared it (clawker.<project>.<agent>-<harness>.<name>, e.g. clawker.myapp.dev-claude.config)
The token persists across container restarts and recreates — any container reusing the same project + agent name with the same harness reuses the volume and stays authenticated. Switching harnesses gets its own volume, so each harness logs in once

The login flow needs network access to the harness vendor’s auth endpoints; the selected harness bundle’s built-in egress floor already allows them, so no firewall configuration is needed for login.

Browser proxying requires the host proxy (security.enable_host_proxy: true, the default). Without it, the harness still prints the auth URL — open it in your host browser manually.

API Keys Instead of OAuth

For headless or CI-style workflows, forward an API key into the container through the environment plumbing instead of logging in interactively. agent.from_env/agent.env apply to every harness; the harnesses.<name> overlay applies only when that harness is selected:

agent:
  from_env:
    - GITHUB_TOKEN          # forwarded for every harness

harnesses:
  claude:
    from_env:
      - ANTHROPIC_API_KEY   # forwarded only when running the claude harness
  codex:
    from_env:
      - OPENAI_API_KEY      # forwarded only when running the codex harness

Per-harness env, env_file, and from_env layer on top of the agent base; on a key collision the harness value wins.

Config Strategy

The harnesses.<name>.config.strategy setting controls how the harness’s configuration is initialized when a container’s config volume is first created:

copy (default) — Stages your host’s managed harness configuration into the fresh volume. For the claude harness this means settings (an allowlisted subset), CLAUDE.md, agents, skills, commands, and plugins (with host paths rewritten to container paths). Credentials are never part of this staging.
fresh — Starts with a clean harness configuration; nothing is staged from the host.

harnesses:
  claude:
    config:
      strategy: "fresh"

Staging happens only into volumes created by that clawker run/create — a pre-existing config volume carries your in-container state and is never re-seeded.

Full Configuration Example

security:
  enable_host_proxy: true
  git_credentials:
    forward_https: true
    forward_ssh: true
    forward_gpg: true
    copy_git_config: true

harnesses:
  claude:
    config:
      strategy: "copy"
    from_env:
      - ANTHROPIC_API_KEY

Troubleshooting

SSH: “Permission denied (publickey)”

Verify your SSH agent is running on the host: ssh-add -l
Check that forward_ssh is enabled
Try restarting the container — the socket bridge daemon reconnects automatically

GPG: “No secret key” when signing commits

Verify your GPG key is available on the host: gpg --list-secret-keys
Check that forward_gpg is enabled
The container’s GPG agent might have auto-started before the forwarded socket was ready. Restart the container to fix.

Git HTTPS: “Authentication failed”

Verify the host proxy is running: check for the process or look at ~/.local/state/clawker/pids/hostproxy.pid
Verify credentials work on the host: git credential fill with your repo URL
Check that enable_host_proxy and forward_https are both enabled

A login prompt on a container’s first run is expected — containers never inherit host credentials. Authenticate once; the token persists in the config volume. If a previously authenticated container prompts again:

Check the config volume still exists (clawker volume list) — removing it (or clawker volume prune) removes the stored token
config.strategy: fresh doesn’t affect credentials, but recreating the agent under a new agent name creates a new (empty) config volume — a new login is expected

If the browser flow doesn’t open on your host during login (claude harness example): verify the host proxy is enabled and running, or copy the printed URL into your host browser manually.

Get started

Configuration

Running Agents

Security

Building images

Bundles & extensions

Operations

Under the hood

Developer guide

CLI Reference

Credential Forwarding

Overview

SSH Agent Forwarding

GPG Agent Forwarding

Git HTTPS Credential Forwarding

Git Config Copying

Harness Authentication

API Keys Instead of OAuth

Config Strategy

Full Configuration Example

Troubleshooting

SSH: “Permission denied (publickey)”

GPG: “No secret key” when signing commits

Git HTTPS: “Authentication failed”

​Overview

​SSH Agent Forwarding

​GPG Agent Forwarding

​Git HTTPS Credential Forwarding

​Git Config Copying

​Harness Authentication

​API Keys Instead of OAuth

​Config Strategy

​Full Configuration Example

​Troubleshooting

​SSH: “Permission denied (publickey)”

​GPG: “No secret key” when signing commits

​Git HTTPS: “Authentication failed”

​Harness prompts for login

Overview

SSH Agent Forwarding

GPG Agent Forwarding

Git HTTPS Credential Forwarding

Git Config Copying

Harness Authentication

API Keys Instead of OAuth

Config Strategy

Full Configuration Example

Troubleshooting

SSH: “Permission denied (publickey)”

GPG: “No secret key” when signing commits

Git HTTPS: “Authentication failed”

Harness prompts for login