Coding agents and subscriptions

The worker runs coding-agent steps with a coding agent installed on your machine, logged in with your own provider account. This page says which agents the worker supports, how each one is logged in, and how to give an agent more than one login so that work can continue on another subscription.

Supported coding agents

Agent	Name in node.yaml	Command it runs	Provider login
Pi	pi	pi	Run pi, then /login
Claude Code	claude	claude	claude /login
Codex	codex	codex	codex login

An agent runs on this worker only when all of these hold:

• Pidgen allows it for your Account;
• its command is installed and on the PATH of the user the worker runs as (or, for pi and claude, named by cli_path in the worker policy);
• node.yaml gives it a max above 0 (see Coding-agent session caps).

Install each agent with npm, as its own documentation describes, and log it in as the same operating-system user the worker runs as. pidgen-worker doctor reports each agent that is switched on but has no command on this machine; such an agent is not offered to Pidgen until you install it or switch it off with pidgen-worker capacity set <harness> --max 0.

Claude Code can also use an API key or token instead of a login: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in the worker's environment. Use one or the other.

Subscriptions

Each coding agent has, by default, one subscription: the login it has in its usual place, called default. You can list more, for example a second account to fall back on when the first reaches its usage limit. A subscription in node.yaml names where a login is kept, never the credential itself:

harnesses:
  claude:
    max: 4
    primary: claude-primary          # optional; the first listed when left out
    subscriptions:
      - label: claude-primary        # Claude Code's usual login
      - label: claude-fallback
        config_dir: ~/.claude-fallback
  codex:
    max: 2
    subscriptions:
      - label: codex-primary         # Codex's usual login
      - label: codex-fallback
        auth_file: ~/.codex-fallback/auth.json
  pi:
    max: 2
    subscriptions:
      - label: pi-primary            # Pi's usual login
      - label: pi-fallback
        auth_file: ~/.pi-fallback/auth.json

Key	Meaning
harnesses.<harness>.subscriptions	Up to 16 logins, in fallback order. Leave it out for the one default login.
harnesses.<harness>.subscriptions.label	The subscription's name: letters, digits, ., _ and -, up to 64 characters, unique within the agent.
harnesses.claude.subscriptions.config_dir	For Claude Code: the configuration directory holding the login. Left out, Claude Code's usual one.
harnesses.codex.subscriptions.auth_file, harnesses.pi.subscriptions.auth_file	For Codex and Pi: the auth.json holding the login. Left out, the agent's usual one.
harnesses.<harness>.primary	The subscription new work runs on. Left out, the first listed.

A Claude Code subscription takes config_dir and never auth_file; a Codex or Pi subscription takes auth_file and never config_dir. pidgen-worker doctor and pidgen-worker capacity show name the key at fault in a file that breaks these rules.

Log a subscription in

Log each listed subscription in at the place node.yaml names for it:

CLAUDE_CONFIG_DIR=~/.claude-fallback claude /login
CODEX_HOME=~/.codex-fallback codex login
PI_CODING_AGENT_DIR=~/.pi-fallback pi

For Pi, type /login once it starts. Each subscription must be logged into a different provider account: a second login to an account listed before it shares that account's usage limit, so it is marked duplicate and never used.

Choose the primary

pidgen-worker subscriptions show
pidgen-worker subscriptions use claude claude-fallback

pidgen-worker subscriptions show lists each agent's subscriptions in node.yaml order with the agent's max, the primary starred. For each it prints the first 12 characters of the login's fingerprint and its state:

State	Meaning
ready	Logged in.
not_ready	No login where node.yaml says it is kept.
unknown	The login is kept where the worker cannot see it, such as the macOS keychain or a cloud identity. The subscription is still used.
duplicate	Logged into the same provider account as a subscription before it; never used.

pidgen-worker subscriptions use <harness> <label> makes <label> the agent's primary. It changes only primary in node.yaml, keeping comments and the fallback order, refuses a label the agent does not list, and then asks the running worker to apply it. It prints saved and then what the worker did, with the same messages and exit statuses as a change of size (see Change the size). New work runs on the new primary from then on, with nothing restarted. You can also change primary in an editor.

You can always change the primary on your own machine, whatever your Pidgen plan includes.

How Pidgen uses subscriptions

Pidgen chooses the subscription each step runs under; the worker never picks one itself. New work runs on the primary. Whether Pidgen may also run work on the other subscriptions, and switch to the next one automatically when one reaches its usage limit, depends on your Account's plan. Without that, only the primary is used. A switch Pidgen makes is not saved to node.yaml: when the worker restarts, or you change the primary, it returns to the primary.

The worker reports each subscription's login state to Pidgen, and for Claude Code and Codex its most recent usage reading. Readings are shown as of the time they were taken, and never decide whether work runs.

Two steps on two subscriptions run side by side, each with its own login:

• Claude Code keeps each subscription's sessions in that subscription's config_dir.
• Codex runs each subscription in a separate home inside the worker's home, so one subscription's sessions never appear in another's.
• Pi uses the subscription's auth.json for that step only.

Check the logins

pidgen-worker doctor

pidgen-worker doctor reports each listed subscription as subscription:<harness>/<label>. It fails a subscription that is not logged in, or that is logged into the same provider account as one before it, and prints the command that logs it in.

The agent's environment

A coding agent does not inherit everything exported in the shell the worker started from. It gets a fixed set of variables: the basics (PATH, HOME, USER, locale and terminal settings, temporary directories), toolchain and certificate settings, proxy settings, SSH_AUTH_SOCK and GIT_SSH_COMMAND, each agent's home (CLAUDE_CONFIG_DIR, CODEX_HOME, PI_CODING_AGENT_DIR, PI_CODING_AGENT_SESSION_DIR), and the model-provider credentials (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, CLAUDE_CODE_OAUTH_TOKEN, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_ORG_ID, GEMINI_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, GROQ_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY).

If Claude Code needs another variable, for example CLAUDE_CODE_USE_BEDROCK and AWS_PROFILE to use Amazon Bedrock, add its name to environment_allowlist under claude in the worker policy. The worker's own credential is never passed to an agent.