Docker

The Docker image runs watch mode by default and exposes an HTTP API for supplying credentials and unlocking the encrypted store — no terminal required.

Quick start

docker run -p 9876:9876 -v keyledger-data:/data ghcr.io/riptideslabs/keyledger:latest

Item	Value
Default command	keyledger watch --unseal-addr 0.0.0.0:9876 --interval 5m
Data volume	/data (SQLite database + snapshots)
Unseal API port	9876
Data env var	KEYLEDGER_HOME=/data

Supplying credentials

On first run, the store is not yet initialised. Use the unseal API to set up encryption and push credentials:

# 1. Check status
curl -sk https://localhost:9876/v1/status
# {"sealed":true,"setup":false}

# 2a. First run — initialise and unseal
curl -sk -X POST https://localhost:9876/v1/init \
  -H 'Content-Type: application/json' \
  -d '{"password":"my-secret"}'

# 2b. Subsequent restarts — store already initialised, just unseal
curl -sk -X POST https://localhost:9876/v1/unseal \
  -H 'Content-Type: application/json' \
  -d '{"password":"my-secret"}'

# 3. Discover expected field names
curl -sk https://localhost:9876/v1/providers

# 4. Push credentials
curl -sk -X POST https://localhost:9876/v1/credentials \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openai","field":"admin_key","value":"sk-admin-..."}'

curl -sk -X POST https://localhost:9876/v1/credentials \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","field":"admin_key","value":"sk-ant-admin01-..."}'

Tip

-sk skips certificate verification for the ephemeral self-signed certificate. For stricter usage, extract the SHA-256 fingerprint printed at startup:

watch: TLS cert fingerprint (SHA-256): AB:CD:EF:12:34:56:…

Then pass it to curl: --pinnedpubkey 'sha256//BASE64=='

Docker Compose

services:
  keyledger:
    image: ghcr.io/riptideslabs/keyledger:latest
    ports:
      - "127.0.0.1:9876:9876"
    volumes:
      - keyledger-data:/data
    restart: unless-stopped

volumes:
  keyledger-data:

Build from source

docker build -t keyledger .
docker run -p 9876:9876 -v keyledger-data:/data keyledger

Custom interval or output directory

docker run \
  -p 9876:9876 \
  -v keyledger-data:/data \
  -v /var/log/keyledger:/snapshots \
  ghcr.io/riptideslabs/keyledger:latest \
  keyledger watch \
    --unseal-addr 0.0.0.0:9876 \
    --interval 1h \
    --output /snapshots

Removing a credential

curl -sk -X DELETE https://localhost:9876/v1/credentials \
  -H 'Content-Type: application/json' \
  -d '{"provider":"openai","field":"admin_key"}'