Chat environment variables

Chat reads its configuration from the environment at startup. npm run start:api loads .env first; the binary itself does not. .env.example in the repository lists the common ones with comments.

Variable	Default	Meaning
`OBLETH_CHAT_DATABASE_URL`	required	Postgres URL for a database Chat owns
`OBLETH_CHAT_ORIGIN`	`http://localhost:8085`	The exact URL people open. Must be HTTPS unless it's loopback
`OBLETH_CHAT_LISTEN`	`127.0.0.1:8085`	Address and port to listen on
`OBLETH_CHAT_STATIC_DIR`	`web`	Directory of the web app. The image sets `/app/web`
`OBLETH_CHAT_DB_CONNECTIONS`	`20`	Postgres connections per replica, 2 to 200
`OBLETH_CHAT_MAX_STREAMS`	`128`	Concurrent responses per replica, 1 to 4096
`OBLETH_CHAT_SESSION_HOURS`	`12`	Session lifetime
`OBLETH_CHAT_LOGIN_RATE_PER_MINUTE`	`300`	Sign-in requests per client address per minute, 1 to 10000
`OBLETH_CHAT_TRUSTED_PROXY`	unset	Proxy addresses or CIDRs whose `X-Forwarded-For` is trusted; `loopback` for the same host. See Reverse proxies
`OBLETH_CHAT_BOOTSTRAP_USERNAME`	unset	First administrator, created only when there are no users. Set with the password, or neither; Compose and `.env.example` use `admin`
`OBLETH_CHAT_BOOTSTRAP_PASSWORD`	unset	Its password, at least 12 characters. Remove after setup
`OBLETH_CHAT_GATEWAY_URL`	unset	Gateway origin, without `/v1`. Set with the signing key, or neither
`OBLETH_CHAT_GATEWAY_SIGNING_KEY_FILE`	unset	RSA private key Chat signs gateway tokens with
`OBLETH_CHAT_GATEWAY_ISSUER`	`OBLETH_CHAT_ORIGIN`	`iss` of gateway tokens
`OBLETH_CHAT_GATEWAY_AUDIENCE`	`obleth`	`aud` of gateway tokens
`OBLETH_CHAT_ADMIN_GATEWAY_URL`	unset	Gateway dashboard link shown to administrators
`OBLETH_CHAT_OIDC_ISSUER`	unset	OIDC issuer URL. Set with client ID and secret, or none
`OBLETH_CHAT_OIDC_CLIENT_ID`	unset	OIDC client ID
`OBLETH_CHAT_OIDC_CLIENT_SECRET`	unset	OIDC client secret
`OBLETH_CHAT_OIDC_ALLOW_SIGNUP`	`false`	Create accounts on first OIDC sign-in
`OBLETH_CHAT_OIDC_GROUP_CLAIM`	`groups`	ID-token claim to map groups from
`OBLETH_CHAT_OIDC_GROUP_MAP`	unset	JSON map of claim values to arrays of Chat group UUIDs
`OBLETH_CHAT_DEFAULT_GROUP_IDS`	unset	Comma-separated group UUIDs for every new account
`OBLETH_CHAT_S3_ENDPOINT`	unset	Turns on Knowledge and the Library, and keeps attachments and generated images in the bucket. S3-compatible endpoint
`OBLETH_CHAT_S3_BUCKET`	unset	Bucket for Knowledge documents, attachments and generated images
`OBLETH_CHAT_S3_ACCESS_KEY_ID`	unset	Bucket access key
`OBLETH_CHAT_S3_SECRET_ACCESS_KEY`	unset	Bucket secret key
`OBLETH_CHAT_S3_REGION`	`auto`	Signing region
`OBLETH_CHAT_EMBEDDING_MODEL`	`qwen3-embedding-8b`	Default gateway embedding model for Knowledge; administrators can change it in Settings
`OBLETH_CHAT_EMBEDDING_QUERY_PREFIX`	Qwen3-Embedding's instruction	Text put before each search. Empty for none
`OBLETH_CHAT_EMBEDDING_DOCUMENT_PREFIX`	empty	Text put before each stored passage
`OBLETH_CHAT_KNOWLEDGE_USER_MB`	`2048`	Knowledge storage per person, in MiB
`OBLETH_CHAT_PDFTOTEXT`	`pdftotext`	Path to `pdftotext`
`OBLETH_CHAT_UNZIP`	`unzip`	Path to `unzip`
`OBLETH_CHAT_WORKSPACES`	`auto`	`off` turns workspaces and the browser off. With `auto`, they're on when Chat runs in Kubernetes with a service account token
`OBLETH_CHAT_SANDBOX_NAMESPACE`	Chat's namespace	Namespace for workspace and browser pods
`OBLETH_CHAT_SANDBOX_IMAGE`	this release's `workspace` image	Workspace image; pin it by digest in production
`OBLETH_CHAT_SANDBOX_SLOTS`	`8`	Most workspace and browser pods running at once
`OBLETH_CHAT_PREVIEW_DOMAIN`	unset	Wildcard domain for workspace previews; unset, workspaces run without previews
`OBLETH_CHAT_SANDBOX_ACCESS`	`admins`	Who gets workspaces: `admins` or `everyone`
`OBLETH_CHAT_SANDBOX_RUNTIME_CLASS`	unset	RuntimeClass for workspace pods
`OBLETH_CHAT_SANDBOX_STORAGE_CLASS`	cluster default	StorageClass for workspace volumes
`OBLETH_CHAT_SANDBOX_STORAGE`	`10Gi`	Workspace volume size and disk cap
`OBLETH_CHAT_SANDBOX_CPU`	`2`	Workspace CPU limit
`OBLETH_CHAT_SANDBOX_MEMORY`	`4Gi`	Workspace memory limit
`OBLETH_CHAT_SANDBOX_IDLE_MINUTES`	`60`	Stop idle workspace pods after this long
`OBLETH_CHAT_SANDBOX_RETENTION_MINUTES`	`10080`	Delete a workspace volume this long after last use
`OBLETH_CHAT_BROWSER`	`on`	`off` leaves out the browser
`OBLETH_CHAT_BROWSER_IMAGE`	this release's `browser` image	Browser image; pin it by digest in production
`OBLETH_CHAT_BROWSER_CPU`	`1`	Browser CPU limit
`OBLETH_CHAT_BROWSER_MEMORY`	`1Gi`	Browser memory limit
`OBLETH_CHAT_BROWSER_STORAGE`	`1Gi`	Browser profile volume size
`OBLETH_CHAT_BROWSER_IDLE_MINUTES`	`15`	Stop idle browsers after this long
`OBLETH_CHAT_KUBE_API`	in-cluster	Kubernetes API URL, for running Chat outside the cluster
`OBLETH_CHAT_KUBE_TOKEN_FILE`	ServiceAccount token	Token for that API
`OBLETH_CHAT_KUBE_CA_FILE`	ServiceAccount CA	CA for that API
`OBLETH_CHAT_CONNECTIONS`	`all`	Which connections people can add: `all`, `mcp` (no clusters) or `off`. See Enable connections
`OBLETH_CHAT_AUTO_MODE`	`allowed`	Whether a chat may switch to Auto mode, where tools run without asking: `allowed` or `off`
`OBLETH_CHAT_CONNECTIONS_ALLOW_PRIVATE`	`false`	Let people's own connections reach private addresses. Development only
`OBLETH_CHAT_BACKUP_STATUS_DIR`	unset	Directory with `lastSuccess` and `bytes` files for backup metrics
`OBLETH_CHAT_METRICS_TOKEN`	unset	Bearer token `/metrics` requires; unset, `/metrics` is open
`RUST_LOG`	unset	Log filter, such as `obleth_chat=info`

PreviousOperate Chat

NextProduction checklist