Agent sign-in

AI agents are signed in per worker: each worker keeps its own agent credentials on shared config volumes, so a login done once persists across every DevBox that worker launches — including the ones runs and schedules create for you. This guide walks the wizard that sets that up.

Starting the wizard

Three ways in, all landing on the same flow:

• From a worker — open any worker’s page (or a cloud worker’s) and click Sign-in agents. This is the canonical entry point.
• From a failed run or schedule — when an execution fails because an agent isn’t authenticated, the remediation banner links straight into the wizard for the right worker.
• Directly — open /authenticate in the console and pick a worker.

The wizard

1. Agent selection. Pick which agents to sign in — Claude Code, Codex, GitHub Copilot. You can pre-register credentials instead of signing in interactively: set the agent’s API key or token under Settings → Environment Variables → Agent Secrets (Claude OAuth token, Anthropic API key, OpenAI API key, or Copilot GitHub token).

2. Build environment. The wizard builds (or reuses) a DevBox on the worker with the selected agents installed. Credentials created inside it persist across DevBox recreation via the shared config volumes, encrypted end-to-end with a per-user key.

3. Sign each agent in. For terminal-login agents the wizard embeds a live terminal seeded with the right command (for example claude auth login). Verification is automatic — after you finish the login the wizard polls and flips the live status badge (a “Checking authentication…” indicator shows while it checks), with a Check now button to probe immediately.

4. Summary. Live status for every selected agent, plus a reference link to Settings → Environment Variables for the stored agent secrets and service tokens. The summary doesn’t embed the credential forms — sign-in itself is per worker, while the stored keys and tokens are global. Fill in any that are still missing there so the next failure never happens:

   • Service access — the GitHub / Azure DevOps / GitLab / Jira tokens your runs need to reach repositories and tickets; see the service access tokens reference.
   • Agent Secrets — the Claude, Anthropic, OpenAI, and Copilot API keys and tokens; see the agent secrets reference.

Tip

Agent sign-in and service tokens are the two halves of a ready worker: the agent must be able to think (signed in) and to reach your code (service tokens). The wizard’s summary links you to both so a brand-new setup is one visit, not two failures.

Checking status later

• Worker, cloud-worker, and DevBox cards show a per-agent auth status badge; runs and schedules surface it in their create panels.
• A run or schedule that fails on agent auth pauses (schedules auto-pause after two consecutive auth failures) and links back to the wizard.
• Asking Nucleus about a worker’s readiness reads the same live status.