Worker deployment guide
Worker deployment guide
Brioso-worker push daemon (BRI-437)
The home worker is an always-on push daemon: a small HTTP server
(brioso-worker serve) that keeps the SA3 engine warm and accepts jobs the
dispatch sweep POSTs to it (POST /jobs → 202 {call_id} / 429 busy;
GET /jobs/{call_id} → call state; GET /health → engine + GPU state). It
runs always-on under pm2 supervision on all three platforms (macOS,
Linux, Windows) — one persistent process, not per-tick invocations. The old
claim-loop daemon (brioso-worker worker + run-daemon.sh +
ecosystem.config.cjs) is deleted; the worker subcommand remains only for
Modal’s pull worker and local dogfood. Runbook:
home-worker-wake.md.
Supervision (pm2 — all platforms)
pm2 manages the daemon lifecycle identically on macOS, Linux, and Windows.
# Start
pm2 start deploy/pm2/ecosystem.wake-agent.config.cjs
# Persist across reboots: save current process list, then generate the native startup script
pm2 save
pm2 startup # prints e.g. `sudo env PATH=... launchctl ...` or the systemd equivalent
The brioso CLI (apps/worker/cli/brioso) wraps pm2 for convenience:
brioso status # pm2 describe brioso-wake-agent
brioso start # pm2 start deploy/pm2/ecosystem.wake-agent.config.cjs
brioso stop # pm2 stop brioso-wake-agent
brioso restart # pm2 restart brioso-wake-agent
brioso logs # pm2 logs brioso-wake-agent
brioso engine # prints SA3/* or audio.cpp/{cuda,metal}, based on the profile
On macOS, wake prevention is owned by the worker process itself.
Native audio.cpp profiles
For dedicated NVIDIA CUDA or Apple Silicon Metal home workers, use the
explicit, copy-to-local profiles in
audiocpp-home-worker-runbook.md. They set
BRIOSO_WORKER_MODEL=audiocpp; AUDIOCPP_BACKEND then selects cuda or
metal. Both require absolute, pre-downloaded audio.cpp v0.7.3 binary and F16
Medium GGUF paths before pm2 starts.
Single invocation (dev / one-shot)
uv run brioso-worker serve # the push daemon (normal path)
For the live backend, set JOBSTORE_API_URL and WORKER_SHARED_SECRET in
the environment. The pull claim loop (brioso-worker worker) was removed in
BRI-439 — serve is the only mode.
Engine customisation
| Variable | Values | Default | Effect |
|---|---|---|---|
SA3_ENGINE |
mlx | diffusers |
platform | Which SA3 backend to use |
SA3_MODEL_ID |
HuggingFace model ID | stable-audio-3-small-music |
Which SA3 variant to load |
SA3_QUANT_MODE |
int8_weight_only | int8_dynamic | fp8 |
none | CUDA quantization scheme (CUDA only) |
SA3_TORCH_COMPILE |
0 | 1 |
0 |
Wrap DiT in torch.compile (CUDA only) |
SA3_TORCH_COMPILE_MODE |
reduce-overhead | max-autotune | … |
reduce-overhead |
compile mode |
SA3_TORCH_COMPILE_DYNAMIC |
0 | 1 |
0 |
Enable dynamic shapes in compile |
SA3_MEGACACHE_DIR |
filesystem path | none | Reuse torch compile cache across boots |
SA3_ENCODE_WORKERS |
integer | 8 |
Thread pool size for encoding + R2 upload |
SA3_MODEL_IDLE_TTL_SECONDS |
integer | 900 |
Unload model after this many seconds idle |
Joining a box
JOBSTORE_API_URL=https://usebrioso.com
WORKER_SHARED_SECRET=<secret> # from the Brioso backend
For the push model the backend must reach the box — over the tailnet by
default (BRI-422 whois auth; BRIOSO_WAKE_ALLOW_NODES narrows it) or with a
HOME_WAKE_TOKEN bearer for non-tailnet callers. The box’s outbound calls
are only result PATCHes + R2 PUTs.
System requirements
- macOS, Linux, or Windows
- GPU: CUDA (Linux/Windows) or Apple Silicon M-series (macOS)
uvandnodeavailable on PATHffmpegon PATH (audio encoding)
Prompt refinement service
The refine service runs inside the web app (TanStack Start) as /refine/ routes served
on port 3000.
Environment variables for the worker to contact it:
BRIOSO_REFINE_URL(default: http://localhost:3000)BRIOSO_REFINE_API_KEYBRIOSO_REFINE_API_TYPE(openai_compatible|anthropic)BRIOSO_REFINE_BASE_URLBRIOSO_REFINE_MODEL
Environment variables
Worker / R2
| Variable | Default | Description |
|---|---|---|
BRIOSO_WORKER_STORE |
sqlite |
Job store: sqlite (local) or api (HTTP backend) |
BRIOSO_WORKER_ID |
(required) | Unique worker identifier |
JOBSTORE_API_URL |
http://localhost:3000 |
Backend job API URL |
CF_SERVICE_TOKEN_ID |
— | Cloudflare Access service-token ID |
CF_SERVICE_TOKEN_SECRET |
— | Cloudflare Access service-token secret |
WORKER_SHARED_SECRET |
— | Bearer token for /jobs/* routes; must match the backend |
R2_ENDPOINT |
(required) | R2/S3 endpoint URL |
R2_ACCESS_KEY_ID |
(required) | R2 access key ID |
R2_SECRET_ACCESS_KEY |
(required) | R2 secret access key |
R2_BUCKET |
(required) | R2 bucket name |
R2_URL_TTL_SECONDS |
2592000 |
Presigned URL lifetime in seconds |
Refine service
| Variable | Default | Description |
|---|---|---|
BRIOSO_REFINE_URL |
http://localhost:3000 |
Refine service URL |
BRIOSO_REFINE_API_KEY |
— | API key for the refine service |
BRIOSO_REFINE_API_TYPE |
openai_compatible |
Provider type |
BRIOSO_REFINE_BASE_URL |
— | LLM endpoint base URL |
BRIOSO_REFINE_MODEL |
— | LLM model id |