Worker environment variable reference (apps/worker)

Worker environment variable reference (apps/worker)

SA3 engine customisation

These env vars tune the generation engine. They apply to both the home worker
and the RunPod handler unless noted.

Variable Values Default Notes
SA3_ENGINE mlx | diffusers platform engine.py:17-21
SA3_MODEL_ID HuggingFace model ID stable-audio-3-small-music e.g. stabilityai/stable-audio-3-medium
SA3_QUANT_MODE int8_weight_only | int8_dynamic | fp8 none CUDA only; model.py:282
SA3_TORCH_COMPILE 0 | 1 0 CUDA only; model.py:323
SA3_TORCH_COMPILE_MODE reduce-overhead | max-autotune | … reduce-overhead model.py:345
SA3_TORCH_COMPILE_DYNAMIC 0 | 1 0 model.py:346
SA3_MEGACACHE_DIR filesystem path none compile cache reuse; model.py:336
SA3_ENCODE_WORKERS integer 8 encode/upload thread pool; main.py:241
SA3_MODEL_IDLE_TTL_SECONDS seconds, or never|none|off|infinite 1800 Idle time before the resident engine is unloaded. 0 unloads immediately after each job; a sentinel keeps it resident forever. Unset or unparseable falls back to the default (a warning is logged for the unparseable case, never raised). engine_cache.py:43
SA3_PREWARM 0|1 0 Load the engine at startup instead of on first job. Opt-in for a dedicated GPU box; a laptop shouldn’t pay a resident model at login. engine_cache.py:84
SA3_MAX_CONCURRENCY integer 1 Explicit bound on concurrent generations via a semaphore. The daemon’s supervised single-flight slot makes 1 the only meaningful value. engine_cache.py:88
SA3_RESIDENT 0|1 0 Route both engine types through BackendProcessManager as resident child processes (stdin-JSONL protocol) instead of loading weights in-process. Default off until residency is proven on both CUDA and MLX boxes. engine_cache.py:94

brioso config prints the resolved value and source (env vs. default) for
exactly six of these: SA3_ENGINE, SA3_MODEL_IDLE_TTL_SECONDS,
SA3_PREWARM, SA3_MAX_CONCURRENCY, SA3_RESIDENT, plus
JOBSTORE_API_URL/WORKER_SHARED_SECRET — it does not cover every var in
the table above. Check there before chasing a claimed vs. actual mismatch on
one of those six; for the rest, check the process env directly.

Native audio.cpp profile

BRIOSO_WORKER_MODEL=audiocpp switches the home-worker generation path to the
native CLI. AUDIOCPP_BACKEND=cuda|metal then selects the runtime accelerator;
it does not itself select the model. Audio.cpp profiles require absolute,
existing AUDIOCPP_BIN and AUDIOCPP_MODEL_PATH values, with the F16 Medium
GGUF downloaded as a real local .gguf file before startup. See
audiocpp-home-worker-runbook.md.

Optional / less-common environment variables

  • HF_TOKEN (required first run) downloads SA3 weights from HuggingFace.
  • BRIOSO_REFINE_URL, BRIOSO_REFINE_API_KEY (optional) best-effort refine
    notify. Failure is captured, not fatal.
  • PHOENIX_COLLECTOR_ENDPOINT, OTEL_RELAY_TOKEN, TRACING_ENABLED,
    POSTHOG_API_KEY, POSTHOG_HOST (optional, safe no-op if unset).
    OTEL_RELAY_TOKEN is the bearer sent to whatever PHOENIX_COLLECTOR_ENDPOINT
    points at: Phoenix’s own API key when that is Phoenix directly, or
    WORKER_SHARED_SECRET when it is apps/web’s /otel/v1/traces relay
    (runtimes off the Tailnet). It is the sole relay credential — the old
    PHOENIX_API_KEY fallback was removed from obs-py (2026-08).
  • CF_SERVICE_TOKEN_ID / CF_SERVICE_TOKEN_SECRET (optional) only if the
    backend sits behind Cloudflare Access.
  • BRIOSO_WORKER_RUNTIME (optional, default home) the runtime id the
    push daemon reports as — the <runtime>:<call_id> leased_by prefix.
    Must name a registered runtime (built-in id or inference_routes row).
    jobstore.py ApiJobStore.__init__.
  • BRIOSO_WAKE_HOST / BRIOSO_WAKE_PORT (optional, 0.0.0.0 / 7311) the
    push daemon’s bind address (brioso-worker serve).
  • BRIOSO_WAKE_STATE_DIR (optional, <repo>/tmp/wake-agent) where per-call
    JSON records live; GET /jobs/{call_id} survives a restart, in-flight
    calls mark cancelled on reboot.
  • BRIOSO_WAKE_ALLOW_NODES (optional) comma-separated tailnet node names —
    narrows which peers may call POST /jobs; unset = any resolved tailnet
    node (BRI-422).
  • HOME_WAKE_TOKEN (optional) bearer for non-tailnet callers; unset =
    loopback + tailnet-only auth.
  • BRIOSO_PUSH_DRAIN_SECONDS (optional, default 10) SIGTERM/SIGINT grace
    for the in-flight call before the daemon exits.
  • WORKER_LEASE_SECONDS (optional, default 120) / WORKER_HEARTBEAT_SECONDS
    (optional, default 15) tune how long a leased job’s lease lasts and how
    often this worker renews it. Lower than the old 300s/30s defaults —
    BRI-251’s runner fallback needs a dead worker’s lease to expire fast enough
    for the reaper to promote the job to RunPod without a long stall. A 409 on
    renewal (lease lost — the server already re-routed the job) aborts the
    current job at its next checkpoint instead of finishing and double-uploading.

R2 credentials are NOT used by the worker at runtime. Uploads go through
presigned PUT URLs the backend mints from its own R2_* config.

Previous Worker deployment guide Next Worker secrets sync (BRI-427)