agent-runner-auth
agent-runner-auth is a single Go binary that links Claude Code’s
apiKeyHelper mechanism to the platform’s Cognito OAuth stack. It runs
as a short-lived CLI on the developer’s machine — no daemon, no
background process.
The token verb
Claude Code calls agent-runner-auth token before each session. This
one verb covers four cases:
| Case | Condition | Behavior | Wall-clock |
|---|---|---|---|
| Token cached | Valid access token in keychain | Print token to stdout, exit 0 | ~50ms |
| Silent refresh | Access token expired, refresh token valid | Refresh grant → write tokens → print | ~300ms |
| PKCE inline | No valid tokens, interactive (TTY + display) | Loopback listener → browser → exchange → print | ~15–30s |
| Non-interactive | No valid tokens, no TTY or $CI set | Error to stderr, exit 1 | ~50ms |
Token output goes to stdout only; all status and progress go to
stderr. This keeps apiKeyHelper parsing clean.
Concurrency
Multiple Claude Code processes may call token at once on first use. The
binary acquires a flock on ~/.config/agent-runner/lock before any
keychain read/write. A second caller blocks until the first completes,
then reads the fresh token without repeating the browser flow.
Config
~/.config/agent-runner/config.json, written once at login time (or by
the marketplace install wizard) — never written by token:
{
"tenant_url": "https://acme.proxy.<domain>",
"auth_domain": "auth.<domain>",
"client_id": "...",
"scope": "openid profile email proxy:invoke"
}Keychain storage per OS
| OS | Storage |
|---|---|
| macOS | Keychain (Security framework) |
| Linux | libsecret (GNOME) with pass fallback |
| Windows | Windows Credential Manager (DPAPI) |
Stored under key names agent-runner-access-token and
agent-runner-refresh-token.
Distribution
| Platform | Install |
|---|---|
| macOS | brew install copebit/tap/agent-runner-auth |
| Linux (Debian/Ubuntu) | apt repo deb https://apt.agent-runner.io stable main |
| Linux (other) | Direct binary download |
| Windows | winget install copebit.AgentRunnerAuth |