> ## 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.

# Run Copilot API with Docker

> Run Copilot API in a Docker container with a persistent volume for token and request history storage, supporting env-variable auth and multi-account setup.

Running Copilot API in Docker lets you keep the proxy running as a long-lived container without needing Node.js or Bun installed on your host. Tokens and request history are stored in a mounted volume so they survive container restarts. This page covers building the image, running with persistent storage, passing credentials via environment variables, using Docker Compose, and managing multiple accounts.

## Build the image

Clone the [Copilot API repository](https://github.com/nick3/copilot-api) and build the Docker image from source:

```bash theme={null}
git clone https://github.com/nick3/copilot-api.git
cd copilot-api
docker build -t copilot-api .
```

The image uses a multi-stage build to keep the final image small, runs as a non-root user for security, and includes a health check at `http://localhost:4141/`.

## Run with persistent storage

Create a directory on your host to store tokens and request history, then mount it into the container:

```bash theme={null}
mkdir -p ./copilot-data

docker run -p 4141:4141 \
  -v $(pwd)/copilot-data:/root/.local/share/copilot-api \
  copilot-api
```

The container stores two important items in the mounted directory:

* **Authentication tokens** — GitHub and Copilot tokens acquired during the OAuth flow
* **`admin.sqlite`** — Request history database used by the Admin UI at `/admin`

Without the volume mount, both are lost when the container stops.

## Run with a GitHub token

If you already have a GitHub token, pass it directly as an environment variable to skip the interactive OAuth flow:

```bash theme={null}
docker run -p 4141:4141 \
  -e GH_TOKEN=your_github_token_here \
  copilot-api
```

### Additional environment variables

You can combine environment variables to configure authentication and access control:

```bash theme={null}
# Enable remote Admin UI access
docker run -p 4141:4141 \
  -e GH_TOKEN=your_github_token_here \
  -e ADMIN_TOKEN=your_admin_token_here \
  copilot-api

# Enable request authentication (clients must send an API key)
docker run -p 4141:4141 \
  -e GH_TOKEN=your_github_token_here \
  -e COPILOT_API_KEY=your_api_key_here \
  copilot-api
```

| Variable          | Purpose                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| `GH_TOKEN`        | GitHub personal access token — skips interactive OAuth                                                     |
| `ADMIN_TOKEN`     | Required to access the Admin UI and API from non-localhost addresses                                       |
| `COPILOT_API_KEY` | Requires all proxy requests to include this key; use `auth.apiKeys` in `config.json` for multi-key support |

<Note>
  `COPILOT_API_KEY` is a legacy fallback. For new setups, configure `auth.apiKeys` in `config.json` and mount it into the container, or use the Admin API to update the configuration.
</Note>

## Docker Compose

Use Docker Compose for a more reproducible setup:

```yaml theme={null}
version: "3.8"
services:
  copilot-api:
    build: .
    ports:
      - "4141:4141"
    environment:
      - GH_TOKEN=your_github_token_here
      - ADMIN_TOKEN=your_admin_token_here
      - COPILOT_API_KEY=your_api_key_here
    restart: unless-stopped
```

Save this as `docker-compose.yml` in the repository root, then run:

```bash theme={null}
docker compose up -d
```

<Tip>
  Add a volume to the Compose file to persist tokens and request history across deployments:

  ```yaml theme={null}
  services:
    copilot-api:
      # ...
      volumes:
        - ./copilot-data:/root/.local/share/copilot-api
  ```
</Tip>

## Add multiple accounts

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

Add accounts one at a time. Each run opens an interactive OAuth flow:

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

# Repeat to add a second account
docker run -it \
  -v $(pwd)/copilot-data:/root/.local/share/copilot-api \
  copilot-api --auth add
```

List all registered accounts and their quota status:

```bash theme={null}
docker run -it \
  -v $(pwd)/copilot-data:/root/.local/share/copilot-api \
  copilot-api --auth ls -q
```

All account data — tokens and the account registry — is stored in the mounted `copilot-data` directory. When the proxy runs with multiple accounts, premium-model requests use accounts in order and automatically switch when one account's premium quota is exhausted. Free-model requests are distributed round-robin across accounts by default.

## Docker image features

The included `Dockerfile` provides:

* **Multi-stage build** — builder stage installs dependencies and compiles; runner stage copies only production artifacts, keeping the final image small
* **Non-root user** — the container runs as a non-root user to reduce the attack surface
* **Health check** — Docker monitors `http://localhost:4141/` every 30 seconds and marks the container unhealthy after 3 failed attempts
* **Pinned base image** — `oven/bun:1.3.11-alpine` is pinned by version for reproducible builds