All configuration is read once at process startup (main.cpp) — there’s no hot-reload or runtime config endpoint. Restart the process to change any of these.

​
Model paths

​
default:"/app/models/face_detection_yunet.onnx"
Filesystem path to the YuNet ONNX detector model. The /app/models/... default matches the Docker image’s mount point (see Deployment); override for local builds.
​
default:"/app/models/arcface_w600k_r50.onnx"
Filesystem path to the ArcFace ONNX embedder model.
If either path is wrong or the file is missing/corrupt, the process logs [main] FATAL: model initialization failed: ... and exits with status 1. This is deliberate — see Architecture → main.cpp for why a fail-loudly startup was chosen over serving with broken models.

​
Inference

​
default:"cpu"
ONNX Runtime execution provider for the embedder session. "cpu" or "cuda". If "cuda" is requested but unavailable, the service logs a warning and falls back to CPU rather than failing startup.
​
default:"1"
Threads ONNX Runtime uses internally for a single inference call. Kept low by default since parallelism across requests is handled by FACE_ENGINE_WORKERS instead — see Concurrency model.

​
HTTP server

​
default:"8080"
TCP port Drogon listens on.
​
default:"2"
Number of Drogon event-loop threads. These only handle connection I/O — never CPU-bound work — so this rarely needs to scale with core count.
​
default:"hardware_concurrency()"
Size of the worker thread pool that runs all decode/align/inference work. Defaults to the number of logical cores detected on the host/container.

​
Comparison behavior

​
default:"0.4"
Cosine-similarity threshold /v1/compare uses to decide match: true vs false. The default was set from a small manual validation set (4 genuine same-person pairs scored 0.52–0.67; 41 cross-identity pairs topped out at 0.32) — not a calibrated FAR/FRR curve. Validate against your own labeled dataset before trusting this in production; see Models → Similarity threshold for the full methodology.

​
Liveness

​
default:"0.85"
Minimum YuNet detector confidence for /v1/liveness to pass. Stricter than the 0.8 detection floor used for embed/compare, since a spoofed/printed face often detects with lower confidence than a live one.
​
default:"50.0"
Minimum Laplacian-variance sharpness over the detected face crop. Not calibrated against a labeled dataset — override once one exists. See Models → Liveness heuristic.
​
default:"0.03"
Minimum face bounding-box area as a fraction of the full frame. Rejects implausibly-small-face captures, common in low-effort photo-of-a-photo attacks shot from too far back.

​
Model version

​
default:"arcface-w600k_r50-v1"
Explicit version identifier returned by /v1/version. Not derivable from EMBEDDER_MODEL_PATH/DETECTOR_MODEL_PATH alone — bump this whenever the deployed model file changes, even if the filename doesn’t, so downstream consumers that store this value per embedding can detect drift.

​
Example: full override