Skip to content

Roles and services

github-actions[bot] edited this page Nov 22, 2026 · 12 revisions

Clippa runs in four roles, plus an optional operator. A machine can do more than one.

Role What runs there Needs
GPU worker clippa worker: transcribe, score, segments, then Shorts (and clips, if [review] include has "picks") to review, then long segments to review an NVIDIA GPU (8 GB+) or Apple Silicon, or none with [transcribe] backend = "modal" (Transcribe on Modal); the NAS share, ffmpeg
Serve clippa serve: the war room, hourly replan and upload, pre-show grabs, retakes, daily jobs always on, the NAS share (or local streams), ffmpeg; the GPU extra, Modal or a CPU transcribe for pre-shows
Bot clippa bot: Discord review cards, buttons, DMs (Review) always on (usually the serve machine), the NAS share
Recorder clippa record watch in Docker on the NAS Docker; see NAS recorder
Claude (optional) Claude Code in its own clone of the repo, driven from the Claude app on the phone Docker on the NAS; see Claude on the NAS

All roles share one streams folder (a NAS share). Only one machine runs serve and only one runs the bot. Here serve, the bot and the worker run as containers on the NAS since 2026-11-05, with the config and state there too: see NAS hub.

Services

One supported way per role, unattended:

Role Runs as Start, stop, update
serve, bot, worker (with a GPU or Modal) Docker compose, deploy/hub, on any Docker host that sees the streams folder (here the NAS, NAS hub) clippa services status|stop|restart serve|bot|worker|all runs docker compose there over ssh with [serve] hub set; bash deploy/hub/deploy.sh ships main
GPU worker on a Windows machine a scheduled task, deploy\worker\worker-task.ps1 -Install (at logon, restarted if it exits, no admin needed; Install on Windows, step 8) -Status, -Restart, -Stop, -Uninstall; clippa services without [serve] hub runs the same script, which also stops the supervisor and the stage processes
YouTube cookies for the hub (laptop) a scheduled task, deploy\cookies\cookies-task.ps1 -Install (at logon and every 4 hours, clippa cookies export; Archives). The NAS depends on the laptop for this -Status, -Run, -Uninstall
recorder its own compose project on the NAS (NAS recorder) clippa services restart recorder over ssh, refused while a show is recording; bash deploy/record/deploy.sh

deploy/hub is written for the NAS but runs on any Docker host: env.local sets CLIPPA_DATA (the folder mounted as /data, with clipper.toml, streams/ and secrets/), PUID/PGID for the files it writes, and RENDER_GID for the Intel GPU device (drop the /dev/dri lines from compose.yaml on a host without one). Restart serve after scheduler or war-room changes, the bot after Discord changes. Serve and the bot by hand (clippa serve, clippa bot in a terminal) are fine for a try, and clippa services status still shows their heartbeats; there are no task scripts for them any more. Never run a service on two machines at once: their single-instance locks don't see each other.

Serve and bot on different machines

The bot reaches serve at [serve] url (empty = this machine). On different machines set it, give both the same [warroom] token (or secrets/warroom_token.txt), and put [paths] schedule and [paths] news under the streams share on both (the bot reads what serve writes there; clippa doctor --role bot checks, and warns when [discord] enabled is false, since no cards get posted then).

Logs and alerts

Logs go to logs\ (serve.log, bot.log, worker.log). The bot DMs you when something needs you (Review, "Alerts"). clippa doctor --role gpu|serve|bot|nas|claude|control checks a machine and prints a fix for each problem. clippa status is the one screen: what needs you first, then every service's heartbeat and the recorder's, the worker's recent streams, review counts, the next releases and this month's spend, read from the share with nothing started (about 15 s from the laptop); clippa services status has the per-job detail and the stop and restart verbs.

Clone this wiki locally