Repository navigation
Roles and services
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.
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.
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 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.
Home · Getting started · clippa doctor · These pages are built from docs/wiki/ in the repo, so edits made here are overwritten: how to edit them
Run it
- Overview
- Getting started
- Roles and services
- Configuration
- Pipeline
- Review
- Reviewing
- War room
- Clippa messenger
- Scheduling and uploads
- Costs
- Checkup
- Audit
- Backups
Install
- Install
- Install checklist
- Kitsu
- Discord app
- YouTube sign-in
- Windows
- macOS
- Transcribe on Modal
- NAS recorder
- NAS hub
- Claude on the NAS
- Phone access
- Model providers
- Adding a show
- YouTube channel
Features
- Pre-shows
- Fetching VODs
- Speakers
- Faces
- Covers
- Cast library
- B-roll
- Clip art
- Weekly issue
- X posts
- TikTok
- News watcher
- Character pieces
- Documentaries
Research
Working on Clippa