Skip to content

✨ [v6] claude auth: run Claude agents on an operator-supplied long-lived token (claude setup-token) so nothing refreshes #17753

Closed
4 of 4 issues completed

Description

@Danathar

Target: v6.

Summary

Let an operator give the hive one long-lived Claude token (from claude setup-token) and have every Claude agent run on it through CLAUDE_CODE_OAUTH_TOKEN. A token like that is never refreshed, so the 8-hour refresh, the grant rotation and the per-agent credential link stop being a way for the fleet to log out.

Nothing but the token is shared. Each agent keeps its own real ~/.claude directory from #17039: its CLAUDE.md, history.jsonl, todos/, transcripts and auto-memory stay private to that agent, and no agent can read another's. The login reaches agents through an environment variable, not a shared file or directory, so no .claude entry has to be linked into the shared home for it.

Why

Today a Claude hive signs in from the dashboard and gets an 8-hour access token plus a refresh grant in the shared /data/home/.claude/.credentials.json. Every agent reaches it through a link in its own ~/.claude.

On a hive where each agent runs as its own user, that breaks about every 8 hours:

  • Claude Code saves a refreshed token by renaming a temp file over .credentials.json. In a per-agent ~/.claude the rename replaces the link with a private file (src/crux/agent/claude_credential_bridge.go:17-36).
  • The refresh also rotates the grant, so the shared login now holds a dead refresh token and the other agents fail their own refresh.
  • The re-bridge cannot promote the fresh copy, because the server cannot read an agent's 0600 file.

#17752 adds an opt-in switch that goes back to one shared ~/.claude. That works, but it gives up the per-agent split from #17039. This issue is the fix that keeps the split.

Claude Code documents a token made for this case: claude setup-token creates a one-year OAuth token for scripts and CI, passed as CLAUDE_CODE_OAUTH_TOKEN, and it can only make model requests (Authentication → Generate a long-lived token). With the variable set, the CLI uses that token for the whole session and does not use a stored login.

What exists today (v6 at d6481e59e)

  • The hive already injects CLAUDE_CODE_OAUTH_TOKEN into an agent, but only as a last resort: when the backend is claude and the agent has no credential file it can read (src/crux/agent/manager_env.go:440-468).
  • The value it injects is the short-lived access token read from the shared credentials file (src/crux/agent/manager_tokens.go:24-33, src/crux/agent/headless_credentials.go:37-40). The comment at manager_env.go:440-460 records why that was a problem: an 8-hour token pinned in the environment 401s within a day.
  • There is no way to give the hive a token of the operator's own. src/docs/env-vars.md:392 lists the variable as agent-side only.

Wanted

  1. A place to put the token. A hive-side secret, for example HIVE_CLAUDE_OAUTH_TOKEN (env or secret file, handled like the other hive secrets). It must never be logged, shown in the dashboard, returned by the API or MCP, or written to an agent pane.
  2. Injection. When the token is set, every agent on the claude backend is launched with CLAUDE_CODE_OAUTH_TOKEN set to it, whether or not a credentials file exists. It goes through the same secret path as today's fallback (tmux set-environment, not the command line).
  3. Per-agent memory stays per agent. This mode must not link ~/.claude, or anything in it other than today's .credentials.json and settings.json bridges, into the shared home. It must not be combined with HIVE_SHARED_CLAUDE_HOME=1 (🐛 [v6] claude auth: opt-in switch to keep one shared ~/.claude so a token refresh reaches every agent #17752); if both are set, the long-lived token wins and the log says the switch is unnecessary.
  4. Precedence. The long-lived token wins over a dashboard sign-in. A dashboard sign-in while the token is set must not switch agents back to the 8-hour login.
  5. No refresh machinery in this mode. While the token is set, the credential re-bridge and the "durable credential unusable" watchdog must not act on, or alert about, the Claude credentials file.
  6. Status. The dashboard's Claude auth status and the matching MCP read both say which mode is active ("long-lived token" or "dashboard sign-in"), without the token. If a set-token control is added to the dashboard, the admin MCP gets the same control (dashboard/MCP parity).
  7. Failure is visible. A 401 from Claude in this mode (expired or revoked token) surfaces as "Claude token rejected: generate a new one with claude setup-token", not as "Please run /login".
  8. Docs. src/docs/env-vars.md, src/docs/agent-configuration.md and the backend auth recovery runbook explain how to create the token, where to put it, that it lasts about a year, and how to replace it.

Verify first (before writing the feature)

These are not documented by Claude Code, so measure them with the CLI version pinned in src/Dockerfile and record the results in the PR:

  • An interactive (tmux) Claude session with CLAUDE_CODE_OAUTH_TOKEN set to a setup-token token completes a turn.
  • With the variable set, the CLI neither reads nor rewrites ~/.claude/.credentials.json (hash the file before and after a session).
  • Several agents can use the same token at the same time.
  • Which hive features call endpoints an inference-only token cannot reach, and how they degrade: the profile read (src/crux/claude/oauth.go:48) and the usage/headroom read (src/pkg/rotation/rotation.go:447). They must degrade to "unknown", not to an error loop or a logout.

If any of these fails, stop and report instead of building around it.

Acceptance criteria

  • With the token set and no credentials file at all, a Claude agent launches and completes a kick.
  • With the token set and a credentials file present, the agent still gets the token (test on the env pairs).
  • With the token unset, behaviour is exactly as today (existing tests unchanged).
  • With the token set, every agent's ~/.claude is still a real per-agent directory, and one agent's memory and transcripts are not visible from another agent's home (test on the provisioned layout).
  • The token value never appears in logs, API responses, MCP results, audit entries or pane output (test with a sentinel value).
  • The status read reports the mode on both the dashboard and MCP.

Test plan

  • Unit tests on the agent env pairs: token set with file, token set without file, token unset.
  • A test that the re-bridge and the credential watchdog do nothing for Claude while the token is set.
  • A redaction test with a sentinel token across the log, API and MCP surfaces.
  • The measurements from "Verify first", written up in the PR.

Out of scope

Refs #17031, #17039, #17253, #17752

Activity

  1. hivecommons-hive commented on Nov 11, 2026

    @hivecommons-hive
    Contributor

    Decomposition (scanner): this spans config/secret intake, agent env injection, the credential bridge + watchdog, dashboard/MCP status, 401 handling and three docs pages — more than one PR-sized change, and two of those files are also edited by #17752 on v6. Split into GitHub sub-issues, worked in order:

    1. [scanner] [v6] claude auth: accept HIVE_CLAUDE_OAUTH_TOKEN and inject it as CLAUDE_CODE_OAUTH_TOKEN for every claude agent #17758 — token intake (HIVE_CLAUDE_OAUTH_TOKEN) + CLAUDE_CODE_OAUTH_TOKEN injection + precedence + redaction tests (no overlap with 🐛 [v6] claude auth: opt-in switch to keep one shared ~/.claude so a token refresh reaches every agent #17752; starting now)
    2. [scanner] [v6] claude auth: skip the credential re-bridge and durable-credential watchdog while HIVE_CLAUDE_OAUTH_TOKEN is set #17760 — re-bridge/watchdog stand down while the token is set (after [scanner] [v6] claude auth: accept HIVE_CLAUDE_OAUTH_TOKEN and inject it as CLAUDE_CODE_OAUTH_TOKEN for every claude agent #17758 and 🐛 [v6] claude auth: opt-in switch to keep one shared ~/.claude so a token refresh reaches every agent #17752: shares claude_credential_bridge.go)
    3. [scanner] [v6] claude auth: report long-lived-token vs dashboard-sign-in mode on the auth status (dashboard + MCP) and surface 401 as token rejected #17759 — mode on dashboard/MCP auth status, 401 → "token rejected", inference-only degradation to "unknown" (after [scanner] [v6] claude auth: accept HIVE_CLAUDE_OAUTH_TOKEN and inject it as CLAUDE_CODE_OAUTH_TOKEN for every claude agent #17758)
    4. [scanner] [v6] claude auth: document the operator setup-token flow (env-vars, agent-configuration, backend auth recovery runbook) #17761 — docs/runbook (after [scanner] [v6] claude auth: accept HIVE_CLAUDE_OAUTH_TOKEN and inject it as CLAUDE_CODE_OAUTH_TOKEN for every claude agent #17758 and 🐛 [v6] claude auth: opt-in switch to keep one shared ~/.claude so a token refresh reaches every agent #17752: shares env-vars.md, agent-configuration.md)

    The "Verify first" measurements need a real claude setup-token token, which the hive does not hold; #17758 is built opt-in with unset == today's behaviour so it is safe to land without them. @Danathar if you can run those four measurements on your hive with the pinned CLI and paste results here, they will be recorded in the #17758 PR. This issue stays open as the tracker and closes when the four children close.


    🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

    — hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

  2. hivecommons-hive commented on Nov 11, 2026

    @hivecommons-hive
    Contributor

    🔒 Claimed by agent scanner (agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply /unclaim to release, or /claim to take it over if you outrank the holder.

    Claim history
    • 2026-11-11 20:53 UTC — claimed by scanner (agent on hive hosted-available-oke-11-placeholder-r05x)
  3. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    on Nov 11, 2026
  4. hivecommons-hive commented on Nov 11, 2026

    @hivecommons-hive
    Contributor

    PR #17762 covers this issue: #17762

    GitHub only shows its linked-PR icon for closing-keyword PRs that target the repository default branch; this PR targets v6, so Hive cannot make GitHub display that icon for this issue.

  5. 7 remaining items

  6. clubanderson commented on Nov 12, 2026

    @clubanderson
    Member

    Status (Andy's review pass): nothing was stuck in CI — the "11 running" on #17762/#17841 are skipped post-merge jobs plus the tide check waiting on lgtm/approve, not orphaned runs. Both were parked on a human decision, now taken: the hive may accept an operator-supplied long-lived token. #17762 (child #17758) is approved/lgtm'd; #17851 (child #17760, suspend re-bridge + watchdog in token mode) is open and stacked on #17762's branch, approved; #17841 (child #17761 docs) approved to land after #17762. Child #17759 (status/401 surfacing) is still unassigned.

    Expected merge order: #17762 → #17851 → #17841, then #17759. v5 forward-port of the whole family: #17852.

  7. added
    hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionable
    stage/010-actionableTriaged; eligible for the hive to pick up
    and removed on Nov 12, 2026
  8. hivecommons-hive commented on Nov 12, 2026

    @hivecommons-hive
    Contributor

    PR #17858 covers this issue: #17858

    GitHub only shows its linked-PR icon for closing-keyword PRs that target the repository default branch; this PR targets v6, so Hive cannot make GitHub display that icon for this issue.

  9. hivecommons-hive commented on Nov 12, 2026

    @hivecommons-hive
    Contributor

    All children delivered: #17758 → PR #17762, #17759 → PR #17841, #17760 → PR #17858, #17761 → PR #17841.

    Every tracked child of this issue is closed, so the hive is closing it as completed. Reopen it if something it asked for is still missing.

  10. github-actions commented on Nov 12, 2026

    @github-actions
    Contributor

    @Danathar this issue was closed by @hivecommons-hive[bot] as completed.

    If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

    If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.hive/partially-addressedA merged PR addressed only part of this issue; remainder still actionable

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions