---
title: "lanes in devlanes.yaml"
url: https://devlanes.run/docs/reference/config/project/lanes/
description: "Reference for the lanes key in devlanes.yaml."
---

# lanes in devlanes.yaml

A top-level key of [`devlanes.yaml`](/docs/reference/config/project/).

## `lanes`

Type: mapping.

Which worktrees get a lane, how many ports each lane reserves, and values computed per lane (`lane.<name>`).

```yaml devlanes
lanes:
  hosts_file: always
  primary: main
  vars:
    db_name: acme_${{ lane.name }}
```

### `lanes.block_size`

Type: integer or an [expression](/docs/reference/expressions/).

Number of ports reserved for each lane. By default devlanes counts the ports the config needs and adds half again, rounded up to ten. A fixed size smaller than what the config needs is an error.

```yaml devlanes
lanes:
  block_size: 80
```

### `lanes.hosts_file`

Type: string.

Whether this project's hostnames are also written to `/etc/hosts`, for programs that cannot resolve `*.localhost` by themselves (Wrangler's workerd, musl or pure-Go binaries). Overrides the user's `hostnames.hosts_file` (default `auto`), except that a user `never` always wins. Writing needs the helper `devlanes setup` installs, and only exact names are written, never wildcards.

Values:

- `auto`: Write the exact hostnames only when the daemon's startup check finds that the system resolver does not answer `*.localhost` with a loopback address.
- `never`: Never write hostnames to `/etc/hosts`. Set in the user config, it applies to every project whatever the project sets.
- `always`: Always write the exact hostnames, even when the system resolver handles `*.localhost`, for programs that send `*.localhost` to DNS themselves.

```yaml devlanes
lanes:
  hosts_file: auto
```

### `lanes.matrix`

Type: list of mappings of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Fixed values per lane instead of computed `vars`: entry N holds lane N's values, read as `lane.<name>`. A lane whose index has no entry fails to resolve. Cannot be combined with `vars`.

```yaml devlanes
lanes:
  matrix:
    - domain: acme.localhost
      port: 20000
    - domain: acme1.localhost
      port: 20100
```

### `lanes.max`

Type: integer or an [expression](/docs/reference/expressions/).

Most lanes the project may hold at once; further worktrees stay unassigned, without ports. Lowering it keeps existing lanes. Unset, the number of lanes is limited only by free port blocks.

```yaml devlanes
lanes:
  max: 6
```

### `lanes.new_worktrees`

Type: string.

What devlanes does when a worktree gets its lane: only reserve it, also set it up, or also start it. Defaults to `register`. A worktree gets a lane the first time `start`, `status` or another command that acts on lanes runs in it, not merely because it exists.

Values:

- `register`: Only reserve the lane (its index, port block and domain); nothing runs until the lane is started.
- `setup`: Also run infrastructure setup and `lane.create` tasks, leaving services stopped.
- `start`: Also start the lane with the default profile.

```yaml devlanes
lanes:
  new_worktrees: register
```

### `lanes.primary`

Type: string.

Branch whose worktree is lane 0, the main lane (`lanes.main` in expressions) and the only worktree that gets a lane by itself. Defaults to the remote's default branch, else `main` or `master`. In CI (a variable such as `CI` or `GITHUB_ACTIONS` is set) the checkout takes lane 0 on any branch when lane 0 is free.

```yaml devlanes
lanes:
  primary: main
```

### `lanes.removed_worktrees`

Type: string.

What happens to a lane whose worktree folder is deleted, for example by `git worktree remove` after a merge. Defaults to `stop`, which stops its processes and keeps its data, containers and ports until `devlanes lane gc --yes` or `devlanes lane clean` removes them. Set `clean` to have devlanes clean the lane by itself.

Values:

- `stop`: Stop the lane's processes and keep the lane: its data folder, containers, index and ports stay until `devlanes lane gc --yes` or `devlanes lane clean` removes them.
- `clean`: Clean the lane by itself: stop its processes, remove its own containers and data folder, and free its index and ports. An idle lane is cleaned once its folder has been gone for 5 seconds, so `git worktree move` keeps it. Its logs stay until log retention removes them. `lane.clean` tasks and `infra.teardown` need the folder to run in, so they are skipped; data they would drop from shared containers stays.

```yaml devlanes
lanes:
  removed_worktrees: stop
```

### `lanes.vars`

Type: mapping of names to strings, booleans, numbers or [expressions](/docs/reference/expressions/).

Values computed for each lane and read as `${{ lane.<name> }}`, such as a database name, vhost, bucket or Redis index per lane. Build names from `${{ lane.name }}`, which is `main` in lane 0 and `lane<N>` in lane N whatever the branch, and numbers from `${{ lane.index }}`. A var named `domain` replaces the default lane domain, and one named `port` fixes where the lane's port block starts. `${{ domain('pages') }}` gives a name a site of its own in each lane, such as `pages2.localhost` in lane 2. Cannot be combined with `matrix`.

```yaml devlanes
lanes:
  vars:
    db_name: acme_${{ lane.name }}
```
