Skip to main content
Clawker forwards your host credentials into containers so agents can push to Git, sign commits, and authenticate with Claude Code without manual key copying. All credential forwarding is enabled by default.

​
Overview

CredentialMethodDefaultConfig Key
SSH agentSocket bridge (muxrpc)Onsecurity.git_credentials.forward_ssh
GPG agentSocket bridge (muxrpc)Onsecurity.git_credentials.forward_gpg
Git HTTPSHost proxy (HTTP)Onsecurity.git_credentials.forward_https
.gitconfigBind mount (read-only)Onsecurity.git_credentials.copy_git_config
Claude Code authVolume injectionOnagent.claude_code.use_host_auth

​
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:
  1. When a container starts, Clawker spawns a socket bridge daemon on the host
  2. The daemon uses docker exec to establish a muxrpc connection with a socket server inside the container
  3. The container-side server creates a Unix socket at ~/.ssh/agent.sock
  4. SSH_AUTH_SOCK is set automatically inside the container
  5. 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:
  1. The same socket bridge daemon handles GPG forwarding alongside SSH
  2. A socket is created at ~/.gnupg/S.gpg-agent inside the container
  3. Your GPG public key is exchanged via the muxrpc protocol
  4. 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:
  1. The host proxy daemon runs on your machine (default port 18374)
  2. Inside the container, a git-credential-clawker helper is configured
  3. When Git needs HTTPS credentials, the helper sends a request to the host proxy
  4. The host proxy queries your host’s native git credential fill command
  5. 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

​
Claude Code Authentication

By default, Clawker forwards your Claude Code authentication into the container so the agent is pre-authenticated on startup. How it works:
  1. During container creation, Clawker looks for credentials in this order:
    • OS keyring (macOS Keychain, etc.)
    • File fallback (~/.claude/.credentials.json)
  2. Credentials are injected into the container’s config volume
  3. Claude Code starts pre-authenticated
Disable: 
agent:
  claude_code:
    use_host_auth: false
When disabled, Claude Code inside the container will prompt for authentication on first run.

​
Config Strategy

The config.strategy setting controls how Claude Code’s configuration is initialized:
  • copy (default) — Copies your host ~/.claude/ settings (plugins, preferences, MCP config) into the container
  • fresh — Starts with a clean Claude Code configuration
agent:
  claude_code:
    config:
      strategy: "fresh"

​
Full Configuration Example

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

agent:
  claude_code:
    config:
      strategy: "copy"
    use_host_auth: true

​
Troubleshooting

​
SSH: “Permission denied (publickey)”

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

​
GPG: “No secret key” when signing commits

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

​
Git HTTPS: “Authentication failed”

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

​
Claude Code: “Please authenticate”

  1. Verify you’re logged in on the host: claude auth status
  2. Check that use_host_auth is true (default)
  3. If using the file fallback, verify ~/.claude/.credentials.json exists