Sign-in only or full setup

A coding CLI has to be signed in before it can do any work. On a runner on your own machine, there are two ways a run gets that sign-in. Sign-in only is the default, and most people never change it.

Sign-in only (the default)

• The runner has its own sign-in. It lives in ~/.commandchain/agent-auth, one folder per coding CLI, separate from your own. The installer creates it, or you do from the runner screen.
• Each run gets a clean home with a copy it can renew. Nothing else from your machine is loaded: no hooks, plugins, MCP servers or settings of your own.
• Parallel runs never sign each other out. The runner renews the sign-in ahead of expiry and keeps every running job on the newest one, so several runs at once, and runs that go on for hours, all stay signed in. That holds even if you sign the runner in again while jobs are running: the jobs already going finish on the sign-in they started with.
• Your own CLI sign-in is never read or changed. Signing the runner in or out does not touch ~/.claude, ~/.codex, ~/.gemini or your own Keychain entry.
• Nothing is uploaded on its own. The runner keeps its sign-in on this machine and uploads it only if you choose to push it for managed runs, with the c key or creds push --from-runner-signin. See managed runner credentials.

Signing in, out and checking

On the runner machine, open the runner with commandchain-runner, then press s for Sign-ins:

• enter signs in with your browser.
• d signs in to Codex with a device code, for a machine with no browser.
• a signs in with an API key instead of a subscription login.
• x signs the runner out. Runs already going finish with the current sign-in.

Prefer commands? They do the same thing:

commandchain-runner signin --agent claude-code     # or codex, gemini
commandchain-runner signin --agent codex --device-auth
commandchain-runner signin --agent claude-code --api-key
commandchain-runner signout --agent claude-code
commandchain-runner creds status

creds status checks only this machine and sends nothing anywhere:

$ commandchain-runner creds status
Agent setup: sign-in only (runs use this runner's own sign-ins)
  Claude Code  signed in for this runner (subscription login)
  Codex        not installed
  Gemini CLI   not installed

API keys in the environment are not used

An ANTHROPIC_API_KEY, OPENAI_API_KEY or similar variable in the runner’s environment does not sign a coding CLI in. To use an API key, press a in Sign-ins, or run commandchain-runner signin --agent claude-code --api-key. The key is stored only in the runner’s own sign-in on this machine.

Full setup

Full setup lets runs use your own CLI folders and your own sign-in instead of the runner’s. Turn it on only on a machine you trust with that.

To turn it on, press f on the runner screen, read the panel Use your full agent setup?, and confirm with y. Press n or esc to keep sign-in only.

• What loads. Runs use your own Claude Code, Codex and Gemini CLI folders (~/.claude, ~/.codex, ~/.gemini): your hooks, plugins, MCP servers, settings, instruction files (CLAUDE.md, AGENTS.md, GEMINI.md) and your own sign-in.
• What runs can reach. Those run inside every agent run, with the same access the agent has. Runs can read and change everything in those folders, including your sign-in and any keys your hooks or MCP servers are configured with, and a copy of ~/.claude.json. On macOS, when your Claude Code sign-in is kept in the Keychain, runs can also reach the Keychain to use it.
• Renewal. Your CLIs renew your sign-in the way they normally do, as if you had several windows open.
• The rest of your home folder stays out of reach, so a hook that calls a script outside those folders will not find it.
• When it takes effect. On the next run. Runs already going keep the setup they started with.
• Where the choice is kept. In ~/.commandchain/agent-setup.json, for this machine and this user. The runner reads it fresh for every run, so no restart is needed.
• Switching back. Press f again and the runner goes straight back to sign-in only. The next run starts clean, with only the runner’s own sign-in.

In full setup, the runner screen and creds status show your own sign-ins rather than the runner’s. Sign in or out of them the way you normally do.

Codex and the system keyring

Runs cannot use a Codex sign-in kept in the system keyring, so with full setup on, Codex reads as not signed in. Add cli_auth_credentials_store = "file" to ~/.codex/config.toml and sign in to Codex again.

Next steps

• The runner screen: every key, and what the screen walks you through.
• The security model: the boundary every run sits inside.
• Managed runner credentials: the separate login used only on CommandChain’s managed servers.