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

# Set Up Coding Agents: Claude Code, Cursor & Codex

> Configure Claude Code, Cursor, Codex, and other coding agents to route through the Buckle gateway. One command to set up.

`buckle run` wraps a coding agent process with Buckle gateway access. Your agent's HTTPS traffic routes through the gateway, which injects stored credentials automatically. The agent never sees raw API keys or OAuth tokens.

## Supported agents

| Agent | Command |
| - | - |
| Claude Code | `buckle run -- claude` |
| Cursor | `buckle run -- cursor` |
| Codex | `buckle run -- codex` |
| Hermes | `buckle run -- hermes` |
| OpenCode | `buckle run -- opencode` |
| OpenClaw | `buckle run -- openclaw gateway run` |

Any command works after `--`. The agents listed above also get an auto-installed skill file that teaches them how to use the gateway.

## Setup

**1. Start Buckle**

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

**2. Install the CLI**

```bash theme={null}
curl -fsSL buckle.dev/cli/install | sh
buckle auth login --api-key oc_...
```

Get your API key from the dashboard at [localhost:10254](http://localhost:10254).

**3. Launch your agent**

```bash theme={null}
buckle run -- claude
```

You'll see `buckle: gateway connected. Starting claude...` and your agent starts with the gateway configured.

## What `buckle run` does

When you run `buckle run -- claude`, the CLI:

1. Fetches gateway configuration from the Buckle server
2. Writes a CA bundle (your system CAs plus the gateway CA) to `~/.buckle/ca-bundle.pem`
3. Installs the Buckle gateway skill into the agent's skill directory (for Claude Code, `~/.claude/skills/buckle-gateway/SKILL.md`), fetched from the server with a built-in fallback
4. Injects `HTTPS_PROXY`, the CA trust variables (`SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, and friends), and `BUCKLE_GATEWAY=true` into the child process
5. Hands over terminal control to the agent

The skill file is refreshed on every launch. Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) pick up the proxy settings automatically.

## Choosing the agent identity

Each `buckle run` session acts as one agent from your project, which decides the credentials the gateway injects and the rules that apply. The identity resolves in this order:

1. `--agent <identifier>` flag
2. `BUCKLE_AGENT` environment variable
3. `buckle config set agent <identifier>` (requires CLI 2.10+)
4. The project's default agent

Pin a machine once and forget it:

```bash theme={null}
buckle config set agent writer-bot
buckle run -- claude                        # runs as writer-bot from now on
buckle run --agent ci-runner -- codex       # one-off override, flag always wins
```

The pin is local to the machine. It doesn't change the workspace's default agent, so your teammates' plain `buckle run` is unaffected.

## How agents connect to services

The skill file teaches supported agents a simple workflow:

1. **Make the request directly.** The agent calls the real API URL (e.g. `https://gmail.googleapis.com/...`). No auth headers needed. If credentials are configured, the gateway injects them and the request succeeds.

2. **If it fails, help the user connect.** The gateway returns a structured error with a `connect_url`, and the agent presents that link to the user.

3. **Poll and retry.** The agent polls the connection status and retries automatically once the user connects the service. No manual "try now" needed.

For OAuth apps (Gmail, GitHub, Google Drive, and 13 others), the user connects with one click in the dashboard. For API key services (Stripe, custom APIs), the user adds a secret via the dashboard or `buckle secrets create`.

## Flags

| Flag | Description |
| - | - |
| `--agent <identifier>` | Run as a specific agent (default: `BUCKLE_AGENT` env, then `buckle config set agent`, then the project's default agent) |
| `--gateway <host:port>` | Override the gateway address (default: derived from API host) |
| `--no-ca` | Skip CA certificate write and trust env injection |
| `--enforce` | OS-enforced governance: route the agent's sandboxed egress through the gateway so it cannot be bypassed (Claude Code only) |
| `--dry-run` | Print the resolved config as JSON without launching the agent |

### Dry run

Use `--dry-run` to inspect what `buckle run` would do without side effects:

```bash theme={null}
buckle run --dry-run -- claude
```

This prints the resolved binary path, injected environment variable keys, and CA cert path as JSON.

> [!TIP]
>
> To run Claude Code on your Claude subscription, store a `claude setup-token` token in Buckle. See [Claude setup-token](/docs/guides/claude-setup-token.md).

## Compared to the SDK path

`buckle run` is for coding agents running directly on your machine. If your agents run in Docker containers (e.g. via [NanoClaw](/docs/guides/nanoclaw.md)), use the [Node.js SDK](/docs/sdks/node.md) instead. Both paths use the same gateway, the same secrets, and the same policy rules.

| | `buckle run` | SDK / Docker |
| - | - | - |
| Agent runs on | Your machine (local process) | Docker container |
| Setup | `buckle run -- claude` | `applyContainerConfig(args)` |
| Skill files | Auto-installed | Not applicable |
| Use case | Development with coding agents | Production orchestration |


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