> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reuse your coding agent subscription across workspaces

Authenticate Claude Code, OpenAI Codex, and GitHub Copilot CLI once and reuse
the same credential across every workspace and project, without a browser
login each time a workspace starts.

## How it works

The pattern is the same for all three agents:

1. **Generate the credential once** on your laptop (or any machine with a browser).
2. **Store it as a Domino user environment variable.** In the Domino UI, go to
   **Account** > **Account Settings** > **User environment variables**.
   [User-level variables](/cloud/platform-capabilities/core-concepts/compute-environments/manage-compute-environments/manage-environment-variables/4-setup-user-environment-variables)
   follow you across all projects and workspaces (unlike project-level
   variables), and Domino injects them into every run you start.
3. **If the CLI needs a file on disk or first-run state patched**, add a
   snippet to the Compute Environment's pre-run script (**Environments** >
   **Edit Definition** > **Run Setup Scripts**). This runs at workspace
   startup, after the user environment variables are already injected. A user
   or admin adds this to the environment once.

Claude Code and Copilot CLI only need the environment variable. Codex
additionally needs a pre-run script to materialize its credential file.

<Tip>
  These recipes reuse your existing coding agent subscription across workspaces.
  You can also use coding agents alongside the new Domino LLM Gateway 2.0 to
  route agent traffic through Domino's centrally governed model access. LLM
  Gateway 2.0 is currently in early access and distributed as a separately
  deployed app; contact your Domino field representative for details.
</Tip>

<Tabs>
  <Tab title="Claude Code">
    Claude Code uses a single long-lived OAuth token that works across many
    workspaces at once.

    1. Generate the token once on your laptop:

       ```bash theme={null}
       claude setup-token
       ```

       The command walks you through OAuth login and prints a token that starts
       with `sk-ant-oat01-...`. It is **not** saved anywhere, so copy it. The token
       is valid for roughly a year and auto-refreshes.

    2. In **Account Settings** > **User environment variables**, add:

       * Name: `CLAUDE_CODE_OAUTH_TOKEN`
       * Value: `sk-ant-oat01-...`

    3. That's it. The Claude Code settings shipped with the Domino Standard
       Environment handle first-run onboarding, so the token is picked up
       automatically in every new workspace.

    No interactive login is needed. Requires a Pro, Max, Team, or Enterprise plan.

    <Warning>
      If `ANTHROPIC_API_KEY` is also set (check project- and environment-level
      variables too), it takes precedence once approved and bills per-token to your
      API account instead of using your subscription. Remove it.
    </Warning>

    **Parallel workspaces:** Work fine; the same static token works everywhere
    simultaneously.
  </Tab>

  <Tab title="OpenAI Codex">
    Codex has no single "print a token" command. Subscription (ChatGPT) auth lives
    in a JSON credential file, so this recipe needs both a user environment
    variable and a pre-run script to write the file at workspace startup. OpenAI
    treats this as an advanced workflow. API keys are their recommended default
    for CI/CD, but those bill per-token, not against your subscription.

    1. Seed `auth.json` once on your laptop or workstation outside of Domino, or
       inside a throwaway Domino workspace.

       Configure file-backed storage in `~/.codex/config.toml`:

       ```toml theme={null}
       cli_auth_credentials_store = "file"
       ```

       Then log in:

       ```bash theme={null}
       codex login
       ```

       Confirm that `auth.json` was created. Typical locations:

       * macOS / Linux: `~/.codex/auth.json`
       * Windows: `%USERPROFILE%\.codex\auth.json` (usually `C:\Users\<you>\.codex\auth.json`)
       * Custom: wherever `$CODEX_HOME` points, if you set it

       If the file exists, you're good to continue.

    2. In **Account Settings** > **User environment variables**, add:

       * Name: `CODEX_AUTH_JSON`
       * Value: the entire contents of your `auth.json` file, pasted as-is.

    3. In the environment's pre-run script, materialize the file. A user or admin
       adds this once to the Compute Environment:

       ```bash theme={null}
       export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
       mkdir -p "$CODEX_HOME" && chmod 700 "$CODEX_HOME"
       # only seed if missing; do NOT overwrite a refreshed file every run
       [ -f "$CODEX_HOME/auth.json" ] || printf '%s' "$CODEX_AUTH_JSON" > "$CODEX_HOME/auth.json"
       chmod 600 "$CODEX_HOME/auth.json"
       ```

    4. Run `codex` normally in the workspace. It refreshes the token bundle in
       place when the session is stale (roughly every 8 days) and writes the new
       tokens back to `auth.json`.

    #### How long the seed lasts

    `auth.json` contains two tokens with different lifetimes:

    * The **access token** (used for API calls) is a JWT valid for roughly a week.
      The CLI proactively refreshes once `last_refresh` is older than roughly 8
      days. Multiple workspaces using the same still-valid access token
      simultaneously is fine.
    * The **refresh token** is rotated on use. When any copy refreshes, the server
      issues a new refresh token and invalidates the old one. Every other copy of
      the credential (other workspaces, the `CODEX_AUTH_JSON` seed value, and even
      your laptop) then holds a dead refresh token and gets a 401 the next time
      *it* tries to refresh.

    Short-lived parallel workspaces (hours to a few days) work as expected. The
    breakage only shows up past the roughly 8-day refresh cycle, and it shows up
    as mysterious 401 responses: a long-running workspace dies after another one refreshed
    first, or a *fresh* workspace fails because the environment variable seed has
    quietly gone stale since something else in the lineage rotated the token.

    Your laptop is part of the same lineage: it keeps itself logged in
    indefinitely by rolling the refresh chain forward, which also means:

    * the seed you pasted into Domino weeks ago is probably already past its refresh, and
    * a long-running workspace that refreshes first can knock your *laptop* out of its session.

    <Warning>
      Treat `auth.json` like a password. Domino stores user environment variables
      encrypted in its secret store, which is where it belongs. Never commit it to
      a repo or project files.
    </Warning>

    **Watch out:**

    * If refresh stops working (401 responses), reseed. Run a fresh `codex login` on your
      laptop and re-paste `auth.json` into the `CODEX_AUTH_JSON` user environment
      variable.
    * The home directory of a workspace is typically ephemeral. A fresh workspace
      gets the seed from `CODEX_AUTH_JSON`, not the last refreshed file, so keep
      the seed reasonably fresh.
    * This does not apply to API-key auth or `chatgptAuthTokens` host
      integrations.

    **Parallel workspaces:** Work fine within an access-token window (roughly a week),
    breaks down across refresh cycles because the refresh token rotates.
  </Tab>

  <Tab title="GitHub Copilot CLI">
    Copilot CLI is the closest analog to Claude Code and the simplest fit for
    Domino: a static fine-grained personal access token (PAT) in a user
    environment variable, no pre-run script needed.

    1. Create a fine-grained personal access token once:

       * Resource owner: your **personal** account (not an organization).
       * Permission: **Copilot Requests** (only available on user-owned
         fine-grained PATs).
       * Repository access: as needed for your work.

       Classic PATs (`ghp_`) are **not** supported. The token looks like
       `github_pat_...`.

    2. In **Account Settings** > **User environment variables**, add:

       * Name: `COPILOT_GITHUB_TOKEN`
       * Value: `github_pat_...`

    The CLI checks these variables in order of precedence: `COPILOT_GITHUB_TOKEN`,
    then `GH_TOKEN`, then `GITHUB_TOKEN`. No browser, no per-workspace login, no
    pre-run script.

    **Watch out:**

    * An environment variable silently overrides any stored OAuth token. If
      `GH_TOKEN` is set for another tool (a common setup in Domino environments
      for Git access), the CLI may use that instead. `COPILOT_GITHUB_TOKEN` wins
      the precedence order, so set it explicitly rather than relying on
      `GH_TOKEN`.
    * Billing: smaller included models don't consume premium requests; more
      capable models draw on premium quota. Use `--model` to pick cheaper models
      for automation.
    * This is the standalone Copilot CLI, not the VS Code extension. The CLI is
      the right tool for headless workspaces.

    **Parallel workspaces:** Work fine; a static PAT works everywhere simultaneously.
  </Tab>
</Tabs>

## Quick comparison

| Agent           | User environment variable                     | Pre-run script needed?                        | Parallel workspaces                                  |
| --------------- | --------------------------------------------- | --------------------------------------------- | ---------------------------------------------------- |
| **Claude Code** | `CLAUDE_CODE_OAUTH_TOKEN` from `setup-token`  | No                                            | Fine, static token                                   |
| **Codex**       | `CODEX_AUTH_JSON` = full `auth.json` contents | Yes, writes `~/.codex/auth.json` from the var | Fine for roughly a week, then refresh rotation bites |
| **Copilot CLI** | `COPILOT_GITHUB_TOKEN` = fine-grained PAT     | No                                            | Fine, static PAT                                     |

<Tip>
  Keep any API-key environment variables (`ANTHROPIC_API_KEY`,
  `CODEX_API_KEY`, `OPENAI_API_KEY`) *out* of your user, project, and
  environment variables unless you deliberately want per-token API billing
  instead of subscription usage.
</Tip>

## Use with Domino LLM Gateway 2.0

Coding agents can be used in concert with the new Domino LLM Gateway 2.0 to
centrally govern how they call external Large Language Model providers,
alongside the subscription-reuse pattern above. LLM Gateway 2.0 is currently
in early access and distributed as a separately deployed app. Contact your
Domino field representative for details on how to route your coding agent
traffic through it.

## Next steps

* [Custom environments (advanced)](/cloud/platform-capabilities/features/coding-assistants/custom-environments):
  Bundle CLI tools, MCP servers, or a different coding agent into a Compute
  Environment.

* [User Environment Variables](/cloud/platform-capabilities/core-concepts/compute-environments/manage-compute-environments/manage-environment-variables/4-setup-user-environment-variables):
  Reference for creating, updating, and deleting user-level variables.

* [Edit an environment definition](/cloud/platform-capabilities/core-concepts/compute-environments/manage-compute-environments/5-edit-environment-definition):
  Where pre-run scripts live in the Compute Environment definition.


## Related topics

- [Get started with AI coding assistants](/cloud/platform-capabilities/features/coding-assistants/get-started.md)
- [Use coding assistants](/cloud/platform-capabilities/features/coding-assistants/index.md)
- [Custom environments (advanced)](/cloud/platform-capabilities/features/coding-assistants/custom-environments.md)
- [Agents](/cloud/platform-capabilities/features/agents/index.md)