> ## 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.

# Cloud machines quickstart

> Install the voyager-cloud CLI, sign in, lease a GPU, run a command, copy files and release the machine in five minutes.

When you finish, you'll have run a command on a Voyager cloud GPU and released it.

> [!NOTE]
>
> **Before you start:** a paid Voyager workspace (Starter or above). The machine bills Voyager credits by the minute until you release it; this quickstart takes a few minutes on `render-lite`, the cheapest preset.

**1. Install the CLI**

> [tab] macOS / Linux
>
> ```sh theme={"system"}
> curl -fsSL https://voyager.so/cloud/install.sh | sh
> ```
>
> It installs `voyager-cloud` for your user (no `sudo`) and checks the download against its published checksum.

> [tab] Windows (PowerShell)
>
> ```powershell theme={"system"}
> irm https://voyager.so/cloud/install.ps1 | iex
> ```

Check it: `voyager-cloud --version`. Later, `voyager-cloud update` updates it.

**2. Sign in**

```sh theme={"system"}
voyager-cloud login
```

Your browser opens; sign in with your Voyager account. Check who you are and which workspace pays with `voyager-cloud whoami` (switch with `voyager-cloud whoami --workspace <workspace>`).

On a server or in CI, set `VOYAGER_API_KEY` to an API key from [voyager.so/dashboard/api](https://voyager.so/dashboard/api) instead, or run `voyager-cloud login --key`, which reads it from that variable. Credentials are kept in one private file in your user config folder, never in the system keychain. `voyager-cloud logout` signs out and revokes them.

**3. Lease a machine**

```sh theme={"system"}
voyager-cloud lease render-lite --name first-try --wait
```

`--wait` returns once the machine is `ready`, usually within a couple of minutes. Note its id (`mch_…`); the commands below take the id or the name.

**4. Run a command**

```sh theme={"system"}
voyager-cloud exec first-try -- nvidia-smi
```

`exec` waits, streams the output and exits with the command's exit code, so scripts and agents can check it. Everything after `--` runs on the machine.

**5. Move files**

```sh theme={"system"}
mkdir -p hello && echo "hi from my laptop" > hello/note.txt
voyager-cloud push first-try hello/
voyager-cloud exec first-try -- sh -c 'cat hello/note.txt > hello/reply.txt; echo "and from the GPU" >> hello/reply.txt'
voyager-cloud pull first-try hello/reply.txt
cat reply.txt
```

`push` skips files that haven't changed, so pushing the same folder again is quick.

**6. Release it**

```sh theme={"system"}
voyager-cloud release first-try
```

Release prints what the machine cost. It stops billing straight away.

## Check it worked

`voyager-cloud list` shows your machine as `released`, with its cost. If you forget to release a machine, it pauses itself after 15 minutes idle; it doesn't bill for the GPU while paused, but release it when you're done.

## Commands

Every command takes `--json`, which prints the API's objects unchanged, so scripts and agents can read every field.

| Command | What it does |
| - | - |
| `voyager-cloud login` / `logout` / `whoami` | Sign in, sign out, show the account and workspace |
| `voyager-cloud presets` / `gpus` / `images` | What you can lease, with prices |
| `voyager-cloud lease [preset] [--gpu] [--name] [--idle-timeout] [--wait]` | Lease a machine |
| `voyager-cloud list` | Your machines |
| `voyager-cloud status <machine> [--wait]` | One machine, its status and cost so far |
| `voyager-cloud exec [--detach] <machine> -- <command…>` | Run a command; waits and streams output unless `--detach` |
| `voyager-cloud wait <job>` / `logs <job> [--follow]` / `cancel <job>` | Follow a detached job |
| `voyager-cloud push <machine> <local> [remote]` | Copy files or a folder to the machine |
| `voyager-cloud pull <machine> <remote> [local]` | Copy files or a folder back |
| `voyager-cloud port <machine> <port>` | Open a port at an `https://…run.voyager.computer/` link anyone with it can reach |
| `voyager-cloud snapshot <machine>` | Save the machine's disk |
| `voyager-cloud pause` / `resume` / `release <machine>` | Stop billing for now, come back, or finish |
| `voyager-cloud help` / `help vork` | Help, and the Vork guide for agents |
| `voyager-cloud update` / `--version` | Update the CLI, show its version |

Environment: `VOYAGER_API_KEY` (use a key instead of signing in) and `VOYAGER_API_URL` (default `https://api.voyager.so`).

## If something went wrong

> [accordion] Access refused: needs a paid plan
>
> Cloud machines need a paid workspace, Starter or above, with a completed payment. The error includes the billing link; owners and admins can upgrade at [voyager.so/dashboard/billing](https://voyager.so/dashboard/billing). If you belong to more than one workspace, check `voyager-cloud whoami` shows the one with the plan.

> [accordion] `voyager-cloud: command not found` after installing
>
> Open a new terminal so it picks up the install folder, or add the folder the installer printed to your `PATH`.

> [accordion] The lease takes a long time or fails
>
> GPUs are sometimes all in use. `failed` machines don't bill. Try again, or lease another preset (`render-lite` is often free sooner).

## Next

> [card] [Machines and cost](https://docs.voyager.so/api/machines/machines.md)
>
> Leasing options, pausing, snapshots and what a machine costs.

> [card] [Render with Vork](https://docs.voyager.so/api/machines/vork.md)
>
> The render loop for Vork scenes.


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