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

# Cloud worktree setup

> Complete cloud worktree setup with bead.toml, prepare dependencies, run a remote command, and bring the worktree down.

Complete cloud worktree setup to run builds on a private Linux machine while you keep editing locally.

## Before you start

[Install bead](https://docs.bead.run/installation.md), [sign in](https://docs.bead.run/agent-signup.md), and check `bead balance`. Run these commands from your Git worktree root. Choose a published template with the tools your project needs; `devbox` is the example below.

## Configure your project

Create `bead.toml`:

```toml theme={null}
version = 1

[template]
id = "devbox"

[machine]
size = "medium"
idle_timeout = 900

[prepare]
run = "cargo fetch"
inputs = ["Cargo.lock", "Cargo.toml"]
```

Use your project's dependency setup command in `prepare.run`. For a JavaScript project, that might be `npm ci` with `package-lock.json` and `package.json` as inputs.

## Bring it up

```bash theme={null}
bead worktree up
bead worktree prepare
bead worktree exec -- cargo check
```

Keep the printed machine ID. The first `up` writes a shared project name into `bead.toml`; commit the configuration through your normal workflow. Preparation runs only when you request it. A stale preparation warning means you should run `prepare` again.

Arguments after `--` are literal Linux arguments. Use a shell explicitly for pipelines or compound commands:

```bash theme={null}
bead worktree exec -- sh -lc 'cargo check && cargo test'
```

## Finish the branch

```bash theme={null}
bead worktree status
bead worktree down
```

Confirm that destruction is acknowledged. See [services](https://docs.bead.run/worktrees/services.md) for dev servers and [recovery](https://docs.bead.run/worktrees/recovery.md) if a connection ends before you receive the result.


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