Adds a how-to page for using a Claude subscription with Claude Code
inside a Coder workspace, rather than an Anthropic API key. Until now
the docs covered API keys, other providers, and AI Gateway, but not this
path.
New page: `docs/workspaces/workspace-access/claude-code-subscription.md`
(added to the sidebar under Workspace access, after Claude Desktop).
- **Interactive sign-in:** `claude auth login` (or `/login`), open the
printed URL locally, paste the code back. A fallback section covers
forwarding the `localhost` callback port with `coder port-forward` or
`ssh -L` when a local browser gets redirected to the workspace.
- **Long-lived token:** `claude setup-token`, stored as a Coder user
secret injected as `CLAUDE_CODE_OAUTH_TOKEN`. Also covers the Claude
Code module's `claude_code_oauth_token` input for template admins, and
notes that a template-level token is shared by every user of that
template.
- **Troubleshooting:** `ANTHROPIC_API_KEY` takes precedence over the
subscription. Confirm with `claude auth status --text` or `/status`,
then `unset` the key. Also lists where Coder can set the key (user
secret, dotfiles, template). Notes that `ANTHROPIC_AUTH_TOKEN` (AI
Gateway) also takes precedence.
- **Cross-links** from `templates/extending-templates/modules.md` (AI
agent modules), `ai-governance/ai-gateway/clients/claude-code.md` (BYOK
Claude subscription), and
`workspaces/workspace-access/claude-desktop.md` (next steps).
Claude Code behavior (precedence, `setup-token`, plan requirements)
links to Anthropic's docs instead of restating plan details.
**These steps were not tested with a real Claude subscription.** I ran
Claude Code 2.1.318 in a Linux workspace without completing a sign-in. I
captured the `claude auth login` prompt and the redirect targets of both
the printed and the browser-opened URLs. I also captured `claude auth
status` output with dummy `CLAUDE_CODE_OAUTH_TOKEN` and
`ANTHROPIC_API_KEY` values to confirm precedence.
<details>
<summary>Decision log</summary>
- **Paste-code flow first, port forwarding as fallback.** The URL that
`claude auth login` prints redirects to
`https://platform.claude.com/oauth/code/callback`, which shows a code to
paste, so SSH users don't need to forward a port. Only the URL handed to
`$BROWSER` redirects to `http://localhost:<random-port>/callback`. The
ticket described port forwarding as the main path.
- **Page location.** No Claude Code page exists under Workspaces. Claude
Code in workspaces is only mentioned in `modules.md` and the AI Gateway
client page. The page sits next to Claude Desktop, and those pages link
to it.
- **User secret over template input for the token.** A subscription
token belongs to one person. A user secret is per user and overrides
`coder_env` with the same name. The template input is still documented
for admins, with the sharing caveat.
</details>
### Verified against
- `coder/registry`: `registry/coder/modules/claude-code/main.tf` and
`README.md` (main, v5.5.2). `claude_code_oauth_token` is sensitive and
sets `CLAUDE_CODE_OAUTH_TOKEN`. It exists in v5.2.0, which matches the
docs' `~> 5.2` pin. Plan-time validation rejects it together with
`enable_ai_gateway` or `api_key_helper`.
- `cli/portforward.go` and
`docs/workspaces/workspace-access/port-forwarding.md`: `--tcp` syntax
and the `ssh -L` section anchor.
- `cli/secret.go`, `docs/workspaces/user-secrets.md`,
`site/src/pages/UserSettingsPage/SecretsPage/SecretDialog.tsx` and
`SecretsPageView.tsx`: Account > Secrets, **Add secret**, the **Name**,
**Value**, and **Environment variable** field labels, **Save**, and
user-secret precedence over `coder_env`.
- Anthropic's Claude Code docs: `authentication` (log in, credential
storage, authentication precedence, generate a long-lived token) and
`cli-reference` (`claude auth login`, `claude auth status`, `claude
setup-token`).
- Local runs of Claude Code 2.1.318 as described above.
### Open questions for the reviewer
- Nobody has completed either flow with a real Pro or Max account.
Someone with a subscription should check the paste-code flow end to end,
and that `claude auth status` then shows `"authMethod": "claude.ai"`
(the value comes from Anthropic's CLI reference).
- The port-forward fallback says to reload the failed `localhost`
callback page after starting `coder port-forward`. I haven't confirmed
that the reload completes the sign-in instead of needing a fresh `claude
auth login`.
- The acceptance criteria ask for a link back from the registry module
page. That README lives in `coder/registry` and needs a separate PR
there.
- Should the template example have a callout about whether sharing one
subscription token across users is acceptable? The page currently only
states the consequence.
Generated by Coder Agents.
Closes DOCS-510
Co-authored-by: Coder Prototypes <294797144+coder-prototypes@users.noreply.github.com>