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

# Run a bounded job on bead

> Run a bounded job on bead to upload a repository, provision a machine, execute work, collect results, and clean up.

Use a Git working tree as the source when you run a bounded job on bead with `bead run`. The CLI returns the remote command's exit status after cleanup, so a script can act on the result.

## Run a job

From a Git working tree:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
bead run --from base --size small --push . --timeout 900 -- \
  sh -c 'pwd && git --version'
```

`--from` is required and selects a published template or ready snapshot. `--push` defaults to the current directory. The command after `--` is literal argv; use `sh -c` when you need shell syntax.

Use a template whose default kind is temporary for this workflow: `bead run` inherits the template’s default kind. With a persistent default, the machine has no automatic deletion backstop if the CLI stops completely.

## What the command does

1. Archives tracked and non-ignored untracked files before creating a machine.
2. Creates a machine and prints its request ID and machine ID to stderr.
3. Uploads and extracts the archive into `/root/repo`.
4. Runs your command there and streams output.
5. Deletes the machine and reports its cost, or `cost_pending` when cost is not yet available.

The source archive is limited to 32 MiB. Materialize submodules explicitly before upload. Git metadata is not part of the selected source-file archive.

## Timeouts and cleanup

`--timeout` sets command execution time, defaults to 900 seconds, and accepts 1–21600 seconds. While the job runs, the CLI renews a 900-second machine deadline every 60 seconds.

Failed uploads, failed commands, timeouts, SIGINT, and SIGTERM enter cleanup. Cancellation returns 130 after cleanup. For a temporary machine, the last server deletion deadline remains active if the CLI process stops completely.

If deletion cannot be confirmed, the CLI reports an error. Inspect the printed machine ID with `bead inspect ID` and complete cleanup. See [output recovery](https://docs.bead.run/run-work/output.md).

Use [worktrees](https://docs.bead.run/worktrees/overview.md) for repeated remote builds, or [swarms](https://docs.bead.run/parallel/swarms.md) for independent shards.


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