Configuration reference
This reference was built from the code. It lists the environment variables an operator sets on the FACE backend, the platform libraries it links, and the frontend. It leaves out variables read only by build tooling, benchmarks and tests, variables read only by the separate voice calling-agent image, and internal tuning knobs whose defaults are meant to stay as shipped.
In a cluster, set control-plane values through the ControlPlane resource’s env list,
never on the live Deployment, and runner values in the face-runner manifest (see
Deployment model).
Locally, export them into the backend’s environment before you start it.
Secret in the Source column means the value is resolved through the platform secret
backend (SECRET_BACKEND), so it can come from a mounted file instead of the environment.
Everything else is read from the environment.
Required at boot
| Variable | Source | Purpose |
|---|---|---|
AUTH_JWT_SECRET | secret | Signs the pre-TOTP MFA challenge. The process refuses to start without it. |
MESH_CA_CERT | secret | The shared cluster CA certificate. Each pod issues its own rotating mTLS leaves from it. |
MESH_CA_KEY | secret | The shared cluster CA private key. |
TIDE_ENVELOPE_KEK | secret | A base64-encoded 32-byte key-encryption key for everything sealed at rest. |
INFERENCE_REMOTE_URL | env | The base URL of the shared inference plane. No other name is read for it. |
Prerequisites and ordering has the exact refusal messages.
Process, role and platform
| Variable | Default | Purpose |
|---|---|---|
SERVICE_ROLE | control plane | runner makes this process a fetch runner. Any other value makes it a control plane. The operator sets server or runner. |
PORT | none | The default for serve --port. The image entrypoint uses 7000 when PORT is unset. The operator sets 7100 (control plane) or 7102 (runner). |
APP_VERSION | empty | The version stamped on structured logs. |
SECRET_BACKEND | env | env or file. With file, secrets are read from SECRETS_DIR with the environment as fallback. Any other value makes every secret lookup fail. |
SECRETS_DIR | /var/run/secrets | The directory for the file backend. A file is named after the variable, or in lower case with dashes. |
RUNINK_VARIANT | standard | The declared variant, reported to the FACE app. It changes no data and no behaviour on any variant: FACE creates no connections and serves no rows of its own. |
FACE_LOCAL_INSTANCE | false | true offers a single local-development instance in the instance picker, on a process with no in-cluster ServiceAccount token only. In a cluster it changes nothing. |
RUNINK_APP | face | The app name that filters ClientInstances in the instance picker. |
FACE_CLIENT_INSTANCE | none | The name of this deployment’s own ClientInstance, used by the access page. There is no fallback. |
FACE_CLIENT_INSTANCE_NAMESPACE | POD_NAMESPACE | The namespace of that ClientInstance. |
POD_NAMESPACE | none | The pod’s namespace, from the downward API. Also used when publishing connectors to TIDE. |
POD_NAME | none | The instance name on lineage reports sent to TIDE. |
HOSTNAME | set by Kubernetes | The runner id fallback when RUNNER_ID is unset. |
KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT | kubernetes.default.svc, 443 | The API server FACE lists ClientInstances from. |
FACE_CONNECTORS_APP | face | The app key of the connectors ConfigMap FACE publishes to TIDE, <key>-connectors. TIDE sets it on each instance to the exact key it created and granted. Unset (the control plane), FACE writes face-connectors. A value that is not a DNS-1123 label (at most 63 characters of a-z, 0-9 and -, starting and ending with a letter or digit) is logged and nothing is published. |
SUBSCRIPTION_TIER, SUBSCRIPTION_STATUS, SUBSCRIPTION_SEATS | none | The subscription the operator mirrors from the ClientInstance. A subscription is reported only when the tier is set and FACE_TENANT matches the tenant asked about. |
RUNINK_ACCOUNTS_FILE | none | The account file the platform operator provides, mapping each user to the purchaser whose billing account pays for their model time. Unset, every model call is recorded as unattributed and logged, never billed to another account. See Plans and billing. |
TIDE_ROUTER_BILLING_KEY_FILE, TIDE_ROUTER_BILLING_KID | none | The key file (read by path) and key id FACE signs each model call’s billing claim with. Unset, model calls carry no billing claim. It never blocks or fails a call. |
TIDE_ROUTER_IDENTITY_KEY | none | The model router’s key (base64, at least 32 bytes) FACE signs an identity assertion with for a fetch a person started, so it runs on the router’s interactive lane. It is never logged or sent to a client. Unset, every model call stays on its billing lane. |
TIDE_PLATFORM_ADMIN | none | The installation admin’s e-mail. That account sees every instance. When it is unset, nobody gets that grant. |
LICENSE | none | A signed licence blob, as base64 or raw JSON. |
LICENSE_FILE | none | A path to read the licence from when LICENSE is unset. |
LICENSE_PUBLIC_KEY | none | The base64 Ed25519 public key licences are verified against. |
FACE_MODEL_CAP_FETCH_PER_HOUR, FACE_MODEL_CAP_ASK_PER_HOUR, FACE_MODEL_CAP_LOOP_PER_HOUR, FACE_MODEL_CAP_SIMULATE_PER_HOUR, FACE_MODEL_CAP_VISION_PER_HOUR | set by FACE | How many model-backed runs one user may start per hour, per class: fetches (RunFetch, RunFetchStream), QuickAsk, agent loops (ExecuteLoop), simulations (SimulateScenario, InteractiveSimulate) and vision (ExtractText, IngestSurveillanceFeed). A call over the cap gets RESOURCE_EXHAUSTED with the time until the next slot. |
TIDE_HEALTH_URL, TIDE_HEALTH_TOKEN | none | Where FACE reports observed lineage to the TIDE console, and the bearer token it uses. |
CORS_ALLOWED_ORIGINS | unset | A comma-separated allowlist of browser origins for gRPC-web. Set it to the origin(s) the FACE app is served from. |
FACE_RATE_RPS, FACE_RATE_BURST | set by FACE | Configure the per-user request rate limit (sustained rate and burst). Callers over the limit get RESOURCE_EXHAUSTED. A value that does not parse keeps the default. |
ENV, GCP_REGION | empty | Labels printed into the system state that compliance and domain analyses read. |
Authentication
| Variable | Source | Default | Purpose |
|---|---|---|---|
ADMIN_EMAIL | env | none | The admin account created at boot. |
ADMIN_PASSWORD | secret | none | Its password. If either value is missing, password admin login is disabled. |
AUTH_GOOGLE_ONLY | env | unset | true makes Google sign-in the sign-in method; password sign-in shows Password sign-in is disabled — use Google sign-in. |
FACE_REQUIRE_TOTP | env | unset (off) | Requires a TOTP second factor for password sign-in. all covers every account; a comma-separated list of roles (admin, writer, reader) covers only those roles. A covered account with no TOTP enrolled is not signed in by its password: the FACE app shows a setup key, and the first code from the authenticator app enrols the key and completes sign-in. Google sign-in relies on the identity provider’s own second factor. An unrecognised value stops the process. |
AUTH_SEED_USERS | env | none | Comma-separated email=role pairs to seed. The operator projects them from ClientInstance users. |
AUTH_USERS_PATH | env | the data directory | A legacy users file. It is imported once into the accounts table and then sealed as <path>.migrated. |
OIDC_ISSUER | env | none | The OIDC issuer. Single sign-on is on only when both this and OIDC_CLIENT_ID are set. |
OIDC_CLIENT_ID | env | none | FACE’s OAuth client id, and the default token audience. It must equal the FACE app’s google_client_id (the face-frontend-config ConfigMap). |
OIDC_AUDIENCE | env | OIDC_CLIENT_ID | An explicit audience override. |
OIDC_JWKS_URL | env | discovered | An explicit JWKS URL instead of discovery. |
AUTH_ALLOWED_EMAILS | env | none | The single sign-on allowlist. When SSO is configured and this is empty, every SSO login is refused (SSO is not available on this instance). An unlisted account gets This account is not authorized for this instance. The operator projects it from the face-oauth Secret. Changes take effect when the pod restarts. |
FACE_RECAPTCHA_SITE_KEY | env | none | The reCAPTCHA v3 site (public) key for login. The FACE app reads it from GET /auth/config. Configure it with FACE_RECAPTCHA_SECRET_FILE to captcha-check logins. |
FACE_RECAPTCHA_SECRET_FILE | secret path | none | Path to a file holding the reCAPTCHA secret key (a mounted Secret). It is read at each login, so a rotated Secret needs no restart. |
FACE_RECAPTCHA_HOSTNAMES | env | none | Comma-separated FACE host(s) a token must have been minted on. Required once a key is present. With a key present but the configuration incomplete, every login is refused until it is complete. |
FACE_RECAPTCHA_MIN_SCORE | env | 0.5 | The reCAPTCHA v3 score a login must reach. |
The login captcha is off while no site key and no secret file are present, which is the
default: the operator projects these three from the optional face-recaptcha Secret, and
reCAPTCHA is not enforced on FACE (owner, 2026-11-02).
Inference and the model plane
| Variable | Default | Purpose |
|---|---|---|
INFERENCE_REMOTE_URL | none (required) | The base URL for chat completions. |
INFERENCE_API_KEY | empty | Secret. Sent as Authorization: Bearer when it is set. FACE never generates one. The placeholder application-generated-key counts as empty. |
VISION_REMOTE_URL | INFERENCE_REMOTE_URL | The base URL for vision calls. |
VOICE_REMOTE_URL | INFERENCE_REMOTE_URL | The base URL for voice calls. |
INFERENCE_CONTEXT_SIZE | 16384 | The prompt window, in tokens, that the agent loop budgets against. |
INFERENCE_DECODE_TOK_S | none in FACE; the operator sets 1.8 | The fallback decode rate of the text tier, which sizes model-call budgets. Since 2026-10-26 (owner) FACE first uses the rate the model router publishes, then the rate measured from the plane’s own answers, and only then this value. A fetch with none of the three sends no model call and says why. |
INFERENCE_VISION_DECODE_TOK_S | none in FACE; the operator sets 1.0 | The same fallback, for the vision tier. |
FETCH_DECODE_TOK_S, REACT_DECODE_TOK_S, POSTURE_DECODE_TOK_S | the text tier’s rate | Pin the decode rate for the fetch, the agent loop’s turn budgets and posture analysis. An operator’s pin wins over the measured rate. |
FETCH_DEADLINE_SECONDS | 300 | The end-to-end fetch budget, in whole seconds. The hard ceiling is 900 seconds; a larger value is clamped to it, with a log line. |
FETCH_PHASE_DATA_PREP_SECONDS, FETCH_PHASE_POSTURE_SECONDS, FETCH_PHASE_RULES_SECONDS, FETCH_PHASE_TRENDS_SECONDS, FETCH_PHASE_HYPOTHESES_SECONDS, FETCH_PHASE_SYNTHESIS_SECONDS | 30, 90, 90, 90, 30, 45 at the 300-second deadline | Per-phase caps of a fetch (data profiling, business domains, business rules, market trends, what-if scenarios, recommendations). Unset, each cap scales with the deadline. The older names POSTURE_LLM_TIMEOUT_SECONDS and METASEARCH_BUDGET_SECONDS are still read for the domains and trends phases when the new name is unset. |
COMPLIANCE_LLM_BUDGET_SECONDS | 15 | The model time budget for compliance analysis. |
FETCH_TREND_MAX_QUERIES | 2 | How many scenario market topics one fetch may search (1–6). Topics shared by the most scenarios go first; confirmed public names, when set, replace them. |
FACE_ADMIT_MAX | 0 (off) | The maximum number of concurrent inference calls. 0 dispatches directly with no scheduling. The operator sets 1. |
FACE_ADMIT_QUEUE | 0 (unbounded) | The maximum number of waiters before backpressure. The operator sets 32. |
FACE_ADMIT_MODE | reject | reject or degrade when the queue is full. |
FACE_ADMIT_WEIGHTS | none | Tier weights, for example interactive:4,batch:1. |
FACE_ADMIT_COALESCE | off | true lets identical concurrent prompts share one generation. |
FACE_GATE_MAX_INFLIGHT | off | The concurrent-submission cap of the inference gate. |
FACE_GATE_FIRST_TOKEN_SECONDS | off | The longest acceptable queue wait. The gate is on only when this or FACE_GATE_MAX_INFLIGHT is positive. |
FACE_GATE_DECODE_RATE | none | The measured tokens per second the gate assumes. |
FACE_GATE_REQUEST_SECONDS | off | The per-request time budget for inference calls. |
These variables are read into the process configuration for compatibility. FACE starts no
model server of its own, so they neither choose nor tune what the plane serves. Set the
model on the plane instead. They are: INFERENCE_PORT, INFERENCE_HOST,
INFERENCE_MODEL, INFERENCE_TIMEOUT, INFERENCE_PARALLEL, INFERENCE_CACHE_RAM,
INFERENCE_CPU_STRICT, INFERENCE_THREADS, INFERENCE_BATCH, INFERENCE_GPU_LAYERS,
INTERNAL_INFERENCE_IP, INTERNAL_BRIDGE_IP, INTERNAL_SUBNET, MODEL_DIR,
MODEL_VOXTRAL, MODEL_WHISPER and MODEL_VISION. (MODEL_VISION is also printed
in the boot line that names the vision tier.)
MODEL_INFERENCE_TTS and MODEL_WAV_TOKENIZER are no longer read. Setting them does
nothing.
MODEL_VISION is a routing key, not a choice of weights. The model router
selects a backend tier from this name and then rewrites the field to default
before dispatch, so the value never reaches an engine — it only decides which
engine. Use a logical tier token (vision); a weights filename classifies as
the general TEXT tier, which answers an image request at HTTP 200 without
seeing the image.
Embeddings
FACE does not embed. EMBEDDING_URL, MODEL_EMBEDDING_DIM, EMBEDDING_FORMAT and
MODEL_EMBEDDING are not read, and setting them changes nothing. Retrieval is grep over
plain text: see Grounding.
Storage and persistence
| Variable | Source | Default | Purpose |
|---|---|---|---|
OBJECTSTORE_ENDPOINT | env | unset | The object store (host:port or https://host:port). When it is unset, the appfs root uses an encrypted local directory. An endpoint without TLS is accepted only for a loopback or cluster-internal name. |
OBJECTSTORE_ACCESS_KEY, OBJECTSTORE_SECRET_KEY | secret | none | Object-store credentials. They are required when an endpoint is set. |
OBJECTSTORE_VACUUM_ACCESS_KEY, OBJECTSTORE_VACUUM_SECRET_KEY | secret | none | An optional second credential used for every delete. Set both or neither. |
OBJECTSTORE_BUCKET | env | the store library’s fallback; the deployment sets runink-face-db-nane1 | The object-store bucket for records, knowledge and evidence. Always set it explicitly. The appfs root and the documents mount use their own buckets (FACE_APPFS_BUCKET, FACE_DOCUMENTS_BUCKET). |
FACE_APPFS_BUCKET | env | face | The object-store bucket of the appfs root. TIDE sets one per instance. It must be 3 to 63 characters of a-z, 0-9 and -, starting and ending with a letter or digit; any other value stops FACE from starting. |
FACE_DOCUMENTS_BUCKET | env | face-documents | The object-store bucket of the documents mount, with the same rule. |
TIDE_ENVELOPE_KEK_RETIRED | secret | none | Retired KEKs (comma- or space-separated, base64), accepted for decryption only. |
SQLITE_PATH | <data dir>/face.db | A legacy face.db from an earlier build, imported once if it exists and never created. It also anchors the defaults below that say “beside face.db”. The operator does not set it on the control plane; the face-runner manifest sets /data/face-runner.db, which a runner never opens as a database. | |
FACE_APPFS_DIR | appfs/ beside face.db | The encrypted local appfs root, used only when there is no object store. | |
FACE_UPLOAD_DIR | uploads/ beside face.db | The instance’s private upload directory, created mode 0700. An OCR LOCAL source and a fetch attachment named by file name are read only from here, and uploaded attachments are written here. It may not be /tmp or another shared system directory, and there is no temp-directory fallback. | |
FACE_CCTV_CAPTURE_DIRS | none | Extra absolute directories (colon-separated) in which a camera connection may name a local video file. The upload directory is always included. Any other local path is refused. | |
FACE_TENANT | default-tenant | The instance’s tenant, and the only tenant variable FACE reads. It names the tenant sub-root tenants/<tenant>/, the tenant sessions carry, and the tenant the access page and subscription checks compare against. It does not name the connectors ConfigMap (see FACE_CONNECTORS_APP). Set it before the first boot (see Persistence). | |
RUNNER_ID | HOSTNAME | On a runner, names its private tables. The face-runner manifest sets the stable value face-runner. | |
FACE_CONNECTIONS_DIR | none | The legacy connection directory. It is imported once into the appfs root. | |
FACE_DCI_CORPUS_DIR | none | An operator directory grounding also greps. FACE reads it and never writes to it. FACE’s own knowledge corpus is searched whether or not this is set. | |
FETCH_LEDGER_DIR | ./data/fetch-ledger | The fetch cascade ledger. | |
RALPH_RUN_DIR | ./data/ralph-runs | The agent run journal, used to resume runs. | |
FACE_VOICE_SOURCE_DIR | $RALPH_RUN_DIR/voice-sources | Where recorded voice sources are written. | |
RALPH_READ_ROOT | . | The root agents may read files under. Paths that escape it are rejected. | |
FACE_DEPLOY_SECRETS_DIR | none | A directory of runner deploy secrets, read by path. | |
EVIDENCE_FRAME_RETENTION | 0 (none kept) | How long camera evidence frames are kept, as a Go duration. It is capped at 720h. |
FACE persists nothing in SQLite (see Persistence).
Consensus, mesh and resilience
| Variable | Default | Purpose |
|---|---|---|
RAFT_NODE_ID | unset | This node’s consensus id. When it is unset, the process does not join consensus (runners). When it is set, a failure to start the orchestrator stops the process. |
RAFT_PEERS | none | The peers, as id@host:port,…. |
RAFT_PIPE_DIR | none | The local proposal-pipe directory. |
RAFT_DATA_DIR | unset (in memory) | The durable consensus state. When it is unset, FACE warns that the state is memory-only. |
RAFT_MTLS_ADDR | unset | The listen address of the mTLS raft peer plane. A voting control plane must set it. |
RAFT_ADVERTISE_IP, RAFT_ADVERTISE_HOST | none | Extra IP and DNS SANs on the mesh leaf certificates. |
LOAD_SHED_THRESHOLD | 0.85 | The orchestrator’s load-shed threshold. |
SNAPSHOT_THRESHOLD, SNAPSHOT_RETAIN | 1000, 100 | Raft snapshot cadence and retention, in entries. |
WATCHDOG_CPU_THRESHOLD | 99.5 | The watchdog’s CPU alarm, in percent. |
WATCHDOG_MEMORY_THRESHOLD_MB | library default | The watchdog’s memory alarm. |
WATCHDOG_GOROUTINE_THRESHOLD | 10000 | The watchdog’s goroutine alarm. |
WATCHDOG_RUNNER_DIAL_TIMEOUT_SECONDS | 5 | The runner reachability probe timeout. |
CIRCUIT_BREAKER_FAILURE_THRESHOLD | 5 | Failures before the breaker opens. |
CIRCUIT_BREAKER_RECOVERY_TIMEOUT_SECONDS | 30 | How long the breaker stays open before it tries again. |
SELF_HEAL_AUTONOMOUS | on | false limits the self-healing reasoner to ENDPOINT_UNHEALTHY events. |
Fetch, runners and agents
| Variable | Default | Purpose |
|---|---|---|
MANAGED_RUNNER_ENDPOINT | face-runner:7102 | Where the control plane forwards fetches. |
REQUIRE_RUNNER_ISOLATION | unset | true makes an unreachable runner a hard failure instead of a fallback to the control plane’s in-process SQL service. |
RUNNER_PORT | none | The port used when dialling a configured runner endpoint that has none. |
RUNNER_ENROLL_ADDR | unset | On a self-hosted runner, the control-plane address it enrols with (see Runners). |
RUNNER_ENROLL_TOKEN | none | The service-account token the runner enrols with. It is required when the address is set. |
RUNNER_ENROLL_TLS | true | TLS with system roots for the enrolment dial. false is refused, and the runner does not enrol. |
RUNNER_NAME, RUNNER_VERSION | empty | Shown in the control plane’s runner registry. |
RUNNER_COMPUTE_POOL, RUNNER_CPU_LIMIT, RUNNER_MEMORY_LIMIT | none, 1, 1G | Inputs to runink runner create for the Snowflake runner type. |
FACE_RUNNER_CHANNEL_ADDR, FACE_RUNNER_CHANNEL_LISTEN | none | The address runners in Snowflake or Databricks reach FACE’s runner channel at, and the local listen address. Both must be set for those deploy targets to be offered. |
FACE_RUNNER_CA_DIR | none | The runner CA (ca.crt, ca.key), read by path. |
FACE_RUNNER_IMAGE_ARCHIVE, FACE_RUNNER_IMAGE_ARCHIVE_SHA256, FACE_RUNNER_IMAGE_REF, FACE_RUNNER_BINARY, FACE_RUNNER_BINARY_SHA256 | none | The runner artifacts an on-premises deploy copies, each with its SHA-256. |
FACE_RUNNER_GCP_IMAGE | none | The default digest-pinned runner image in your registry for a Google Cloud deploy. |
SCHEDULE_EXECUTE_FETCH | off | true makes briefs run real fetches. When it is off, a brief’s trigger logs a dry run. The deployment sets it through spec.scheduleExecuteFetch. |
FETCH_CACHE_TTL | 10m | How long a fetch result may be reused. 0 disables reuse. |
FACE_RALPH_JUDGEMENT | on | Controls judging of proposed actions. |
FACE_RALPH_JUDGE_MAX_ACTIONS | set by FACE | Bounds the judging cost per answer. |
FACE_RALPH_JUDGE_REVISIONS | set by FACE | Bounds the revision rounds after dissent. |
FACE_FAST_JUDGEMENT | on | The local fast-path judge in front of the model. |
FACE_A2A_PEERS | none | Agent-to-agent delegation peers, separated by commas, spaces or newlines. |
A2A_ORGANIZATION | falls back to RUNINK_ORG, then TIDE_GITHUB_ORG | The organization published on the agent card. |
FACE_AGENT_EMAIL_ALLOWLIST | none | The addresses or @domain suffixes the audit trail treats as approved recipients for agent e-mail. Agent e-mail is always drafted for a person to send, whatever this list or the decision-authority policy says. |
FACE_OUTPUT_URL_HOSTS | none | Hosts an agent answer may link to, comma separated; a subdomain matches its parent. Every other link is removed from the answer, and images and embedded frames are always removed. |
FACE_GUARD_MODEL | none | The model-router token of the guard tier, usually guard. Configures the guard model that screens text in the agent loop. |
FACE_PROMPT_GUARD | on | Controls the guard model configured by FACE_GUARD_MODEL. The OpenBias rules and the output constraints always apply. |
FACE_AUTHORITY_POLICY_FILE | embedded default | A decision-authority policy (versioned JSON) replacing the shipped one. Unreadable or invalid = every approval refused. |
FACE_OPERATIONAL_LENS_FILE | embedded default | An operational lens (versioned JSON: areas, signals and the column-name terms that show them, and the decisions each needs) replacing the shipped one for the Operational coverage section on Ask. Unreadable or invalid = no lens, and the page says so. |
ENFORCE_AUDIT_LOGGING, REQUIRE_HITL, DATABASE_ENGINE, PRIMARY_SERVER_URL | unset | Reported into every compliance analysis as the controls in place. |
Connectors, vision and integrations
| Variable | Default | Purpose |
|---|---|---|
FACE_BROWSER_CONCURRENCY | 12 | The number of headless-Chrome renders run at once. Lower it on small hosts. |
FACE_MAP_TILE_URL | unset | An optional raster basemap for the twins map: an XYZ tile URL template ({z}, {x} and {y} all required) on your own tile service. Set, it is drawn instead of FACE’s built-in vector basemap. FACE never falls back to a public tile server. A template missing a placeholder is ignored, with a warning in the log. |
FACE_MAP_BASEMAP_PMTILES | /app/basemap/basemap.pmtiles | FACE’s built-in basemap: a PMTiles archive of OpenStreetMap vector tiles that ships in the server image and is served by the server itself at /api/map/basemap/{z}/{x}/{y}.mvt. Point it at a larger archive (for example a regional extract with street-level zooms) to give the map more detail. Missing, the map draws plain ground and says that no basemap is installed. |
FACE_MAP_GLYPHS_DIR | /app/basemap/glyphs | The glyphs the map draws place names with (<font name>/<start>-<end>.pbf), served at /api/map/glyphs/. Without them the map shows places as dots. |
FACE_MAP_TILE_ATTRIBUTION | © OpenStreetMap contributors | The credit shown on the map whenever the basemap is. Tiles built from OpenStreetMap data must carry it under the ODbL, self-hosted included; set your own if your tiles come from other data. |
FACE_MAX_DOWNLOAD_BYTES | 2 GiB | The largest file a connector downloads. |
SCRAPER_USER_AGENT | Mozilla/5.0 (compatible; RuninkFACE/1.0) | The user agent for crawling. |
VISION_DETECT_INSTANCES | off | true adds a per-instance detection turn per camera frame. It roughly doubles the vision time per frame. |
VISION_MAX_EDGE | 448 | Frames are downscaled to this longest edge. 0 disables downscaling. Keep it below 1000. |
VISION_SWEEP_FRAMES | 2 | The number of frames sampled per camera ingest (at most 8). |
VISION_RESOLVE_ITEMS | off | true resolves detected objects against the item catalogue. |
OCR_VISION_FALLBACK | off | true lets OCR fall back to the vision model. |
GOOGLE_CREDENTIALS_JSON | secret | A Google Workspace service-account JSON. The stored integration config is used when it is empty. |
TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_FROM_NUMBER, TWILIO_WHATSAPP_FROM | none | Voice, SMS and WhatsApp. FACE refuses to send by name when they are missing. |
PUBLIC_URL | localhost:8080 | The public host used for Twilio media-stream callbacks. |
FACE_VERIFY_MAIL_FROM | none | The envelope sender for the e-mail deliverability probe in the company checks (VerifyContact). It must be an address this deployment owns. Unset, the e-mail check records NOT_RUN with that reason, and no contact can become VERIFIED. |
CALLING_AGENT_URL | none | The shared calling agent that WebRTC signalling is forwarded to. When it is unset, the call RPC answers Unavailable. |
Frontend
PORT (default 8080), WEB_DIR (/web) and BACKEND_ADDR. See
Deployment model.
Removed and renamed names
Since the TIDE rename (2026-10-19) FACE reads only the TIDE_* names above
(TIDE_PLATFORM_ADMIN, TIDE_ROUTER_IDENTITY_KEY, TIDE_ROUTER_BILLING_KEY_FILE,
TIDE_ROUTER_BILLING_KID, TIDE_HEALTH_URL, TIDE_HEALTH_TOKEN, TIDE_GITHUB_ORG,
TIDE_ENVELOPE_KEK). The platform renders them; there is no fallback to the
pre-TIDE spelling.
These are listed to help an upgrade. FACE ignores every one of them, except
OBJECTSTORE_USE_SSL, which it refuses. Remove them from your resources.
| Name | Status |
|---|---|
REMOTE_LLAMA_URL, LLAMA_REMOTE_URL | Renamed to INFERENCE_REMOTE_URL. A manifest that sets only the old name has no inference endpoint, and the process refuses to start. |
LLAMA_API_KEY | Renamed to INFERENCE_API_KEY. |
MESH_MTLS, ENABLE_ALTS | Removed. Mesh mTLS is unconditional. |
REQUIRE_MTLS_INGRESS | Removed. |
OBJECTSTORE_USE_SSL | Removed, and refused if it is set. Put the scheme in OBJECTSTORE_ENDPOINT. |
GOOGLE_API_KEY | Read by no code. Maps keys are entered per connection in Settings › Integrations. |