voyager cloud does not guess your project’s setup. You (or your agent) choose the commands, and Voyager runs them, copies files, keeps the machine’s disk and releases the machine when you’re done. Each recipe below works for any language or package manager.
1. One command for a job
run leases a machine, waits until it’s ready, pushes this folder to /project, runs the command there with its output streaming, pulls out/ back here, then releases the machine and prints how long it ran and what it cost. It exits with the command’s own code. The machine is released whatever happens: a failed command, an error, Ctrl-C or SIGTERM.
.git/,.venv/,node_modules/,.envfiles and keys are not pushed (see default excludes). A.voyagerignorefile (gitignore syntax) leaves out more, such as datasets you fetch on the machine.- Name outputs with
--pull, once per path under/project. If the command succeeded but a path isn’t there,runexits 6. run render-lite …, or--gpu L40S, picks the GPU.voyager cloud presetslists them with their price.--budget 5caps what the job may spend; add--ceiling 8to let a running command finish past $5. See Budgets.- stderr ends with
times: ready … s · code started … s · total … s. “code started” is how long it took from the command to your code running.
2. Set up once, then start from it
Install into the machine’s own disk, under/project, and save a snapshot:
snp_… id works too; voyager cloud snapshot list shows them):
- Keep what you install in the folders a snapshot saves on its own: a venv under
/project(orpip install --user), and models under/project(for exampleHF_HOME=/project/hf;~/.cacheis not saved). When only those changed, the snapshot holds just them and a machine starts from it fast. Installing withaptor the systempipmakes it save the whole disk, which starts several times slower. - Never install onto a volume at
/persist. A volume is for data and checkpoints: an environment read from it file by file is slow. See Concepts. push $m .with no destination puts the folder at/project/<folder name>.push $m . .puts it at/project, whereexecandrunstart.- When
requirements.txtchanges, set up again andsaveunder the same name:--from my-envthen starts from the new one. --fromalso takes a machine’s name: it starts from that machine’s newest snapshot, including the one it saved when it paused.- A snapshot starts on any GPU. When the GPU you ask for isn’t free, the start moves to a bigger one by itself, at the price of the one you asked for.
3. Secrets and settings
--env NAME=valuesets a variable for the command.--env-from-local NAMEsends this computer’s value ofNAMEwith the request, never on a command line here (where other users can see it in the process list). Use it for keys and tokens.- Values are never stored and never printed by
voyager cloud; only the names are kept. Don’t push.envfiles: they are excluded by default.
4. A server you want to look at
--port opens a private https://….run.voyager.computer/ link to that port before your command starts and prints it on stderr. Open it once the server is up. Press Ctrl-C to stop: the machine is released. To keep a server up across several commands, lease, run it with exec --detach, open the link with port, and release when you’re done:
--public to port for a link anyone with the address can open. Share the link only with people who should reach the port.
5. Work across several calls
For a session that needs the machine between steps (look at a result, change code, run again), keep one machine:using <machine> on stderr. With several, they list them and ask you to name one. See the current machine. A machine left idle pauses itself after 15 minutes, but release it when you’re done.
When something goes wrong
Every error is one line on stderr starting withError:, or with --json an error object with a code. The exit code says what kind:
How long it takes
Measured on 2026-11-18 withrun render-lite and a small Python project (numpy, pandas, scikit-learn). “Code running” is from the command to the first line the project printed.
Setting up the snapshot took one lease of 44 s (2.5 credits). Starting from it skips the install, so it pays off from the second run, and more so the longer the install.