> ## 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 development environments for Git worktrees

> Keep editing and Git local while each worktree runs builds and services in its own cloud development environment.

Use a cloud development environment while keeping your editor, coding agent and Git on your laptop. Each Git worktree uses its own persistent bead machine for Linux builds and services.

## What runs in your remote development environment

| On your laptop | On the machine |
| - | - |
| Editor, coding agent, commits and branches | Commands, dependencies, dev servers and build outputs |
| Authoritative source files and dotenv files | Synced source at `/workspace` and injected process environment |

Tools installed on your laptop are not available remotely. Use macOS or Linux. On WSL2, use the Linux CLI and keep the checkout in the Linux filesystem. Native Windows is unsupported.

## Your local files are authoritative

Managed execution syncs selected source files before it runs. Sync is one way: remote edits are not merged into your local files. Guest-only caches and build outputs survive sync. Use [artifact pulls](https://docs.bead.run/worktrees/exec.md) to retrieve outputs separately.

Git stays local. The guest has an initialized Git repository and files, without your Git history. Use `BEAD_GIT_COMMIT` and `BEAD_GIT_BRANCH` for version stamping.

## Worktree isolation

`bead worktree up` creates or recovers the binding. `prepare` reconciles dependencies explicitly. `exec` runs a command; `dev` runs a declared service and forwards localhost traffic.

Active commands and services keep compute billed. Idle pause preserves state and bills storage. `down` deletes the bound machine; templates and prepared snapshots have separate lifetimes.

Start with [Set up a worktree](https://docs.bead.run/worktrees/quickstart.md), then read [configuration](https://docs.bead.run/worktrees/configuration.md) and [recovery](https://docs.bead.run/worktrees/recovery.md).


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