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

# Use claude setup-token With Buckle Agents

> Generate a one-year Claude token with claude setup-token, store it in Buckle, and let Claude Code and other agents use your Claude plan without seeing it.

`claude setup-token` creates a long-lived OAuth token for your Claude subscription. You usually export it as `CLAUDE_CODE_OAUTH_TOKEN`, which puts the token in every agent's environment. With Buckle, you store the token once in the gateway instead. Agents call `api.anthropic.com` as usual, and the gateway adds the token to each request.

## What you will set up

* A Claude subscription token stored as an Anthropic secret in Buckle
* Claude Code running through the Buckle gateway with `buckle run -- claude`
* Requests to `api.anthropic.com` that carry your token, without the token in the agent's environment

## Before you start

* A Claude Pro, Max, Team, or Enterprise plan. The free plan doesn't include Claude Code, so it can't create a token.
* Claude Code installed. Check with `claude --version`.
* A running Buckle instance. For a local one, run:

```bash theme={null}
docker run --pull always -p 10254:10254 -p 10255:10255 -v buckle-data:/app/data ghcr.io/trybuckle/buckle
```

The dashboard runs on [localhost:10254](http://localhost:10254) and the gateway on port `10255`.

## Steps

**1. Generate the token**

Run:

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

A browser window opens. Sign in to the Claude account that has your plan and approve. The terminal prints a token that starts with `sk-ant-oat`. Copy all of it, on one line. The token is valid for one year, and the command doesn't save it anywhere.

> [!WARNING]
>
> Treat the token like a password. Anyone who has it can use your Claude plan.

**2. Store it in Buckle**

In the dashboard, open your agent's **Agent settings** page (under **More** in the sidebar), click **Add LLM key** in the **Model** block, and choose **Anthropic**. Paste the token into **Secret value** and click **Add Secret**.

Buckle sees the `sk-ant-oat` prefix and injects the token as `Authorization: Bearer {token}`. API keys go in the `x-api-key` header instead. See [Anthropic](/docs/integrations/anthropic.md) for both options.

**3. Remove the token from your shell**

If you exported the token before, remove it so it stays only in Buckle:

```bash theme={null}
unset CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_API_KEY
```

Also delete any matching `export` lines from `~/.zshrc` or `~/.bashrc`.

**4. Run Claude Code through the gateway**

Sign the CLI in with your Buckle API key from the dashboard, then start Claude Code:

```bash theme={null}
buckle auth login --api-key oc_...
buckle run -- claude
```

You'll see `buckle: gateway connected. Starting claude...`. `buckle run` sets the proxy and CA certificate and removes `ANTHROPIC_API_KEY` from the environment. On each request to `api.anthropic.com`, the gateway replaces the `Authorization` header with your stored token. See [Coding agents](/docs/guides/coding-agents.md) for all `buckle run` options.

## Use the token in other agents

Any agent whose traffic goes through the gateway gets the same token on Anthropic requests:

* Containers and custom agents: use the [Node.js SDK](/docs/sdks/node.md) to apply the proxy settings.
* Claude Code without the CLI wrapper: install the [Claude Code plugin](/docs/guides/claude-code-plugin.md).
* Limit which agents can use the secret with [agent access](/docs/guides/agent-access.md) and [rules](/docs/guides/rules.md).

## FAQ

> [accordion] What does claude setup-token do?
>
> It runs the same browser sign-in as `/login` and prints a one-year OAuth token for your Claude subscription. Usage counts against your plan, not API billing.

> [accordion] Why store it in Buckle instead of CLAUDE\_CODE\_OAUTH\_TOKEN?
>
> An environment variable is readable by the agent and by every process it starts. In Buckle, the token stays in the gateway, and you can revoke or rotate it in one place.

> [accordion] What happens when the token expires?
>
> Anthropic rejects requests and the key shows **Key rejected** in the **Model** block of the agent's **Agent settings** page. Run `claude setup-token` again and update the secret with the pencil icon.

> [accordion] Can I use an API key instead?
>
> Yes. Paste a Claude Console key (`sk-ant-api...`) into the same field. Buckle injects it as `x-api-key`. See [Anthropic](/docs/integrations/anthropic.md).

## Next steps

* [How Buckle works](/docs/how-it-works.md)
* [Quickstart](/docs/quickstart.md)
* [LLM providers](/docs/integrations/llms.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.