Settings¶
Kist is configured with environment variables in .env next to
docker-compose.yml; .env.example lists them all with their defaults.
After a change, docker compose up -d recreates the containers that use it.
Settings you change in the web app (theme, density, tile size, the first-run
checklist) are kept per browser, and the rest (tokens, vocabulary, templates,
export presets, share links) live in the library, so they survive a rebuild.
Only KIST_TOKEN is required.
| variable | default | |
|---|---|---|
KIST_TOKEN |
— | Required. The owner's bearer token (scope admin) for the UI, API, and MCP (16+ characters). Narrower named tokens: see Tokens |
KIST_PORT |
8080 |
Host port (a number) |
KIST_BIND |
0.0.0.0 |
Host address the port is published on. 0.0.0.0 is every interface, so the LAN can reach Kist over plain HTTP; set 127.0.0.1 when the TLS reverse proxy runs on the same host. (An old KIST_PORT=127.0.0.1:8080 moves here.) |
KIST_LIBRARY |
./library |
Host path of the asset library |
KIST_DB_PASSWORD |
kist |
Postgres password. Postgres publishes no port, so only the compose network reaches it, but set your own anyway |
KIST_USER_AGENT |
kist/<version> (self-hosted asset manager) |
User-Agent for URL downloads; some sites (e.g. Wikimedia) require contact info in it |
KIST_URL_ALLOW_PRIVATE |
false |
Let "add from URL" fetch private/LAN/loopback addresses. Off by default so a web page can't point Kist at devices on your network |
KIST_URL_ALLOW_HOSTS |
— | Comma list of host names or CIDR ranges allowed anyway, e.g. nas.lan,192.168.1.0/24 |
KIST_DOWNLOAD_TIMEOUT_SECONDS |
120 |
Overall time limit for one URL download |
KIST_PREVIEW_TIMEOUT_SECONDS |
300 |
Time limit for generating one item's previews |
KIST_HSTS_SECONDS |
15552000 |
Strict-Transport-Security max-age (180 days); 0 turns it off |
KIST_PUBLIC_URL |
— | The address you open Kist at (e.g. https://kist.example.com); MCP items then carry absolute web_url links |
KIST_JOB_LEASE_SECONDS |
900 |
A background job running longer than this is treated as abandoned by a stopped worker and queued again |
KIST_MAX_UPLOAD_BYTES |
4294967296 (4 GiB) |
Largest direct upload; bigger ones get 413 |
KIST_MAX_DOWNLOAD_MB |
512 |
Largest "add from URL" download |
KIST_VERIFY_INTERVAL_HOURS |
24 |
How often the worker runs kist verify (0 turns it off); /api/health/deep shows the last result |
KIST_TRASH_RETENTION_DAYS |
30 |
The worker deletes items trashed longer than this for good (never protected ones); 0 keeps the trash forever. The clock starts the first time the worker runs with it on |
KIST_BACKUP_REPO |
— | restic repository kist backup writes to (a path mounted into the worker, or sftp:, rest:, s3:, b2: …) |
RESTIC_PASSWORD / RESTIC_PASSWORD_FILE |
— | The backup repository's password (restic's own variables) |
KIST_BACKUP_INTERVAL_HOURS |
0 |
The worker runs kist backup this often; 0 = only by hand |
KIST_LOG_LEVEL |
INFO |
DEBUG, INFO, WARNING or ERROR |
KIST_GIT_COMMIT |
unknown |
Build argument naming the commit, shown by /api/version: KIST_GIT_COMMIT=$(git rev-parse --short HEAD) docker compose build |
KIST_INBOX_POLL_SECONDS / KIST_WORKER_POLL_SECONDS |
5 / 2 |
How often the worker looks in the inbox and the job queue |
KIST_UID / KIST_GID |
1000 |
User the containers run as; the library folder must be owned by it |
KIST_MEM_LIMIT |
4g |
Memory cap for each of the app and worker containers |
KIST_AI_ENABLED |
true in compose |
Queue embedding/OCR jobs for new items (false outside compose, where there's no ml service) |
KIST_ML_URL |
http://ml:8000 in compose |
The ml service the worker sends AI jobs to. Empty: the worker runs none itself (a kist helper still can) |
KIST_ML_MODEL |
ViT-B-32__openai |
Embedding model, for the ml service, app and worker alike. ViT-B-16-SigLIP2__webli is the opt-in alternative (768-d, ~2.5× slower, 1.5 GB of files) |
KIST_AI_WINDOW |
— | When backfill jobs may run, e.g. 01:00-06:00 (local time of the containers' TZ; may wrap past midnight). Empty: any time. New items' jobs never wait for it |
KIST_AI_CONCURRENCY |
2 |
AI jobs the worker runs at once (on their own threads: imports never wait behind them) |
KIST_AI_EMBED_BATCH |
16 |
Embed jobs one worker thread sends to the ml service in one request (at most 32; 1 sends them one by one) |
KIST_CAPTION_PROVIDER |
— | Captions (off when empty): ollama, or bring your own key for openai, anthropic or gemini. The last three send every image you caption to that company |
KIST_CAPTION_URL |
— | ollama: its address, e.g. http://ollama:11434 (empty: a kist helper --kinds caption on a Mac with Ollama does them). openai: an OpenAI-compatible server's /v1 address instead of api.openai.com (on your own network, e.g. LM Studio or vLLM, images stay at home and Kist doesn't warn) |
KIST_CAPTION_MODEL |
— | e.g. qwen2.5vl:3b (Ollama), gpt-4o-mini, claude-haiku-4-5, gemini-2.5-flash |
KIST_CAPTION_API_KEY |
— | The key for openai, anthropic or gemini |
KIST_CAPTION_AUTO |
false |
Caption every new item automatically (otherwise only on request and by kist ai-backfill --kind caption) |
KIST_CAPTION_PROMPT / KIST_CAPTION_TIMEOUT_SECONDS |
built in / 180 |
The instruction sent with each image; one caption's time limit |
KIST_AI_OCR_PDF_PAGES |
5 |
Scanned PDFs (no text layer): OCR at most this many pages |
KIST_ML_TIMEOUT_SECONDS |
120 |
One ml request's time limit |
KIST_ML_THREADS |
4 |
Inference threads per request in the ml service (4 keeps a 10-core NAS responsive) |
KIST_ML_CONCURRENCY |
1 |
Requests the ml service runs at once (the rest wait) |
KIST_ML_MEM_LIMIT / KIST_ML_CPUS |
4g / 4 |
Memory and CPU caps for the ml container. The "Fine edges" cut-out model needs 8g and isn't offered below that |
KIST_ML_DEVICE |
cpu |
cpu, or openvino-gpu for an Intel GPU (build with KIST_ML_OPENVINO=1 and pass /dev/dri through: see docker-compose.yml) |
KIST_ML_OPENVINO |
0 |
Build argument: 1 builds the ml image with ONNX Runtime's OpenVINO build (+~200 MB) |
KIST_ML_IDLE_SECONDS |
300 |
The ml service unloads a model unused this long (0 = never) |
KIST_ML_BASE_URL |
https://huggingface.co |
Where model files are downloaded from (a mirror works: files are checked by sha256) |
TZ |
UTC |
The worker's time zone, which KIST_AI_WINDOW is in |
KIST_FACES |
0 |
Faces and people, opt-in. Set it for the app, worker and ml service: the worker then queues a faces job per image, and only then does the ml service download (~39 MB) and load the face models. See Organising |
KIST_FACE_MODELS_URL |
— | A mirror for the two face model files (they're checked by sha256 either way) |
KIST_CUTOUTS |
1 |
Subject cut-outs (app, worker and ml service). The ml service downloads the model the first time someone asks for a cut-out (ISNet 179 MB; BiRefNet-lite 224 MB for "Fine edges"); 0 hides the action and refuses the endpoints |
KIST_CUTOUT_MODEL |
— | The model a cut-out uses when the request names none: isnet-general-use (fast, the ml service's default) or birefnet-lite (finer edges, about six times slower) |
KIST_CUTOUT_MAX_SIDE |
4096 |
A cut-out's long side at most this many pixels (the original's size when smaller) |
KIST_CUTOUT_MODELS_URL |
— | ml service: a mirror for the cut-out model files (checked by sha256 either way) |
KIST_COLLECTIONS_INTERVAL_HOURS |
24 |
How often the worker recomputes suggested collections; 0 = only on request (?refresh=1) |
KIST_KINDS |
true |
Kinds (utility collections: Screenshots, Drawings …): sorted locally from embeddings, OCR and file facts. The packs, strictness and sidebar threshold are set in Settings → Kinds and kept in library/.kist/kinds.json; false switches the whole feature off |
KIST_EXPORT_RETENTION_DAYS |
7 |
Finished portable exports (library/exports/) are deleted after this many days; 0 keeps them |
KIST_SNAPSHOTS |
false |
Let POST /api/items/{id}/snapshot with no body fetch the item's page on the server (through the same SSRF guard as URL adds). Off: only snapshots the browser sends |
KIST_LINK_CHECK_DAYS |
0 |
Off by default. Set a number of days to have the link-rot watch re-check every item's source page that often; what it finds is shown in the item's info panel only, never as something that needs attention |
KIST_LINK_CHECK_DELAY_SECONDS |
2 |
Pause between two link checks (and never the same host within 10 s) |
KIST_WAYBACK |
false |
Ask the Wayback Machine (archive.org, an outside service) for an archived copy of sources that are gone. Off by default: it tells archive.org which pages you kept |
KIST_XMP_SIDECARS |
true |
Write items/<id>/original.xmp (rating, keywords, notes, label, creator, rights, provenance) for images on every change, for Lightroom, darktable and digiKam |
KIST_SHARE_PASSWORD_ATTEMPTS |
10 |
Wrong share-link passwords allowed per link per 15 minutes (then 429) |
KIST_PROOF_ACTIONS_PER_IP |
120 |
Guest feedback actions (pick, heart, comment, name) per visitor address per 10 minutes on share links that let guests pick and comment (then 429). Behind a reverse proxy, set uvicorn's FORWARDED_ALLOW_IPS so Kist sees the real address |
KIST_PROOF_ACTIONS_PER_SHARE |
1500 |
Guest feedback actions per share link per 10 minutes, all visitors together (then 429) |
KIST_PRESENT_REMOTE_HOURS |
4 |
Present: how long a phone remote's pairing works (one show; Unpair or a restart ends it sooner) |
KIST_PRESENT_MAX_SLIDES |
500 |
Present: the most slides one show holds |
M4 and M5 options (exports, link checks, video and bundle limits, map tiles)
are listed in .env.example and the
changelog's upgrade notes.
Settings kept in the library¶
The art-team features keep their settings as files in library/.kist/, so
kist rebuild-index keeps them and kist verify checks them:
| file | set in | defaults |
|---|---|---|
kinds.json |
Settings → Kinds | base kinds on, trade packs off; a kind shows in the sidebar from 20 items; Low-res = prints under 5 in on the long edge at 300 dpi (low_res_in, 1,500 px; low_res_px 1,200 applies only without the print check) |
credits.json |
Settings → Sharing | the clearance warning on (clearance_warning) |
colourbooks/<id>.json |
Settings → Colour books | none: Kist ships no colour books |
projects.json |
Projects, the sidebar's Pinned | no projects, no pins |
shows.json |
Present → Save show | no shows |
shares/<id>/feedback.json |
the Share dialog, Feedback | guest feedback off per link; "show everyone's feedback" off |