Skip to main content
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

1

Add the first account

Run the auth command (or auth add) and follow the GitHub device code flow in your browser:
npx @nick3/copilot-api@latest auth add
For a business or enterprise plan, pass the --account-type flag:
npx @nick3/copilot-api@latest auth add --account-type business
npx @nick3/copilot-api@latest auth add --account-type enterprise
2

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:
npx @nick3/copilot-api@latest auth add
Repeat as many times as needed. All accounts are stored in the data directory.
3

Verify the accounts

List registered accounts to confirm they were added:
# 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

​
Adding accounts in Docker

The Docker image runs the start command by default. To run auth subcommands inside the container, prefix them with --auth: 
# 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: 
# 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): 
{
  "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): 
# All accounts
curl "http://localhost:4141/usage"

# Detailed usage for account index 0
curl "http://localhost:4141/usage/0"
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.

​
Example /usage response

[
  {
    "id": "octocat",
    "remainingQuota": 250,
    "unlimited": false
  },
  {
    "id": "github-user-2",
    "remainingQuota": 300,
    "unlimited": false
  }
]
If API key authentication is enabled, include your key when calling usage endpoints: Authorization: Bearer <key> or x-api-key: <key>.