main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-claude-auth description: >- How Claude Code signs in inside Hydrogen on Linux: the OAuth flow, where credentials live, the backup that survives a workspace rebuild, and how to recover. Use when Claude is not authenticated, the Claude token expired, or Claude needs to re-auth after a virgin reset.

Hydrogen Claude Auth: how Claude Code signs in

Claude Code (the VS Code extension and the claude CLI in the workspace) signs in separately from your Adom login.

For Adom auth (your hydrogen.adom.inc login), see hydrogen-adom-auth. This skill is Claude-Code-specific.

Where sign-in happens

Setup does not sign anyone in to Claude. After setup the user picks and signs in to an AI from Manage AIs (Adom logo menu) or Your AIs (profile menu), the "Choose your AI" dialog. On Linux those sign-in links always open in the system browser (never an in-app tab), with no picker countdown.

  1. The Claude Code panel shows "Claude.ai Subscription" when it is not signed in.
  2. Clicking it opens the claude.ai OAuth page in the browser.
  3. claude.ai redirects to a localhost callback port. The workspace shares this computer's network, so the callback reaches the workspace directly.
  4. The credentials land at /home/adom/.claude/.credentials.json in the workspace.

Where Claude credentials live

Layer Location Purpose
Inside workspace (live) /home/adom/.claude/.credentials.json Active credentials the extension and claude CLI both read
Host-side backup ~/.config/hydrogen-desktop/replay-claude-credentials.json Lets a rebuilt workspace stay signed in
VS Code secret store (in code-server's user data) webview-internal, can't be inspected directly The extension also keeps a secret per panel; this is what dictates the chat UI showing vs the auth button

The backup is written by a virgin reset that keeps Claude (it copies the live file out before wiping) and by the old-image migration.

Key insight: each Claude Code panel instance keeps its own auth state. If one panel says "not authenticated", opening a NEW Claude Code conversation panel often shows the auth button fresh and lets you sign in cleanly.

Recovery

BASE="$(cat ~/.adom/hydrogen-control-url)"
curl -s "$BASE/claude/auth-status"                                   # what Hydrogen sees
curl -s -X POST "$BASE/demo/run" -d '{"action":"reinject-claude-creds"}'   # put the backup back
curl -s -X POST "$BASE/claude/wipe-creds" -d '{"backup":false}'      # sign out, keep the backup

/claude/wipe-creds always removes the workspace credentials; backup:true (the default) also deletes the host backup. claude_authorize_in_browser is not available on Linux.

Virgin reset: what each option does

The setup panel's Virgin Reset section has a per-Claude-creds toggle:

Toggle What happens to Claude auth When to use
Claude credentials (default OFF) Deletes the replay-claude-credentials.json backup from the host AND the credentials inside the workspace. You will need to re-OAuth. When Claude is stuck in a broken auth state and you want a true fresh sign-in.
Workspace The workspace machine is rebuilt. With the Claude credentials toggle OFF, the host backup is kept, so the user can be restored (reinject-claude-creds). Normal virgin reset for testing.

Standard pattern for AI-driven testing: keep the "Claude credentials" toggle OFF so testing doesn't bounce you out of Claude every cycle.

Common failures

"Claude.ai Subscription" button keeps appearing even though I just signed in

  • A SECOND panel still has stale auth state. Close all Claude Code panels and open one fresh — it'll read the new credentials.

Credentials backup file exists but Claude says expired

  • Check expiresAt (epoch ms) in ~/.config/hydrogen-desktop/replay-claude-credentials.json. If it is past, sign in again from Manage AIs.

claude auth status says loggedIn: true but the extension says not authenticated

  • Known quirk: the CLI and the VS Code extension use SEPARATE credential stores. claude auth status checks the CLI store; the extension uses VS Code secrets. Trust the extension UI (the "Claude.ai Subscription" button) over the CLI's status output.

OAuth callback fails / browser shows "connection refused"

  • The claude process that opened the callback port has exited, or the sign-in timed out: start the sign-in again from Manage AIs.
  • hydrogen-adom-auth — Adom (hydrogen.adom.inc) login, separate from Claude
  • hydrogen-setup-steps: what setup does and does not do for AIs
  • hydrogen-volume — explains why the host-side backup survives workspace rebuild