# 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](<https://virtuos.github.io/keyosk/configuration/#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`:

```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:

```sh
# 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](<https://virtuos.github.io/keyosk/configuration/index.md>) 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

```sh
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](<https://virtuos.github.io/keyosk/monitoring/#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](<https://virtuos.github.io/keyosk/administrators/index.md>) 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:

```sh
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:

```sh
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

```sh
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:

```sh
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.