Form K-00 · Installation

Install

One container, one volume, one port. All data lives in a single SQLite file.

Docker (recommended)

docker run -d --name keeyo \
  -p 5390:5390 \
  -v keeyo-data:/data \
  --restart unless-stopped \
  ghcr.io/ans-ib/keeyo:latest

Docker Compose

services:
  keeyo:
    image: ghcr.io/ans-ib/keeyo:latest
    container_name: keeyo
    restart: unless-stopped
    ports:
      - "5390:5390"
    volumes:
      - keeyo-data:/data

volumes:
  keeyo-data:

Then open http://localhost:5390. Your first visit creates the admin account — there is no default password and no open registration.

Build from source

git clone https://github.com/ans-ib/keeyo.git && cd keeyo
docker compose up -d

Without Docker

Needs Node.js 22.13+ — Keeyo uses Node's built-in SQLite, so there are no native modules to compile.

git clone https://github.com/ans-ib/keeyo.git && cd keeyo
npm install
npm start          # http://localhost:5390, data in ./data

Configuration

Single sign-on (Authentik, Authelia, Keycloak, …)

Keeyo speaks standard OpenID Connect (authorization code flow with PKCE), so any self-hosted identity provider works. The easiest way is the admin panel: Settings → Single sign-on covers everything — provider name, client credentials, issuer (endpoints are auto-discovered; manual Auth/Token URL overrides exist for providers without discovery), scopes, the identifier claim, a logout URL, plus toggles for auto-creating users, requiring a verified email, and disabling password login (admins always keep password sign-in as the lockout hatch). Environment variables do the same headlessly and, when set, lock the panel. For Authentik:

1. Create an OAuth2/OpenID provider (confidential client, authorization code flow) with redirect URI https://keys.example.com/api/oidc/callback, and an application using it.
2. Set the environment variables: KEEYO_OIDC_ISSUER to the provider's OpenID issuer URL (e.g. https://auth.example.com/application/o/keeyo/), plus KEEYO_OIDC_CLIENT_ID, KEEYO_OIDC_CLIENT_SECRET, and KEEYO_OIDC_NAME=Authentik.
3. Restart Keeyo — a Continue with Authentik button appears on the sign-in page.

SSO users are matched by username (preferred_username, falling back to the email's local part) and created automatically on first sign-in as regular users — admins are only ever appointed locally. SSO accounts have no Keeyo password, and Keeyo's own second factor is skipped for them: your identity provider owns their authentication, including MFA. Password sign-in keeps working alongside SSO for local accounts.

Email & password reset

Configure SMTP in Settings → Email (or via the KEEYO_SMTP_* variables, which lock the panel) and a Forgot password? link appears on the sign-in page. Users set their address under Settings → Account; reset links are single-use, expire after 45 minutes, and revoke every session of the account when used. Accounts created by SSO have no password and are excluded. The SMTP client is built in — no relay container needed — and speaks TLS, STARTTLS or plain.

Reverse proxy & HTTPS

Keeyo speaks plain HTTP; put your reverse proxy in front for TLS and set TRUST_PROXY=1. Caddy example:

keys.example.com {
    reverse_proxy keeyo:5390
}

Backups

• Everything: back up the /data volume — the SQLite file is the complete state, file attachments included.
• Portable: Settings → Account → Export data gives a JSON file with keys, services, registrations, catalog and secret notes (in plain text — guard it). Attachments are not in the JSON.
• Human-readable: CSV export and a printable register sheet exist for paper people.

Locked out?

On the server (or in the container):

docker exec -it keeyo node scripts/reset-password.js <username> <new-password>

This resets the password, signs out all sessions and removes every second factor on the account — sign-in security keys, the authenticator app, and recovery codes. Alternatively, start Keeyo once with KEEYO_DISABLE_MFA=1 to skip the second factor.