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

# Worktree environment secrets

> Configure worktree environment secrets with laptop env files or scoped vault values and understand their precedence.

Set worktree environment secrets with project vault values, service vault values and laptop dotenv files. Values enter the process environment; bead does not write a guest dotenv file.

## Select laptop files

Gitignored root `.env*` files inject automatically into ordinary worktree commands. Narrow the list in `bead.toml`:

```toml theme={null}
[env]
files = [".env.local"]

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

Set `files = []` to disable automatic laptop-file injection. Service `env_files` add files for that service. Files must be ignored, untracked regular files inside the worktree. Each file and the combined decoded values are limited to 64 KiB. Values are literal: expansion and command substitution are unsupported. Keys must be ASCII identifiers starting with a letter or underscore and contain at most 256 characters. The `BEAD_`, `LD_` and `DYLD_` prefixes and `PATH`, `NODE_OPTIONS`, `BASH_ENV` and `ENV` are reserved.

## Import into the project vault

For a teammate or cloud agent without your laptop files:

```bash theme={null}
bead env import .env.local
bead env import .env.web --service web
bead env ls
bead env unset DATABASE_URL --service web
```

The command uses the committed project name, or infers the name that first `up` writes. Use `--project NAME` to select it explicitly. A service import applies only to that service's `dev` invocation.

Stored values use the encrypted vault. `env ls` prints names only. The dashboard groups names by project and service and lets you delete them; import values through the CLI.

## Precedence and retention

Values apply in this order, with later values winning: project vault, service vault, laptop files. Projects cannot receive another project's values.

Automatic root dotenv files load alphabetically; explicit `env.files` load in listed order, followed by the service’s `env_files`, with later files overriding earlier values. The final project-vault, service-vault and laptop environment is limited to 64 KiB in total.

Keep production secrets out of the development vault. Keep values out of arguments and logs. Ordinary machine checkpoints can retain values, files and process heaps; deleting a laptop file does not erase an existing checkpoint. [Prepared snapshots](https://docs.bead.run/worktrees/prepared-snapshots.md) exclude laptop environment injection.


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