Skip to content

Environment Variables

$DEVENV_STATE refers to <project root>/.devenv/state — this is where devenv stores runtime data.

All settings can be overridden in .env. Defaults (where appropriate) are provided in devenv.nix at low priority so .env values take precedence.

file: prefix: Any env var can be prefixed with file: to read the value from a file at runtime (e.g. KLANGK_JWT_SECRET=file:/run/secrets/jwt). The file contents are stripped of leading/trailing whitespace. This works with secret management tools like agenix/sops that write decrypted secrets to files. If the file cannot be read, an error is logged and the value is treated as unset.

Variable Default Description
KLANGK_NGINX_PORT 8995 Primary access point — nginx reverse proxy port (UI, API, WebSocket, hosted apps)
KLANGK_PORT 8997 Backend (FastAPI/uvicorn) port — proxied through nginx, not accessed directly
KLANGK_DATA_DIR $DEVENV_STATE/klangk/data Database, workspaces, Pi sessions
KLANGK_PLUGINS_DIR $DEVENV_STATE/klangk/plugins Fetched plugins (outside repo for execIfModified)
KLANGK_HOST_IMAGE klangk-host Docker image name for run-host-container
KLANGK_IMAGE_NAME klangk-workspace Podman image name for workspace containers
KLANGK_IMAGE_PULL_POLICY never Podman --pull policy for workspace containers (never, missing, always, newer). Default never requires the image to exist locally; missing pulls from a registry if not found
KLANGK_USERNS keep-id:uid=1000,gid=1000 Podman --userns mode for workspace containers. Maps the host user to uid/gid 1000 inside the container so bind-mounted files are owned correctly.
KLANGK_PODMAN_BIN podman Path to the podman binary
KLANGK_PORT_RANGE_START 9000 First host port for workspace app allocations. Each workspace gets 5 ports starting from this value. See Hosted Apps.
KLANGK_ALLOWED_MOUNT_ROOTS Comma-separated list of allowed host path prefixes for bind mounts (e.g., /home,/data). If unset, all bind mount paths are allowed. Protected paths are always blocked.
KLANGK_INSTANCE_ID default Instance identifier for multi-instance deployments on the same host — isolates containers, names, and cleanup
KLANGK_DNS_SERVERS Comma-separated DNS server IPs for containers (e.g., 100.100.100.100,8.8.8.8 for Tailscale MagicDNS). If unset, containers use podman's default DNS.
KLANGK_HOSTING_HOSTNAME (auto-derived) Hostname for hosted app URLs. Auto-derived from X-Forwarded-Host or Host header. Set explicitly in production.
KLANGK_HOSTING_PROTO (auto-derived) Protocol for user-facing app URLs. Auto-derived from X-Forwarded-Proto or defaults to http.
KLANGK_HOSTING_BASE_PATH (auto-derived) Base path prefix for user-facing app URLs (e.g., /klangk). Auto-derived from X-Forwarded-Prefix.
KLANGK_REJECT_PROXY_HEADERS Set to 1 to ignore X-Forwarded-Host/Proto/Prefix headers. Use in hardened deployments where the backend port is exposed directly.
KLANGK_IDLE_TIMEOUT_SECONDS 1800 Container idle timeout in seconds (check interval auto-computed as timeout/3, clamped 10-60s)
KLANGK_LOGIN_LOCKOUT_WINDOW 300 Time window in seconds for counting failed login attempts.
KLANGK_LOGIN_LOCKOUT_FAILURES 0 Number of failed login attempts before a lockout. Default 0 (disabled).
KLANGK_LOGIN_LOCKOUT_DURATION 900 Duration of lockout in seconds (only relevant when KLANGK_LOGIN_LOCKOUT_FAILURES > 0).
KLANGK_LLM_API_KEY LLM provider API key
KLANGK_LLM_BASE_URL LLM API URL — must use IP or public FQDN, not bare hostnames (see Tailscale note)
KLANGK_LLM_MODEL LLM model name
KLANGK_CHAT_AGENT_EMAIL MrBoops@example.com Email for the chat AI agent. Used for seeding — the agent user is created or updated in the DB on each startup.
KLANGK_CHAT_AGENT_HANDLE MrBoops @mention handle for the chat AI agent. Used for seeding — the agent user is created or updated in the DB on each startup.
KLANGK_JWT_SECRET JWT signing secret. A warning is logged at startup if unset or left as the insecure dev default.
KLANGK_PREVENT_INSECURE_JWT_SECRET Set to 1 to fail at startup if KLANGK_JWT_SECRET is unset or insecure. Recommended for production.
KLANGK_WORKSPACE_TOKEN_HOURS 24 Lifetime in hours for per-workspace JWTs injected into containers.
KLANGK_DEFAULT_USER Auto-seeded admin email on startup
KLANGK_DEFAULT_PASSWORD Auto-seeded password on startup (omit to generate random; supports file: prefix)
KLANGK_MIN_PASSWORD_LENGTH 4 Minimum password length
KLANGK_FILE_UPLOAD_SIZE_MAX 524288000 Maximum upload size in bytes for file uploads and workspace imports (default 500 MB)
KLANGK_WS_MSG_SIZE_MAX 16777216 Maximum WebSocket message size in bytes (default 16 MB). Increase if syncing very large files via rsync over WebSocket.
KLANGK_CORS_ORIGINS Comma-separated list of allowed CORS origins (e.g., https://klangk.example.com). If unset, derived from KLANGK_HOSTING_HOSTNAME/KLANGK_HOSTING_PROTO, or defaults to http://localhost:{KLANGK_NGINX_PORT}. Set to * to allow all origins (not recommended for public deployments).
KLANGK_GITHUB_OAUTH_CLIENT_ID GitHub OAuth App client ID for device-flow authentication. Injected into workspace containers by the git-credential plugin. When set, git push to github.com triggers the OAuth device flow automatically. No client secret needed. See GitHub Authentication.
KLANGK_DISABLE_REGISTRATION Set to any non-empty value to block new user signups and hide the registration link in the UI
KLANGK_DISABLE_INVITES Set to 1 to disable the invitation system
KLANGK_INVITE_EXPIRE_HOURS 72 How long invitation links remain valid (hours)
KLANGK_ALLOW_SUDO Set to 1/true/yes to grant passwordless sudo inside workspace containers. Default: disabled — an explicit deny rule (!ALL) is written so sudo is blocked even if a password is set on the klangk user. Configured at container start via podman exec --user root.
KLANGK_DISABLE_TMUX Set to 1/true/yes to drop new terminals straight into a plain login shell instead of tmux. Only affects the default per-user terminal; shared/joined terminals always use tmux.
KLANGK_OIDC_CONFIG Path to OIDC provider config file (YAML or JSON). Enables OIDC authentication when set. See OIDC Configuration.
KLANGK_OIDC_LOGIN_HOOK Dotted Python path to a login hook function (e.g., klangk_backend.oidc.example_admin_hook). Called on each OIDC login to enforce custom policies. See OIDC Configuration.
KLANGK_AUTH_MODES both (if OIDC configured) Auth modes: password, oidc, or both. Defaults to password when no OIDC config.
KLANGK_SMTP_HOST SMTP server hostname (if set, uses SMTP; otherwise uses sendmail)
KLANGK_SMTP_PORT 587 SMTP server port
KLANGK_SMTP_USER SMTP auth username
KLANGK_SMTP_PASSWORD SMTP auth password
KLANGK_SMTP_FROM Email sender address (falls back to SMTP_USER, then noreply@localhost)
KLANGK_SMTP_USE_TLS true Use STARTTLS for SMTP
KLANGK_SENDMAIL_PATH sendmail Path to sendmail binary (used when KLANGK_SMTP_HOST is not set)
KLANGK_LOGIN_BANNER_TITLE Title shown on the consent banner page (e.g., company name). If empty, no title is displayed.
KLANGK_LOGIN_BANNER Consent banner text shown before login. Blocks all access until accepted. Supports file: prefix. If empty, no banner is shown.
KLANGKC_FORWARD_AGENT CLI env var: true/1/yes to always forward, false/0/no to not forward, or space-separated server URLs to forward only to specific servers. The --forward-agent (-A) flag takes highest precedence. See SSH Agent Forwarding.
KLANGKC_DEBUG_SSH_AGENT Set to any non-empty value to enable verbose debug logging for SSH agent forwarding on both the backend and CLI side. Useful for diagnosing relay issues.
KLANGK_WS_DEBUG Set to any non-empty value to enable verbose WebSocket message logging on the backend. Useful for diagnosing connection issues.
LOGFIRE_TOKEN Pydantic Logfire write token (opt-in)
LOGFIRE_BASE_URL https://logfire-api.pydantic.dev Logfire API base URL (for self-hosted instances)
LOGFIRE_ENVIRONMENT Logfire environment tag (e.g., production, staging) — filters traces in the dashboard.