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

# bead TOML configuration

> Write bead TOML configuration for templates, machines, preparation, sync, environment values, and services.

Define bead TOML configuration in `bead.toml` at your Git worktree root. Unknown fields are rejected. Keep secret values in [environment files or the project vault](https://docs.bead.run/worktrees/environment.md).

## Minimal configuration

```toml theme={null}
version = 1
[template]
id = "devbox"
```

## Fields

| Field | Default | Meaning |
| - | - | - |
| `version` | Required | Must be `1`. |
| `project.name` | Inferred on first up | Shared project identity; 1–48 ASCII letters, digits, `.`, `-` or `_`. |
| `machine.size` | `"medium"` | Named [machine size](https://docs.bead.run/machines/sizes.md). |
| `machine.idle_timeout` | `900` | Seconds from 300 through 86400, or `"never"`. |
| `template.id` | None | Published template ID. |
| `template.image` | None | Image pinned with `@sha256:` and a 64-character hex digest. |
| `template.dockerfile` | None | Dockerfile input for a custom build. |
| `template.context` | Dockerfile directory | Build context for a Dockerfile. |
| `template.build_size` | `"small"` | `small`, `medium` or `large`. |
| `template.build_timeout` | `720` | Build timeout from 60 through 3600 seconds. |
| `template.start_cmd` | None | Custom template start command. |
| `template.ready_cmd` | None | Custom template readiness command. |
| `prepare.run` | None | Shell command run by `bead worktree prepare`. |
| `prepare.inputs` | All selected source files | Root-relative patterns used to track preparation freshness. An empty list tracks no files. |
| `prepare.snapshot` | None | Ready prepared snapshot ID with matching shape. |
| `sync.include` | `[]` | Add safe ignored source inputs. |
| `sync.exclude` | `[]` | Exclude source inputs. |
| `env.files` | Automatic | Select dotenv files; `[]` disables laptop-file injection. |
| `service.NAME.run` | Required per service | Service shell command. |
| `service.NAME.port` | Required per service | Application port. |
| `service.NAME.env_files` | `[]` | Additional dotenv files for this service. |

Choose exactly one of `template.id`, `template.image` or `template.dockerfile`. A template ID forbids context, build, start and readiness fields. An image forbids context.

Patterns use root-relative Git wildmatch syntax. Empty patterns, leading `/` or `!`, and `..` path segments are rejected. Explicit includes cannot bypass protected-path exclusions.

Service names contain 1–32 ASCII letters, digits, `-` or `_`. Names must remain distinct after replacing `-` with `_` and uppercasing. Reserved ports are rejected.

## Add a service

```toml theme={null}
[prepare]
run = "npm ci"
inputs = ["package.json", "package-lock.json"]

[sync]
exclude = ["coverage/**"]

[env]
files = [".env.local"]

[service.web]
run = "npm run dev"
port = 3000
env_files = [".env.web"]
```

Changing the machine, template or prepared snapshot of a bound worktree requires explicit `down` followed by `up`. See [custom templates](https://docs.bead.run/templates/custom.md) and [prepared snapshots](https://docs.bead.run/worktrees/prepared-snapshots.md).


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