Skip to content

Configuration

All configuration is environment variables, read by app/config.py (and from a .env file, when there is one). .env.example lists every setting with a comment and is the place to start a deployment’s .env from (see DEPLOYMENT.md).

Bad configuration is reported, never refused: the app always starts. A numeric setting below what it accepts (negative, or 0 where 0 is not listed as “disables”) is replaced by its default with a warning, so a typo never switches a guard off. An unsafe combination is logged at ERROR on every start, with a SECURITY: or CONFIG: prefix.

Variable Default Description
STORE_DIR ./data/store Root directory for the JSON file store (flows, compiled flows, versions)
VERSION_HISTORY_ENABLED true Snapshot the previous state on every save (restorable); false disables history
HISTORY_MAX_VERSIONS 100 Max snapshots kept per flow (oldest pruned); ignored when history off. At least 1; to keep none, set VERSION_HISTORY_ENABLED=false
APP_HOST 0.0.0.0 Bind host
ALLOWED_HOSTS (unset) Host names the editor and API answer to, comma-separated (the Host check ignores ports); * = any. Unset: any host behind a login (or TRUSTED_USER_HEADER), but an open editor only answers to localhost / 127.0.0.1 / [::1] and the BASE_WEBHOOK_URL host; others get 400 (the DNS-rebinding guard). Webhooks and /health are exempt. Listed names also count as this app’s own origin for the cross-site checks (a proxy that rewrites Host), and there the port counts: ivr.example.com is the page on the standard port (https://ivr.example.com), ivr.example.com:8443 the page on 8443
APP_PORT 5001 Bind port
BASE_WEBHOOK_URL http://127.0.0.1:5001 Public URL for Jambonz actionHook callbacks (the 127.0.0.1 default works only when Jambonz runs on the same host). Left at loopback while APP_HOST listens on the network, every start logs a CONFIG: error: calls would die at their first menu
DEBUG false Dev conveniences: auto-reload + live browser refresh (set true for local dev)
LOG_FORMAT text text (human-readable) or json (structured, for aggregation); anything else warns and uses text
LOG_LEVEL INFO Root log level (DEBUG, INFO, WARNING, ERROR, CRITICAL); a typo warns and uses INFO
WEBHOOK_SECRET (unset) The account’s webhook signing secret (from the Jambonz portal); when set, every webhook’s Jambonz-Signature is verified. Comma-separate multiple secrets (multi-account / rotation)
WEBHOOK_BASIC_AUTH_USER / WEBHOOK_BASIC_AUTH_PASSWORD (unset) Require basic auth on webhook routes only (both required): the same credentials configured on the application’s webhooks in Jambonz. Not on the OPTIONS env-var schema request: Jambonz sends that one without credentials, so the schema (names, types, descriptions, non-obscure defaults) is public
AUTH_ADMIN_USER / AUTH_ADMIN_PASSWORD (unset) Editor login with full access (both required; setting them is what enables UI/API auth)
AUTH_READONLY_USER / AUTH_READONLY_PASSWORD (unset) Optional second account that may view everything but change nothing (both required)
SESSION_IDLE_TIMEOUT 3600 Seconds a sign-in survives without a request. Working in the editor keeps it alive; an attached Debug feed closes when it ends. Must be positive
SESSION_MAX_LIFETIME 43200 The most a sign-in can last, in seconds (12 h), however busy. Counted from sign-in, never extended. 0 disables. Signing out also revokes the session server-side, so an earlier copy of the cookie stops working; that list is per process and forgotten on restart, where this and the idle timeout bound what is left
SESSION_COOKIE_SECURE (follows BASE_WEBHOOK_URL) Mark the sign-in cookie Secure (HTTPS only). Unset: on when BASE_WEBHOOK_URL is https://. Set false if the editor is reached over plain http while Jambonz uses an https URL
LOGIN_MAX_ATTEMPTS / LOGIN_LOCKOUT_SECONDS 5 / 900 Failed sign-ins one client address may make within the lockout window before it is refused for that long (429). Per address, not per account; 0 attempts disables
LOGIN_GLOBAL_MAX_ATTEMPTS 20 Failed sign-ins from all browsers that have never signed in here, together, within the lockout window: what guessing spread over many addresses runs into. Reaching it pauses sign-in for those browsers only; one that has signed in before keeps working. 0 disables
TRUSTED_USER_HEADER (unset) Delegate auth to a gateway: trust this identity header (e.g. X-Forwarded-User) on UI/API. Takes precedence over the login accounts
TRUSTED_USER_HEADER_SECRET (unset) Have the gateway also send X-Trusted-Proxy-Secret: <this value>; the identity header is then honoured only alongside it (constant-time compare), and the secret is stripped before the app or a flow sees it. Unset, anyone who can reach the port can claim any identity; startup warns
HTTP_REQUEST_TIMEOUT 10.0 Total deadline (s) for one http_request node call: DNS, connect, TLS and the whole body together, so an upstream that trickles bytes can’t hold a call past it. Never later than the end of the hook’s MAX_HOOK_SECONDS budget
HTTP_REQUEST_MAX_BYTES 1048576 Max response body the http_request node will read; over it the node fails with {{http_error}}. 0 = unlimited
HTTP_REQUEST_ALLOW_PRIVATE true Allow http_request to reach private/loopback IPs. Set false to turn the SSRF guard on (blocks every address that is not globally routable: private, loopback, link-local, reserved, shared 100.64.0.0/10, incl. cloud metadata)
COMPILED_CACHE_TTL 30.0 Per-process TTL (s) for the webhook path’s caches (the compiled flow and the name→id lookup); 0 disables
MAX_REQUEST_BYTES 1048576 Max request body size; larger requests get 413. 0 disables
MAX_CALL_STATE_BYTES 65536 Max size (bytes of JSON) of the variables a call carries between hooks. Jambonz echoes them back on every hook, so state near MAX_REQUEST_BYTES would make the next hook a 413 and drop the call; over this cap the flow’s Error handler runs instead, and the largest variables are logged by name and size. 0 disables
MAX_HOOK_SECONDS 8.0 Wall-clock budget for one webhook, Error handler (and the call-status hook’s Disconnect handler) included, under Jambonz’s ~10 s wait for an answer. HTTP requests are clamped to what is left of it; over it the hook routes to the flow’s Error handler, which runs on the remainder. 0 disables (and lifts the clamp). Above ~9 it buys nothing
WEBHOOK_MAX_CONCURRENCY 100 Webhooks executing at once (each holds a worker thread). Beyond it a hook is shed immediately rather than queued. A slot mostly waits on an HTTP Request’s API; size it with scripts/load_test.py (OPERATIONS.md)
CALLER_UNAVAILABLE_MESSAGE Sorry, this service is unavailable. Please try again later. Spoken (then a hangup) when the app can’t serve a call: an unknown flow, one that won’t load, a missing subflow. The log names the reason; the caller never hears it. Empty = hang up without a word
CALLER_BUSY_MESSAGE Sorry, the system is busy. Please try again shortly. Spoken (then a hangup) when a caller-facing hook is shed under load. Empty = hang up without a word
CALL_TRACE_ENABLED true Whether the editor’s Debug pane may attach to live calls. Not the on switch: tracing runs only while a pane is attached (its Start button), and nothing is ever stored; false refuses every trace socket
RATE_LIMIT_PER_MINUTE 600 Per-IP req/min on UI+API (webhooks + /health exempt); 0 disables
FORWARDED_ALLOW_IPS 127.0.0.1 Read by uvicorn: which proxy addresses (or CIDR ranges) may set X-Forwarded-For / X-Forwarded-Proto. Set to the proxy’s address behind a reverse proxy, or every caller shares one rate-limit bucket and one failed sign-in count. Avoid *: it believes the left-most X-Forwarded-For entry, which a client writes itself unless the proxy overwrites the header (see OPERATIONS.md)
UVICORN_WORKERS 1 Worker processes (container entrypoint only)

The monitoring stack and the container have settings of their own: COMPOSE_PROFILES, LOG_RETENTION, GRAFANA_ADMIN_PASSWORD, APP_PUBLISH and others. They are in .env.example, and explained where they are used: DEPLOYMENT.md and OPERATIONS.md.