Deployment - GPT-Load

Choose one of the three installation methods. Once you know where the data lives and how to upgrade, you have everything this page needs to cover.

Which one to select §

Docker Compose — Recommended. One command starts the service, and one command upgrades it.
Native binary — when you would rather not install Docker
Windows installer — when you want a service on Windows that starts at boot
Source code build — Use this to modify the code or build for a specific platform.

If unsure, use the first one.

Docker Compose§

① Start 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 it's running

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

③ Obtain the management key

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

Two values may be overwritten inside the container

This is the easiest pitfall to fall into: inside the container, HOST is fixed to 0.0.0.0 and DATA_DIR to /app/data. Changing either in .env has no effect. External reachability is controlled by Compose port publishing, which defaults to the host's 127.0.0.1:3001 only.

Native binary §

Download the build for your platform from GitHub Releases. There are five targets: Linux and macOS each on amd64 and arm64, plus Windows on amd64.

Verify after downloading. The release page includes SHA256SUMS:

Verify and run

 # Verify checksum 
sha256sum -c SHA256SUMS --ignore-missing

chmod +x ./gpt-load-linux-amd64
HOST=127.0.0.1 DATA_DIR=./data ./gpt-load-linux-amd64

Then open http://127.0.0.1:3001. The management key is stored at ./data/auth.key.

On Windows, gpt-load-windows-amd64.exe runs in the foreground, so closing the window stops the service. To keep it running, use the installer below.

Windows installer §

The release page also offers gpt-load-windows-setup.exe, the easier way to install on Windows: double-click, confirm the administrator prompt, and it handles all of this for you:

Registers a Windows service — runs under a low-privilege account and starts at boot
Creates shortcuts — shortcuts to the management page appear on the desktop and in the Start menu
Starts the service — ready to use once installed; no further commands needed

The installer shows the admin key

The admin key generated on first run is shown only once, on the installer screen, so save it before closing the page. If you miss it, you can still find it at %ProgramData%\GPT-Load\data\auth.key.

After installation, two directories are worth knowing:

Configuration directory — %ProgramData%\GPT-Load; the service reads .env from here
Data directory — %ProgramData%\GPT-Load\data; the database and both keys live here

To manage the service by hand, use the subcommands built into the program:

Managing the installed service

"%ProgramFiles%\GPT-Load\gpt-load.exe" service status
"%ProgramFiles%\GPT-Load\gpt-load.exe" service stop
"%ProgramFiles%\GPT-Load\gpt-load.exe" service start
"%ProgramFiles%\GPT-Load\gpt-load.exe" service restart

Upgrading is just a matter of running the new installer over the old one; it gracefully stops the service before updating. Uninstalling removes the program and the service but keeps the data directory — which means your configuration survives a reinstall, and also means you must delete it by hand for a truly clean removal.

Source code build §

Building from source requires Go and Node. The management UI is embedded in the binary, so the frontend is built first:

Build from source.

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

 # Build management UI, artifacts will be embedded in binary 
make build

./gpt-load

Refer to go.mod and web/package.json at the repository root for the required Go and Node versions.

Where the data is stored §

In the default SQLite deployment, all state is stored in DATA_DIR. The logical volume name in the Compose configuration is gpt-load-data, but the actual Docker volume name is derived from the Compose project name and may differ:

gpt-load.db — The database (SQLite by default).
auth.key — generated automatically when AUTH_KEY is not explicitly set
encryption.key — generated automatically when ENCRYPTION_KEY is not explicitly set

Backup together

Back up the encryption key together with the database. When explicitly setting AUTH_KEY or ENCRYPTION_KEY, back them up separately from their original secure source; they are not written to the data volume automatically. See Database and backup.

Set DATABASE_DSN to use MySQL or PostgreSQL; leave it empty to use the built-in SQLite database.

Routine operations §

Common commands

 # Check logs 
docker compose logs -f

 # Stop the service 
docker compose stop

 # Restart 
docker compose restart

Upgrade and rollback §

No need to watch GitHub. The Settings page in the admin console has a System info section: it shows your current version, flags new releases with a link to the release notes, and lets you check for updates manually.

Upgrade to the latest 2.x

docker compose pull
docker compose up -d

Data remains in the named volume during upgrades. Database schema migrations run automatically at startup; no manual action is required.

The official Compose file uses the 2 update channel. Before GA, it tracks verified 2.0 Beta and RC releases; after GA, it tracks stable 2.x releases only. Exact image tags omit the Git tag's v prefix (for example, 2.0.0-beta.25); 2.0-beta is the 2.0 Beta channel, and latest is never used. To pin a version, use an exact image tag or digest.

Database migrations are one-way; a rollback requires more than changing the image tag. Take an offline backup before upgrading. To roll back, restore the pre-upgrade database and matching keys, then start the older version associated with that backup.

After installation, use Quick start to create your first Group, then complete the Security and production checklist before production.