You need Node.js 22.13 or newer, ffmpeg, and a coding agent: Claude Code, Codex, Grok, Cursor, Gemini CLI, or another. The default voice needs macOS. On other systems, set TTS_PROVIDER=openai or TTS_PROVIDER=none. See Setup. vfrey is in beta, so install the beta tag.
1

Start a project

npm runs create-vfrey for you. npx create-vfrey@beta my-channel does the same. This makes the folder my-channel, installs vfrey in it, and runs vfrey doctor. Each failed check prints a Fix: line. The project already holds what every agent needs: AGENTS.md, CLAUDE.md, GEMINI.md, and the vfrey skill. See Projects.
2

Go into the folder

3

Open it in your agent

Start your agent in this folder: claude, codex, grok, gemini, or open the folder in Cursor. Nothing else to install. The agent reads the folder’s instructions and finds the skill there. Working outside a project? See Agent skill to install it. More detail: Your agent.
4

Ask for a video

Say: “Make me a short video about how octopuses have three hearts, and show it to me.”The agent writes the script, designs a scene for the idea, renders the video into videos/ under a readable name like videos/2026-10-26 How octopuses have three hearts.mp4, and shows it to you. The transcript sits beside it as .txt. The first render or frame preview downloads Chrome Headless Shell (about 170 MB) once, so it takes longer; vfrey prints Downloading Chrome Headless Shell (about 170 MB), first time only… before it starts.You can run it by hand too:
--about takes the topic in your own words, in quotes: the subject of the video, for example “how octopuses have three hearts”. It is not a title or a script. Without --script, vfrey writes a basic placeholder script. An agent writes its own. See Your agent. To ask for a length, add --duration 20-30 (seconds): a voice that falls outside it stops before the render and says how many words to cut or add.
5

Look at it

This opens this project’s dashboard in your browser and prints its URL. If the dashboard is already running, it reuses it. npx vfrey videos lists your videos with their paths.
During the beta use @beta: npm create vfrey@beta my-channel. The @latest form works once the beta is promoted.
A new series is not live, so nothing is uploaded and the summary says why: Not uploaded to youtube: this series is not live yet, and No youtube key is set either when you have no key. Dry run (--dry-run) appears only when you pass --dry-run, and Upload skipped: no key for youtube appears once the series is live without a key. Either way the video stays on your machine, and the summary says “Replies skipped: no platform keys”. npx vfrey push refuses for now. Publishing happens inside tick once the series is live and keys are set. See Autopilot.The tick also starts this project’s dashboard in the background, prints Dashboard: URL once at the end, and leaves it running. Stop it with npx vfrey dashboard stop.
If tick makes nothing, it prints why. See Troubleshooting. To keep going on the series cadence, run npx vfrey worker.