Skip to content

Configuration

Copy .env.example to .env and fill in the values. The example is preset for the local development stack in dev/, so for that nothing needs filling in:

Variable Required Default Description
LITELLM_BASE_URL yes — Base URL of the LiteLLM proxy. Keyosk manages keys there, and the dashboard shows it, with /v1, as the API base URL, so it must be an address users can reach
LITELLM_MASTER_KEY yes — LiteLLM master key for key management
OIDC_ISSUER_URL yes — OIDC provider issuer URL
OIDC_CLIENT_ID yes — OIDC client ID
OIDC_CLIENT_SECRET yes — OIDC client secret
OIDC_EXTRA_SCOPES no — Space-separated scopes requested on top of openid profile email, e.g. groups for IdPs that send groups only when asked
ADMIN_GROUP no — IdP group whose members are the admins; see Administrators. Unset, admins are managed in the panel
ADMIN_GROUP_CLAIM no groups Dot path to the ID token claim that lists the groups, e.g. realm_access.roles for Keycloak realm roles. Only with ADMIN_GROUP
FRONTEND_URL yes — Public URL of this app, such as https://keyosk.example.org. Keyosk is served at the root of its own host name, so the URL has no path. The OIDC callback is {FRONTEND_URL}/callback, and the URL is the link in expiry emails and the redirect after logout. With https, also behind a proxy that ends TLS, the cookies are Secure and get the __Host- prefix, which no other host under the same domain can set, and responses carry HSTS. It replaces OIDC_REDIRECT_URL, which is no longer read
LITELLM_USER_ID_PREFIX no Only for several Keyosk instances on one gateway; see Several Keyosk instances on one gateway
LITELLM_USER_EMAIL no false Record people's email addresses on their LiteLLM users, so LiteLLM's user search finds them. Only where addresses are unique across everything connected to the gateway; see People in LiteLLM
DB_PATH no ./data.db Path to the SQLite database file. It runs in WAL mode, so -wal and -shm files sit next to it; keep the directory on a local filesystem (not NFS), and back up with keyosk -backup <file> rather than copying the file (see Backups)
LISTEN_ADDR no :8080 Address and port to listen on
TRUSTED_PROXIES no private ranges Comma-separated CIDRs or IPs of reverse proxies whose X-Forwarded-For is believed for the client address in the request log. The default is loopback and the private ranges (127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7); none trusts nobody and always logs the connecting address
SESSION_DURATION no 24h How long a login session lasts
KEY_DURATION_DAYS no 90 Default key validity; profiles may override it
BUDGET_UNIT no $ Unit label for quota amounts; use a word such as credits when model prices are nominal
USAGE_HISTORY_DAYS no 30 How far back the usage chart and per-model table reach; see Usage reporting
SUCCESSOR_URL no Set on a Keyosk instance being retired: the dashboard shows a banner sending users to this address. Keys can no longer be created or extended here, only deleted; existing keys expire on their own
PRIVACY_NOTICE_FILE_DE no — Path to an HTML fragment shown at /privacy (no login needed) as this deployment's privacy notice, and linked from the dashboard. A named file that is missing or empty stops startup
PRIVACY_NOTICE_FILE_EN no — The same in English. With only one language set, readers of the other get that one; with both, visitors who are not signed in can switch between them on the page
SMTP_HOST no — host:port of a mail relay; unset disables expiry emails
SMTP_FROM no noreply@example.com Sender address for expiry emails
SMTP_USERNAME no — Only if the relay requires authentication
SMTP_PASSWORD no — Only if the relay requires authentication
METRICS_TOKEN no — Bearer token /metrics requires. Without it the endpoint is open. See Metrics
LOG_LEVEL no info debug, info, warn or error
LIMIT_SYNC_WORKERS no 1 How many limit updates Keyosk sends to the gateway at once. One is gentle on the gateway but slow for large changes: about 25 minutes for 5,000 keys
LIMIT_SYNC_INTERVAL no 5m How often the limit sync retries keys whose update failed. Admin changes start a run straight away and do not wait for it
KEY_MISSING_GRACE_PERIOD no 24h How long a key the gateway no longer has stays marked as missing before Keyosk removes its record. A key that returns in time is unmarked. See Keys deleted in the gateway

OIDC client registration

Register the application with your OIDC provider:

  • Redirect URI: {FRONTEND_URL}/callback
  • Post-logout redirect URI: {FRONTEND_URL} (optional)
  • Back-channel logout URI: {FRONTEND_URL}/backchannel-logout (optional)
  • Required scopes: openid, email, profile, plus whatever your IdP needs to send groups when ADMIN_GROUP is set (see OIDC_EXTRA_SCOPES)

Only the identity provider calls /backchannel-logout, and it needs no login. Keyosk acts only on a logout token signed by the provider, but each request with a token it cannot verify makes it fetch the provider's signing keys again. If your reverse proxy can, allow /backchannel-logout only from the identity provider's addresses.