Repository navigation
Description
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~/.claudethe 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
0600file.
#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_TOKENinto an agent, but only as a last resort: when the backend isclaudeand 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 atmanager_env.go:440-460records 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:392lists the variable as agent-side only.
Wanted
- 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. - Injection. When the token is set, every agent on the
claudebackend is launched withCLAUDE_CODE_OAUTH_TOKENset to it, whether or not a credentials file exists. It goes through the same secret path as today's fallback (tmuxset-environment, not the command line). - Per-agent memory stays per agent. This mode must not link
~/.claude, or anything in it other than today's.credentials.jsonandsettings.jsonbridges, into the shared home. It must not be combined withHIVE_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. - 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.
- 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.
- 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).
- 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". - Docs.
src/docs/env-vars.md,src/docs/agent-configuration.mdand 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_TOKENset to asetup-tokentoken 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
~/.claudeis 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
- Changing how the dashboard sign-in or the 8-hour refresh works.
- The credential re-bridge itself.
- Removing the
HIVE_SHARED_CLAUDE_HOMEswitch from 🐛 [v6] claude auth: opt-in switch to keep one shared ~/.claude so a token refresh reaches every agent #17752. - Rotating or minting the long-lived token for the operator. They run
claude setup-tokenthemselves.
Activity
hivecommons-hive commentedon Nov 11, 2026
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:
HIVE_CLAUDE_OAUTH_TOKEN) +CLAUDE_CODE_OAUTH_TOKENinjection + 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)claude_credential_bridge.go)env-vars.md,agent-configuration.md)The "Verify first" measurements need a real
claude setup-tokentoken, 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
hivecommons-hive commentedon Nov 11, 2026
🔒 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/unclaimto release, or/claimto take it over if you outrank the holder.Claim history
scanner(agent on hive hosted-available-oke-11-placeholder-r05x)hivecommons-hive commentedon Nov 11, 2026
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.7 remaining items
clubanderson commentedon Nov 12, 2026
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.
hivecommons-hive commentedon Nov 12, 2026
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.hivecommons-hive commentedon Nov 12, 2026
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.
github-actions commentedon Nov 12, 2026
@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
/reopenand 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.🌱 Top up v6 with v5 latest (v5.237.2) (#18030)
🐛 claude auth: share refreshed logins across per-agent .claude homes …