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

# Remote worktree builds

> Run remote worktree builds with literal Linux arguments, inspect exit codes, and pull artifacts into a private cache.

Run remote worktree builds, tests and other Linux commands with `bead worktree exec`. Run `up` first and [prepare dependencies](https://docs.bead.run/worktrees/quickstart.md) when needed.

## Run a command

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

Arguments after `--` are literal Linux argv. Shell expressions require an explicit shell. Commands run against the synced project in `/workspace`.

The default command timeout is 21600 seconds (six hours). `--timeout` accepts 1–86400 seconds. Output streams to your terminal, and the command's exit status is preserved.

## Pull artifacts

```bash theme={null}
bead worktree exec --pull target/release/tool -- cargo build --release
```

Repeat `--pull` for additional paths. Pulls can read build-output directories such as `target/` and run even when the remote command fails.

Pull paths must stay inside `/workspace` and select regular files or directories of regular files; symlinks, protected credential paths and recognized provider credentials in contents are rejected. Each file is limited to 256 MiB and the combined artifacts to 1 GiB.

Artifacts go into a new private local cache directory outside your source tree. They do not overwrite authored files. Inspect the printed result to locate them.

Copy artifacts you want to keep out of the printed cache directory before running `bead worktree down`. Once deletion is acknowledged, `down` removes that machine’s local artifact cache.

A pull failure is separate from the remote command result. If the remote command succeeded but pulling fails, the CLI returns 125; if the command failed, its exit status remains the result.

## Recover an interrupted connection

Keep the execution ID. Read retained output without running the command again:

```bash theme={null}
bead worktree status --execution "$EXECUTION_ID"
```

See [recovery and cleanup](https://docs.bead.run/worktrees/recovery.md) for output retention and machine state.


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