Quick start

From an empty machine to the first request returning results takes about ten minutes. No need to understand any concepts beforehand, just follow the steps.

Before you start §

Prepare two things:

A machine with Docker and Docker Compose installed
An API key for an upstream service — Use an API key from any available upstream service, such as OpenAI, Anthropic, Gemini, or DeepSeek.

No database setup is required; the built-in SQLite database is used by default. The management UI is embedded in the same program, so there is no separate frontend to deploy.

1 · Start the service §

Start the service.

git clone --depth 1 --branch v2 \
  https://github.com/tbphp/gpt-load.git
cd gpt-load

cp .env.example .env
docker compose up -d

Confirm the service is running:

curl --fail http://127.0.0.1:3001/health

A successful response confirms that the service is running. By default, it listens only on localhost, so it is not reachable from the public internet. This is intentional; see Security and production for safe remote access.

The first startup generates a management key automatically. Read it with:

docker compose exec gpt-load \
  sh -c 'cat /app/data/auth.key'

Open http://127.0.0.1:3001 and enter this key.

GPT-Load management UI login page, including management key input box and login button — FIG. 1 — LoginEnter management key

Alternative

To supply your own management key, set AUTH_KEY in .env before startup. ENCRYPTION_KEY encrypts upstream credentials and must be backed up with the database; without it, those credentials cannot be decrypted.

3 · Create a Group §

A Group combines an upstream service with its credentials. Open Group → Import channel credentials → Create new Group and first choose a channel:

The new Group page for importing channel credentials shows common channel buttons and other channel entries — FIG. 2 — Select channelChoose the channel when creating a Group

After choosing a channel, paste the API key into the credential field, then add the models this Group should expose:

Completed new Group form, including Group name, example API key, and model table — FIG. 3 — Completed GroupChannel · Credential · Model

The Group is ready after you save it. See Groups and channels for details about each option.

4 · Create an AccessKey §

Groups manage upstream services; AccessKeys define what each application may use. Open AccessKey → Create new, select the Group you just created and the allowed protocols, then save.

Give the generated key to the application. The application does not need to know how many Groups or upstream keys are behind it.

5 · Send the first request §

Replace the key and model name below with your own:

cURL

export GPT_LOAD_KEY= "Your AccessKey" 

curl http://127.0.0.1:3001/v1/chat/completions \
  -H "Authorization: Bearer ${GPT_LOAD_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "model": "Your model name", "messages": [{ "role": "user", "content": "Hello" }]}'

Once you receive a response, the whole path is working. Existing clients usually need only two changes:

Python — OpenAI SDK

client = OpenAI(
    base_url="http://127.0.0.1:3001/v1",    # Change this line 
    api_key= "Your AccessKey" ,           # Change this line 
)

The management UI can generate connection settings for each client, so you do not have to assemble them manually:

One-click access area on the management UI homepage, displaying AccessKeys, client options, and generated configuration parameters — FIG. 4 — One-Click AccessSelect Key and Client, automatically generate parameters

Next steps §

Understand the relationship between Groups and AccessKeys → Core concepts
Connect subscription accounts such as Codex or Claude → Subscription accounts
Configure your own client → Client setup
Prepare for production → Security and production
Coming from 1.4.x → Moving from 1.x; note that 2.0 cannot be upgraded in place.