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

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

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

`onecli run` wraps a coding agent process with OneCLI 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 | `onecli run -- claude`   |
| Cursor      | `onecli run -- cursor`   |
| Codex       | `onecli run -- codex`    |
| Hermes      | `onecli run -- hermes`   |
| OpenCode    | `onecli run -- opencode` |

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

## Setup

<Steps>
  <Step title="Start OneCLI">
    ```bash theme={null}
    docker run --pull always -p 10254:10254 -p 10255:10255 -v onecli-data:/app/data ghcr.io/onecli/onecli
    ```
  </Step>

  <Step title="Install the CLI">
    ```bash theme={null}
    curl -fsSL onecli.sh/cli/install | sh
    onecli auth login --api-key oc_...
    ```

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

  <Step title="Launch your agent">
    ```bash theme={null}
    onecli run -- claude
    ```

    You'll see `onecli: gateway connected. Starting claude...` and your agent starts with the gateway configured.
  </Step>
</Steps>

## What `onecli run` does

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

1. Fetches gateway configuration from the OneCLI server
2. Writes the gateway CA certificate to `~/.onecli/gateway-ca.pem`
3. Fetches your configured secrets and generates a dynamic skill file at `~/.claude/skills/onecli-gateway/SKILL.md` listing your actual services
4. Injects `HTTPS_PROXY`, CA trust variables, `ONECLI_AGENT_NAME`, and `ONECLI_URL` into the child process
5. Hands over terminal control to the agent

The skill file is regenerated on every launch, so it always reflects your current secret configuration. Standard HTTP clients (curl, fetch, requests, axios, Go net/http, git) pick up the proxy settings automatically.

## 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`. The agent appends `&source=agent&agent_name=` (from `$ONECLI_AGENT_NAME`) and presents the 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 `onecli secrets create`.

## Flags

| Flag                    | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `--agent <identifier>`  | Use a specific OneCLI agent identity instead of the default   |
| `--gateway <host:port>` | Override the gateway address (default: derived from API host) |
| `--no-ca`               | Skip CA certificate write and trust env injection             |
| `--dry-run`             | Print the resolved config as JSON without launching the agent |

### Dry run

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

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

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

## Compared to the SDK path

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

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