Configuration reference

This reference was built from the code. It lists every environment variable read by the FACE backend (grpc/), the platform libraries it links (security, store, inference), its Litestream configuration and the frontend sleeve. It leaves out variables read only by build tooling, benchmarks and tests, and variables read only by the separate voice calling-agent image.

In a cluster, set values through the ControlPlane or FaceInstance env list, never on the live Deployment (see Deployment model). Locally, export them before core dev up face.

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.

Connector and integration credentials (warehouses, SaaS APIs, maps keys) do not belong in environment variables. They are entered per connection in the cockpit and stored sealed in FACE’s credential store. The few integration variables below are the exceptions the code still reads.

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.
`CORE_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. `demo` seeds the demo connection set. When the process has no in-cluster ServiceAccount token, `demo` also offers a single local-development instance in the instance picker.
`DEMO_SEED_DATA`	unset	`true` also seeds the demo connection set. It does not enable the local instance card. Prefer `RUNINK_VARIANT=demo`.
`RUNINK_APP`	`face`	The app name that filters `ClientInstance`s 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 CORE.
`POD_NAME`	none	The instance name on lineage reports sent to CORE.
`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 `ClientInstance`s from.
`TENANT_ID`	none	The pod’s tenant for subscription checks. Also names the connectors ConfigMap FACE publishes to CORE (`face-<tenant>`).
`SUBSCRIPTION_TIER`, `SUBSCRIPTION_STATUS`, `SUBSCRIPTION_SEATS`	none	The subscription the operator mirrors from the `ClientInstance`. A subscription is reported only when the tier and `TENANT_ID` are set and match the tenant asked about.
`CORE_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.
`CORE_HEALTH_URL`, `CORE_HEALTH_TOKEN`	none	Where FACE reports observed lineage to the CORE console, and the bearer token it uses.
`CORS_ALLOWED_ORIGINS`	unset	A comma-separated allowlist of browser origins for gRPC-web. Set it to your cockpit origin(s).
`FACE_RATE_RPS`, `FACE_RATE_BURST`	unset	The per-caller request rate (requests per second) and burst. Callers over the limit get `ResourceExhausted`.
`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 break-glass admin account seeded at boot.
`ADMIN_PASSWORD`	secret	none	Its password. If either value is missing, FACE logs `break-glass admin not seeded` and disables password admin login.
`AUTH_GOOGLE_ONLY`	env	unset	`true` rejects password sign-in with `Password sign-in is disabled — use Google sign-in`. The break-glass admin is exempt.
`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 cockpit’s `google_client_id`.
`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.
`HCAPTCHA_SECRET`	secret	none	The secret for verifying hCaptcha on login.

Inference and the model plane

Variable	Default	Purpose
`INFERENCE_REMOTE_URL`	none (required)	The base URL for chat completions, and for embeddings when `EMBEDDING_URL` is unset.
`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`	`3.4`	The measured decode rate of the text tier. It sizes time budgets.
`INFERENCE_VISION_DECODE_TOK_S`	`1.0`	The same, for the vision tier.
`REACT_DECODE_TOK_S`	`INFERENCE_DECODE_TOK_S`	Overrides the decode rate for the agent loop’s turn budgets.
`REACT_PREFILL_TOK_S`	`38`	The prefill rate for the agent loop’s turn budgets.
`POSTURE_DECODE_TOK_S`	`INFERENCE_DECODE_TOK_S`	Overrides the decode rate for posture analysis.
`POSTURE_LLM_TIMEOUT_SECONDS`	`120`	The model time budget for posture analysis.
`COMPLIANCE_LLM_BUDGET_SECONDS`	`15`	The model time budget for compliance analysis.
`METASEARCH_BUDGET_SECONDS`	`90`	The time budget for the trend metasearch step of a fetch.
`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_EMBEDDING, MODEL_VOXTRAL, MODEL_WHISPER, MODEL_INFERENCE_TTS, MODEL_WAV_TOKENIZER and MODEL_VISION. (MODEL_VISION is also printed in the boot line that names the vision tier.)

Embeddings

Variable	Default	Purpose
`EMBEDDING_URL`	`INFERENCE_REMOTE_URL`	A dedicated embedding endpoint. Without it, embeddings go to the chat plane, and semantic grounding is expected to report `INACTIVE`.
`MODEL_EMBEDDING_DIM`	`768`	The vector width the knowledge index is built for. The endpoint’s vectors must have this width after the format’s fit.
`EMBEDDING_FORMAT`	`qwen3-embedding`	The instruction format of the embedding model: `qwen3-embedding`, `nomic-v1.5` or `raw`. It must name the model `EMBEDDING_URL` actually serves. An unknown name stops the process.

See Model plane.

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. A cleartext endpoint 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	`core`	The object-store bucket for records, knowledge and evidence. The appfs root always uses its own bucket, `face`.
`CORE_ENVELOPE_KEK_RETIRED`	secret	none	Retired KEKs (comma- or space-separated, base64), accepted for decryption only.
`SQLITE_PATH`	`<data dir>/face.db`		The MetaDB file. The entrypoint requires an absolute path. The operator sets `/data/face.db`.
`FACE_APPFS_DIR`	`appfs/` beside `face.db`		The encrypted local appfs root, used only when there is no object store.
`FACE_TENANT`	`default-tenant`		The tenant sub-root, `tenants/<tenant>/`. Set it before the first boot (see Persistence).
`RUNNER_ID`	`HOSTNAME`		On a runner, names its private tables. The operator sets a stable value.
`FACE_CONNECTIONS_DIR`	none		The legacy connection directory. It is imported once into the appfs root.
`FACE_DCI_CORPUS_DIR`	none		Overrides the directory the grep-based grounding reads.
`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.
`FEATURED_MESSAGES_PATH`	`featured_messages.json` on the data path		A file of featured activity messages.
`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`.

Litestream, read by /app/litestream.yml and set by the operator: SQLITE_PATH, MINIO_ENDPOINT (host and port only, with no scheme), MINIO_BUCKET, MINIO_ACCESS_KEY, MINIO_SECRET_KEY. The image entrypoint also checks MINIO_ENDPOINT to decide whether to run the server under Litestream.

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.
`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.
`SCHEDULE_EXECUTE_FETCH`	off	`true` makes schedules run real fetches. When it is off, a schedule logs a dry run.
`FETCH_CACHE_TTL`	`10m`	How long a fetch result may be reused. `0` disables reuse.
`FETCH_CACHE_MIN_CONFIDENCE`	`0.7`	The minimum confidence for a cached result to be reused.
`FACE_RALPH_JUDGEMENT`	on	`off`, `false`, `0`, `no` or `disabled` turns off judging of proposed actions.
`FACE_RALPH_JUDGE_MAX_ACTIONS`	`3`	The number of actions judged per answer (1–20).
`FACE_RALPH_JUDGE_REVISIONS`	`1`	The number of revision rounds after dissent (0–3).
`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 `CORE_GITHUB_ORG`	The organization published on the agent card.
`FACE_AGENT_EMAIL_ALLOWLIST`	none	The addresses or `@domain` suffixes agents may e-mail autonomously.
`ENFORCE_AUDIT_LOGGING`, `REQUIRE_HITL`, `DATABASE_ENGINE`, `PRIMARY_SERVER_URL`	unset	Reported into every compliance analysis as the controls actually in place. They never stop the process.

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_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.
`HUBSPOT_API_KEY`	none	The key for the HubSpot read paths.
`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.
`CALLING_AGENT_URL`	none	The shared calling agent that WebRTC signalling is forwarded to. When it is unset, the call RPC answers `Unavailable`.

Frontend sleeve

PORT (default 8080), WEB_DIR (/web) and BACKEND_ADDR. See Deployment model.

Removed and renamed names

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`.
`CORE_ENVELOPE_ENCRYPTION`	Removed. Sealing at rest is unconditional.
`GOOGLE_API_KEY`	Read by no code. Maps keys are entered per connection in the cockpit.

Prerequisites and ordering Model plane