> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyager.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Farm a frame range across cloud machines

> Split an animation's frames over several Voyager cloud machines started from one snapshot, check every frame, pull the results and release every machine, with one command.

`voyager cloud farm` renders a frame range on several machines at once. It leases them from a snapshot, hands each the next chunk of frames from one shared queue, checks the outputs, pulls them back and releases every machine it leased when it ends, even when it fails or you press Ctrl-C.

> [!NOTE]
>
> **Before you start:** the `voyager` CLI ([quickstart](https://docs.voyager.so/api/machines/quickstart.md)) and a snapshot of a machine that has your scene on it. Each farm machine bills by the second like any other; your plan sets how many you can run at once.

## Set up once, then farm

**1. Put the scene on one machine and snapshot it**

Set up one machine with everything the render needs, then save its disk. Here, the scene from [Render with Blender](https://docs.voyager.so/api/machines/blender.md):

```sh theme={"system"}
m=$(voyager cloud lease render-lite --wait --yes)
voyager cloud push $m shot/ shot
voyager cloud exec $m -- "cd shot && blender -b -P build_scene.py -- recipe.json --tier draft"
voyager cloud save $m farm-scene
voyager cloud release $m
```

`save` keeps the machine's disk under the name `farm-scene` (saving the name again moves it to the new state). Release the setup machine: the farm leases its own.

**2. Farm the frames**

```sh theme={"system"}
voyager cloud farm farm-scene --frames 1-4 --machines 1 --chunk 2 --preset render-lite \
  --expect 'shot/out/{frame:04}.png' --out film \
  -- blender -b shot/product-sweep.blend -o //out/#### -s {start} -e {end} -a
```

The command after `--` runs once per chunk, with `{start}` and `{end}` filled in. `--expect` names one file per frame, and every one must exist before the chunk counts as done. The frames land in `film/shot/out/`. This run took about a minute and a half, leasing included, and the farm released its machine at the end.

Raise `--machines` to split a long range: each machine takes the next chunk as it finishes, so a slow machine never holds up the rest.

## Options

| Option | What it does |
| - | - |
| `--frames A-B` | The frames to render. |
| `--machines N` | How many machines to lease at once. At your plan's limit, each waits for a free one (`--wait-timeout`, default 1 hour) and the farm goes on with what it has. |
| `--chunk K` | Frames per chunk (default: about 3 chunks per machine). Frames only. |
| `--tasks FILE` | Farm the lines of a file instead of frames. See [Farm a list of tasks](#farm-a-list-of-tasks). |
| `--on-finish 'cmd'` | Runs on your computer when the farm ends. See [Run something when the farm ends](#run-something-when-the-farm-ends). |
| `--preset P` | The preset for every machine. |
| `--preflight 'cmd'` | Runs once on each machine before any chunk. If it fails, the farm releases its machines and stops. |
| `--expect PATTERN` | The outputs every chunk must leave: `out/{frame:04}.png` is one file per frame, zero-padded to 4; any other pattern is a glob that must match a file. |
| `--encode 'cmd'` | Runs on the machine after each chunk, for example `ffmpeg` from the chunk's frames to one video. |
| `--pull PATTERN` / `--out DIR` | What to pull instead of the `--expect` files, and where it lands. |
| `--budget USD` / `--ceiling USD` | One budget for the whole farm, and where every machine pauses (default 1.25× the budget). See [A budget for the whole farm](#a-budget-for-the-whole-farm). |
| `--budget-per-machine USD` / `--max-hours H` | A dollar cap per machine (default: `--max-hours`, 6, at the preset's price), so a farm whose CLI dies can't leave machines billing. |

A failed chunk is retried on another machine, three tries in all. A machine that fails two chunks, or dies, is released and replaced.

## A budget for the whole farm

```sh theme={"system"}
voyager cloud farm snp_… --frames 1-1200 --machines 6 --budget 40 --ceiling 50 --expect 'out/{frame:04}.png' --out film -- blender -b scene.blend -o //out/#### -s {start} -e {end} -a
```

* **At `--budget`:** once what the farm has spent, plus one more chunk, would pass it, no new chunk starts. Running chunks finish and are pulled, and idle machines are released. The report lists what is done and what is left. Run the farm again with `--resume` and a higher `--budget` to finish.
* **At `--ceiling`:** every farm machine is paused, with its disk kept. `farm cleanup` releases them.
* **Replacements:** a machine that replaces a failed one gets only what is left of the ceiling, never a fresh share. A machine that went away counts at its full cap until Voyager confirms what it cost.
* **If the CLI stops:** each machine carries its share of the budget and ceiling, so Voyager pauses it even with nobody watching.

The same works for task farms (`--tasks`).

## Encode on the machine

Pull one video per chunk instead of thousands of frames: encode on the machine and pull only the video.

```sh theme={"system"}
voyager cloud farm snp_… --frames 0-1367 --machines 5 --chunk 48 \
  --expect 'out/{frame:04}.png' --out film \
  --encode 'mkdir -p enc && ffmpeg -y -v error -framerate 24 -start_number {start} -i out/%04d.png -frames:v {frames} -c:v libx265 -pix_fmt yuv444p10le enc/{start}-{end}.mkv' \
  --pull 'enc/{start}-{end}.mkv' \
  -- blender -b scene.blend -o //out/#### -s {start} -e {end} -a
```

## Farm a list of tasks

Not every job is a frame range. `--tasks` farms any list of independent tasks, such as shots, seeds or scenes: one per line of a file, with the same queue, retries, checks, pulls and release as frames.

```text shots.txt theme={"system"}
# one task per line; blank lines and # lines are left out
seed-7
seed-11
seed-42
```

```sh theme={"system"}
voyager cloud farm snp_… --tasks shots.txt --machines 2 \
  --expect 'out/{index}.txt' --out results \
  -- 'mkdir -p out && python3 make.py --seed {task} > out/{index}.txt'
```

* Tasks are numbered 1 to N in file order. In the command after `--`, `{task}` is the task's line as written and `{index}` is its number. Without a command after `--`, each line is itself the shell command.
* Name outputs in `--expect` and `--pull` with `{index}`, never `{task}`: a line can hold spaces.
* Each task's whole log comes back as `<--out>/logs/<n>.log` (without `--out`, beside the farm's record in `.voyager-farm/`).
* `--json` lists every task with its status, tries, machine, log and outputs, plus the credits the farm spent.
* A file takes up to 2,000 tasks. `--chunk` is for frames only: each task is its own chunk.

A three-task farm on one machine took under a minute, leasing included, and released its machine at the end.

## Run something when the farm ends

`--on-finish 'cmd'` runs a command on your own computer once the farm ends, whether it is done, failed, stopped by Ctrl-C or left a machine it couldn't release. The command gets the farm's summary as JSON on stdin, and `VOYAGER_FARM_STATUS` (`done`, `failed`, `stopped` or `unreleased`), `VOYAGER_FARM_NAME` and `VOYAGER_FARM_RECORD` in its environment. Its output goes to stderr, so `--json` on stdout stays clean, and its exit code never changes the farm's.

```sh theme={"system"}
voyager cloud farm snp_… --tasks shots.txt --machines 2 --out results \
  --on-finish 'jq -r .status > status.txt' -- 'python3 make.py --seed {task}'
```

## If the farm stops

The farm keeps a record in `.voyager-farm/<name>.json` (`--name` sets the name).

* **Continue:** `voyager cloud farm --resume .voyager-farm/<name>.json` skips the chunks that are done and reuses machines still up.
* **Clean up:** `voyager cloud farm cleanup <name>` releases every machine a crashed farm left. Every farm machine carries the farm's tag, so even a machine whose lease answer was lost is found.

## Next

> [card] [Concepts](https://docs.voyager.so/api/machines/concepts.md)
>
> What snapshots keep, and what each machine state bills.

> [card] [Render with Vork](https://docs.voyager.so/api/machines/vork.md)
>
> Vork splits a long render over the GPUs of one machine by itself.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.