bead TOML configuration

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.

Minimal configuration

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

[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 and prepared snapshots.

Get started

Use cases

Connect

Run work

Set up machines and templates

Snapshots and fork

Machines

Agents and computer use

Worktrees

Fleets and swarms

Teams and organizations

Security and data

Help

bead TOML configuration

Minimal configuration

Fields

Add a service

​Minimal configuration

​Fields

​Add a service

Minimal configuration

Fields

Add a service