Skip to content

Installation

Keyosk runs as a single container next to a LiteLLM gateway and an OIDC provider that you already have. This guide sets it up with Docker Compose; podman compose works with the same files.

Before you start

You need:

  • a LiteLLM gateway, v1.105.0 or later, and its master key. Keyosk creates the keys and the LiteLLM users on it.
  • an OIDC client for Keyosk at your identity provider, with the redirect URI https://keyosk.example.org/callback; see OIDC client registration.
  • a reverse proxy that serves Keyosk over HTTPS and forwards to port 8080 of the container.

Compose file

Put two files in a directory of their own. compose.yaml:

services:
  keyosk:
    image: ghcr.io/virtuos/keyosk:main
    restart: unless-stopped
    env_file: keyosk.env
    ports:
      - "127.0.0.1:8080:8080"   # the reverse proxy connects here
    volumes:
      - keyosk-data:/data

volumes:
  keyosk-data:
    name: keyosk-data

keyosk.env, with your values:

# The gateway
LITELLM_BASE_URL=https://litellm.example.org
LITELLM_MASTER_KEY=sk-...

# The identity provider
OIDC_ISSUER_URL=https://login.example.org/realms/example
OIDC_CLIENT_ID=keyosk
OIDC_CLIENT_SECRET=...

# Where people reach Keyosk; https here makes the cookies secure
FRONTEND_URL=https://keyosk.example.org

# Admins: the members of this group at the identity provider
ADMIN_GROUP=keyosk-admin

# Recommended: protect /metrics, and send expiry emails
METRICS_TOKEN=...
SMTP_HOST=mail.example.org:25
SMTP_FROM=noreply@example.org

The first block of seven is required. Everything else has a default; see Configuration for every setting. Keep keyosk.env readable only by you, since it holds the master key and the client secret.

ghcr.io/virtuos/keyosk:main is built from the main branch. Releases are tagged v1.2.3, 1.2 and 1; pin one of those to choose when you update.

Start

docker compose up -d
docker compose logs -f keyosk

On its first start, Keyosk creates its database in the volume, runs the migrations and creates a default profile. The log names anything that is not set up yet, such as a missing first admin, an open /metrics or missing email. GET /readyz answers 200 once it is ready; see Health checks.

The default profile applies to everyone who has no profile of their own, and the one created on the first start has no usage limit. Until an admin gives it one, or makes a limited profile the default, those users can spend without a cap. Set this up before you let users in; the startup log and the top of the admin panel say so for as long as the default is unlimited.

The first admin

With ADMIN_GROUP set, as above, the members of that group are the admins from their first login, and there is nothing else to do. See Administrators for what the identity provider has to send.

Without it, admins are managed in the admin panel, and the first one is marked with a command. The person logs in once, so that Keyosk has their account, and looks up their user ID on the Account settings page, which opens from the account menu. Then mark that account in the running container:

docker compose exec keyosk keyosk -make-admin 1

The command names the account it marked, so a mistyped ID shows. It is safe while Keyosk runs and takes effect on the person's next request. Further admins are then promoted in the panel.

Backups

Everything Keyosk keeps is one SQLite database in the volume. Back it up with keyosk -backup, which writes a consistent copy while Keyosk runs, rather than by copying the database file. The copy goes into the volume, from where it can be copied out:

docker compose exec keyosk keyosk -backup /data/keyosk-backup.db
docker compose cp keyosk:/data/keyosk-backup.db .

The command replaces an older backup in the same file, and only once the new one is complete, so the same two commands can run from cron every night. A tool that already backs up the volume should not copy the live database, which may be caught mid-write: run keyosk -backup before it, and the tool picks up the copy.

The database holds no usable API keys: a key is shown to its user once, and only its SHA-256 hash is stored, which LiteLLM accepts for revoking, updating and reporting on it. It does hold everyone's name, email address and profile.

Updating

docker compose pull
docker compose up -d

Keyosk runs any new migrations when it starts. Take a backup first: a migration cannot be rolled back.

To see which version runs, open About Keyosk in the account menu, or ask the image, which needs no configuration and no running container:

docker run --rm ghcr.io/virtuos/keyosk:main -version

It prints the version, the commit it was built from and the Go version, and Keyosk logs its version and commit at every start.