npx vfrey worker runs a tick every 60 seconds in your terminal until you stop it. The background service does the same for every project on your machine, and keeps running when you close the terminal.
Install it
npx vfrey worker --all-projects in a terminal and leave it open.
On Linux,
loginctl enable-linger $USER keeps the worker running after you log out.
What a cycle does
npx vfrey worker --all-projects is what the service runs. Each cycle it reads the machine index (~/.vfrey/projects.json, the list npx vfrey projects shows). For every project that has a series that is due and not paused, it runs one tick in that project’s folder, so the project’s own .env and database are used. A project whose folder is gone is skipped and logged as missing. One project’s trouble never stops the others. --once runs a single cycle and exits, and --dry-run skips the real render and upload.
The service also ticks a project that has an approved job ready to render, even when no series is due. See Review before render. service status and the cycle log show how many jobs wait for review.
The service only starts a project’s series on their cadence. It publishes only where you added keys and only for a series that is live. A new series is dry-run until you go live. See Autopilot.
The service passes along PATH, HOME, VFREY_HOME, the voice and Chrome settings, and the HyperFrames path. It does not pass secrets: each project’s .env holds those.
Locks
Only one tick runs in a project at a time. A tick,desk tick, and the worker all take .vfrey/worker.lock in the project. If you run npx vfrey tick --now while the worker is ticking that project, the second one stops and says another tick is running (exit code 75), and the worker skips a busy project until its next cycle. A lock left by a process that is gone is taken over.
Logs
The log is~/.vfrey/logs/worker.log (under VFREY_HOME when set). Each line is JSON. It rotates at 5 MB and keeps 3 older files. Secrets are redacted. npx vfrey service logs prints it, and npx vfrey worker --all-projects in a terminal prints it as it goes.
Check on it
missing when its folder is gone, or ticking now. If the service is not installed, status says so and prints the install command.