> ## Documentation Index
> Fetch the complete documentation index at: https://copilot-api.nick3.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage multiple Copilot accounts

> Add multiple GitHub Copilot accounts to increase combined quota and enable failover. Control request distribution with round-robin or session affinity routing.

Copilot API supports multiple GitHub accounts simultaneously. Adding more than one account raises your combined request quota and gives the proxy a failover path when one account's premium budget is exhausted.

## Why use multiple accounts

* **Higher combined quota**: Premium model limits are per-account. With two accounts, you effectively double available premium requests before throttling kicks in.
* **Automatic failover**: If one account runs out of premium quota mid-session, the proxy switches to the next account automatically without interrupting your workflow.
* **Load distribution**: Free-model requests can be spread across accounts using round-robin or affinity routing.

## Adding accounts

<Steps>
  <Step title="Add the first account">
    Run the `auth` command (or `auth add`) and follow the GitHub device code flow in your browser:

    ```bash theme={null}
    npx @nick3/copilot-api@latest auth add
    ```

    For a business or enterprise plan, pass the `--account-type` flag:

    ```bash theme={null}
    npx @nick3/copilot-api@latest auth add --account-type business
    npx @nick3/copilot-api@latest auth add --account-type enterprise
    ```
  </Step>

  <Step title="Add additional accounts">
    Run `auth add` again for each additional account. Each run opens a new device code flow so you can log in with a different GitHub account:

    ```bash theme={null}
    npx @nick3/copilot-api@latest auth add
    ```

    Repeat as many times as needed. All accounts are stored in the data directory.
  </Step>

  <Step title="Verify the accounts">
    List registered accounts to confirm they were added:

    ```bash theme={null}
    # List accounts
    npx @nick3/copilot-api@latest auth ls

    # List with quota information (makes an API call per account)
    npx @nick3/copilot-api@latest auth ls -q
    ```
  </Step>
</Steps>

### Adding accounts in Docker

The Docker image runs the `start` command by default. To run auth subcommands inside the container, prefix them with `--auth`:

```bash theme={null}
# Add an account
docker run -it -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api --auth add

# List accounts with quota
docker run -it -v $(pwd)/copilot-data:/root/.local/share/copilot-api copilot-api --auth ls -q
```

## Removing accounts

Use `auth rm` with either the account ID (GitHub username) or its 1-based index as shown by `auth ls`:

```bash theme={null}
# Remove by index (1-based)
npx @nick3/copilot-api@latest auth rm 2

# Remove by GitHub username
npx @nick3/copilot-api@latest auth rm octocat

# Skip the confirmation prompt
npx @nick3/copilot-api@latest auth rm 2 --force
```

## How request routing works

### Premium models

Requests to premium models are tried against accounts in the order they were added. When an account's quota is exhausted, the proxy automatically switches to the next account in the list. This continues until either a request succeeds or all accounts are exhausted.

### Free models

By default (`accountAffinity: true`), free-model requests from the same session are routed to the last account that handled them successfully. This keeps session context consistent.

When `accountAffinity` is set to `false` in `config.json`, free-model requests are distributed round-robin across all accounts.

### Session affinity

With `accountAffinity: true` (the default), the proxy binds a session-and-model pair to the account that last responded successfully. Subsequent requests from the same session for the same model go to that account unless it fails, at which point the proxy picks the next available account and updates the binding.

You can control how long affinity bindings are retained with `sessionAffinityRetentionDays` (default: `7`):

```json theme={null}
{
  "accountAffinity": true,
  "sessionAffinityRetentionDays": 14
}
```

## Viewing per-account usage

The `/usage` endpoint returns a snapshot of all loaded accounts. The `/usage/:accountIndex` endpoint returns detailed quota information for a specific account (index is **0-based**):

```bash theme={null}
# All accounts
curl "http://localhost:4141/usage"

# Detailed usage for account index 0
curl "http://localhost:4141/usage/0"
```

<Note>
  If you start the server with `--github-token`, a temporary account is included as index `0` in `/usage` (displayed as `"(temporary)"`). In that case, your registered accounts start at index `1`. The `auth rm` command, by contrast, uses **1-based** indexing as shown by `auth ls`.
</Note>

### Example `/usage` response

```json theme={null}
[
  {
    "id": "octocat",
    "remainingQuota": 250,
    "unlimited": false
  },
  {
    "id": "github-user-2",
    "remainingQuota": 300,
    "unlimited": false
  }
]
```

<Tip>
  If API key authentication is enabled, include your key when calling usage endpoints: `Authorization: Bearer <key>` or `x-api-key: <key>`.
</Tip>