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>
7.1 KiB
title
| title |
|---|
| Sign in to Claude Code with a Claude subscription |
Use your Claude subscription to authenticate Claude Code in a Coder workspace, instead of an Anthropic API key. This guide is for developers who run the Claude Code CLI in a workspace terminal.
Claude Code in a workspace is the same CLI that you run on your local machine. When no other credential is set, Claude Code uses your subscription sign-in. Anthropic's authentication precedence lists the order in which Claude Code picks a credential.
You can authenticate in one of two ways:
- Sign in interactively: Claude Code saves your sign-in in the workspace.
- Use a long-lived token: Coder injects a token into your workspaces as an environment variable.
Prerequisites
- A Claude account with a plan that includes Claude Code. Refer to Anthropic's authentication documentation for the account types.
- Claude Code installed in your workspace. Your template can install it with the Claude Code module, or you can install it yourself.
- A terminal in your workspace, such as
coder ssh, the web terminal, or your IDE's terminal.
Sign in interactively
-
Open a terminal in your workspace:
coder ssh <workspace-name> -
Start the sign-in:
claude auth loginClaude Code prints a sign-in URL and waits for a code:
Opening browser to sign in… If the browser didn't open, visit: https://claude.com/cai/oauth/authorize?... Paste code here if prompted >You can also run
claudeand then type/loginat the Claude Code prompt. -
Open the sign-in URL in the browser on your local machine.
-
Sign in with your Claude account and approve access.
-
Copy the code that the browser shows.
-
Paste the code at the
Paste code here if promptedprompt in the workspace terminal. -
Confirm the sign-in:
claude auth statusThe output shows
"loggedIn": trueand"authMethod": "claude.ai".
Claude Code saves your sign-in to ~/.claude/.credentials.json in the workspace.
If your template does not keep your home directory between workspace restarts, sign in again after each restart, or use a long-lived token.
Forward the sign-in port
When Claude Code can open a browser on your local machine, for example from your IDE's terminal, the sign-in redirects to a localhost address instead of showing a code.
That address points to a port in the workspace, such as http://localhost:39437/callback.
Claude Code picks a new port for each sign-in.
Some IDEs forward the port for you.
If the localhost page fails to load after you approve access:
-
Note the port number in the
localhostaddress. -
On your local machine, forward the port from the workspace and leave the command running:
coder port-forward <workspace-name> --tcp <port> -
Reload the
localhostpage in your browser.
You can also forward the port over SSH with ssh -L.
Use a long-lived token
A long-lived token lets Claude Code authenticate without a browser, so every workspace you own can start Claude Code already signed in.
-
Generate a token with Claude Code, on your local machine or in a workspace:
claude setup-tokenThe command opens the same sign-in flow as
claude auth loginand prints a token when you approve access. Claude Code does not save the token. Refer to Anthropic's long-lived token documentation for its requirements and limits. -
Copy the token.
-
In the Coder dashboard, select your avatar, then select Account > Secrets.
-
Select Add secret.
-
Enter a Name, such as
claude-code-oauth-token. -
Paste the token into Value.
-
Enter
CLAUDE_CODE_OAUTH_TOKENin Environment variable. -
Select Save.
-
Restart your workspace.
-
Confirm that Claude Code reads the token:
claude auth status --textAuth token: CLAUDE_CODE_OAUTH_TOKEN
Coder injects the secret into every workspace you own. To manage the secret from the CLI instead, refer to User secrets.
Set the token in a template
Template administrators can pass a token to the Claude Code module with its claude_code_oauth_token input.
The module sets CLAUDE_CODE_OAUTH_TOKEN in every workspace that the template creates, so every user of the template shares the same subscription.
For a token per user, have each user store it as a user secret.
A user secret overrides an environment variable with the same name that the template sets.
variable "claude_code_oauth_token" {
type = string
sensitive = true
}
module "claude-code" {
source = "registry.coder.com/coder/claude-code/coder"
version = "~> 5.2"
agent_id = coder_agent.main.id
claude_code_oauth_token = var.claude_code_oauth_token
}
Set only one authentication input on the module.
The module rejects claude_code_oauth_token together with enable_ai_gateway or api_key_helper.
Troubleshooting
Claude Code uses an API key instead of your subscription
When ANTHROPIC_API_KEY is set, it takes precedence over your subscription sign-in and your token.
In an interactive session, Claude Code asks once whether to use the key.
If the key belongs to a disabled or expired organization, requests fail with authentication errors.
-
Check which credential Claude Code uses:
claude auth status --textThis output shows that the API key overrides the token:
Auth token: CLAUDE_CODE_OAUTH_TOKEN · not in use API key: ANTHROPIC_API_KEY -
Remove the API key from your shell:
unset ANTHROPIC_API_KEY -
Start Claude Code and type
/statusto confirm that it uses your subscription.
unset affects only the current shell.
If ANTHROPIC_API_KEY returns in new shells, remove it where it's set, such as a user secret, your dotfiles, or the template.
If your template sets it, ask your template administrator to remove the anthropic_api_key input from the Claude Code module.
ANTHROPIC_AUTH_TOKEN also overrides your subscription.
When a template enables AI Gateway for Claude Code, Claude Code authenticates with AI Gateway through this variable.
Learn more
- Authentication in the Claude Code documentation
- Workspace ports
- User secrets
- Claude Code module in the Coder Registry