Reference
Environment variables
Every setting the API, worker and embedders read.
Self-hosted only — on the managed service these are set for you. Organization settings in the interface override the model-related ones.
| Variable | What it does | |
|---|---|---|
API_PORT | Optional | Port to listen on. Defaults to 8080 |
APPD_TLS_CA | Optional | CA certificate that signed appd's certificate, for an https APPD_URL. Unset uses the system roots |
APPD_TLS_CLIENT_CERT | Optional | The API's client certificate, for an appd that requires mutual TLS. Set together with APPD_TLS_CLIENT_KEY |
APPD_TLS_CLIENT_KEY | Optional | Private key for APPD_TLS_CLIENT_CERT |
APPD_TOKEN | Optional | Bearer token shared with appd. 32+ hex characters, openssl rand -hex 32 |
APPD_URL | Optional | The apps node (appd) address, e.g. http://appd:9090. Apps are off unless both APPD_ variables are set |
APPS_SOURCE_DIR | Optional | Where each app release's source is kept, for merge deploys and reading files back. Default: app-sources on the uploads volume when it is mounted |
BASE_URL | Important | Your public address. Agent sign-in breaks if wrong |
CODE_EMBED_BASE_URL | Optional | Endpoint for the code search lane |
CODE_EMBED_MODEL | Optional | Model for the code search lane |
COOKIE_DOMAIN | Optional | Cookie domain, if you need it set explicitly |
COOKIE_SECURE | Important | true when serving over HTTPS |
DATABASE_URL | Required | PostgreSQL connection string |
ENCRYPTION_KEY | Required | Encrypts connector credentials. Exactly 32 bytes, base64 |
JWT_SECRET | Required | Signs sessions. 32+ characters |
LENSHUB_ENV | Optional | production enables stricter startup checks |
LLM_API_KEY | Optional | Key for your provider |
LLM_BASE_URL | Optional | API root. Empty for OpenAI itself |
LLM_CHAT_MODEL | Optional | Chat model name |
LLM_EMBED_BASE_URL | Optional | Embedding endpoint. Keep local to avoid sending content out |
LLM_EMBED_MODEL | Optional | Embedding model. Empty keeps the bundled local one |
LLM_PROVIDER | Optional | openai for anything OpenAI-compatible, or vllm |
METRICS_LISTEN | Optional | Address for the internal Prometheus /metrics listener, e.g. :9464. Unset or empty turns it off. Never publish it |
OPENAI_API_KEY | Optional | Fallback if LLM_API_KEY is unset |
RERANK_DEFAULT | Optional | Rerank without being asked |
RERANK_OVERSAMPLE | Optional | Candidates considered before reranking |
RERANK_URL | Optional | Result reranking service, if you run one |
Worker
The worker reads DATABASE_URL, ENCRYPTION_KEY, the LLM_* group and
EMBEDDING_DIM like the API, plus:
| Variable | Default | What it does |
|---|---|---|
WORKER_CONCURRENCY | 8 in compose (4 without) | Jobs run in parallel |
WORKER_METRICS_LISTEN | :9465 in compose | Internal Prometheus /metrics listener. Empty turns it off |
CODE_EMBED_BASE_URL, CODE_EMBED_MODEL, CODE_EMBEDDING_DIM | bundled embedding-code | The code lane's embedder |
EMBED_CODE_MAX_ATTEMPTS | 3 | Tries a code file gets before it is marked failed and skipped until it changes |
RETENTION_JOBS_DONE_DAYS | 14 | Finished and cancelled jobs are deleted after this many days |
RETENTION_JOBS_FAILED_DAYS | 90 | Failed jobs |
RETENTION_RETRIEVAL_LOGS_DAYS | 365 | Search logs |
RETENTION_TOOL_CALLS_DAYS | 365 | MCP and chat tool-call records |
RETENTION_AGENT_SESSIONS_DAYS | 365 | Agent sessions |
RETENTION_AUDIT_LOG_DAYS | 365 | Audit log |
RETENTION_AUTH_EVENTS_DAYS | 365 | Authentication trail |
RETENTION_APP_UPLOAD_LINKS_DAYS | 7 | Spent and expired app source upload links |
Every RETENTION_* value of 0 keeps that table forever.
Embedding servers
| Variable | Default | What it does |
|---|---|---|
EMBED_BULK_SLICE | one encode batch | Bulk requests are encoded in slices this size, so a search waits for at most one slice |
Apps runtime
appd's settings (APPD_BUILD_NETWORK, APPD_BUILD_ALLOW, APPD_DENY_CIDRS,
APPD_TLS_*, APPD_METRICS_LISTEN, storage and resource limits) are listed
in .env.example and services/appd/apps-node/.env.example.
See Configuration for which ones actually matter and when.