--- title: "Config reference" url: https://devlanes.run/docs/reference/config/ description: "Every field of devlanes.yaml and of the per-user config.yaml, generated from the JSON Schemas devlanes publishes." updated: 2026-11-02T00:53:29.000Z --- # Config reference Every field of `devlanes.yaml` and of the per-user `config.yaml`, generated from the JSON Schemas devlanes publishes. In a path, `` stands for a key you choose (a service, task or profile name) and `[]` for an item of a list. A type marked *templated* also accepts a `${{ ... }}` expression, evaluated for each lane. A *duration* is a number with `ms`, `s`, `m`, `h` or `d`, and a *scalar* is a string, number or boolean. [examples/devlanes.yaml](https://github.com/devlanes-run/devlanes/blob/3afa327903b6275d80d44ea599d8b71b274abc95/docs/examples/devlanes.yaml) shows the fields in context. ## Project config `devlanes.yaml` at the repository root or in a subdirectory; devlanes uses the nearest one above the current directory, up to the repository root. Another project file in the same directory, such as `devlanes.prod.yaml`, is named once with `--file`. Each project file can have local overrides in a `.local.yaml` next to it. Schema: `https://devlanes.run/v1/schema.json`. ### extends | Path | Type | Description | Example | | --- | --- | --- | --- | | `extends` | string or list of string | Other project files this one builds on: one path or a list, relative to this file, such as `devlanes.yaml` for a `devlanes.prod.yaml` that runs the same apps another way. They are merged in order, each with its own `.local.yaml`, then this file and its `.local.yaml` go last, so later files win. Mappings merge by key and lists and single values replace, as with local overrides. An extended file may be partial and its `project` is ignored; paths in it mean what they would in this file. | `devlanes.yaml` | ### global_env | Path | Type | Description | Example | | --- | --- | --- | --- | | `global_env` | map of scalar (templated) | Variables for every service and task of the lane, above devlanes' own variables (`PORT`, `DEVLANES_*`) and below each unit's `env` and the profile's `env`. Use it for values many units share, such as a database URL built from `${{ infra.postgres.port }}`. Never set `PORT` here: it would replace every service's own port. | `{"API_URL":"${{ services.api.url }}"}` | ### infra | Path | Type | Description | Example | | --- | --- | --- | --- | | `infra` | object | Containers the lanes depend on (databases, brokers, object stores), started and waited on before setup, tasks and services, plus the commands that create and remove each lane's data in them. | `{"compose":"docker-compose.yml","hidden":["postgres"]}` | | infra.compose | string or list of string | Compose file, or a list of files merged like repeated `-f`, relative to the project. Its services are shared by every lane unless listed in `per_lane`; the shared project runs from the primary worktree with that worktree's `.env` as `--env-file`. | `docker-compose.yml` | | infra.containers | map of object | Docker containers run without a Compose file, keyed by name and reached as `infra.` in expressions. | `{"cerbos":{"image":"ghcr.io/cerbos/cerbos:0.40.0","per_lane":true,"ports":{"http":3592}}}` | | infra.containers..command | string (templated) or list of string (templated) | Command replacing the image's default: a list is used as is, a string runs through `/bin/sh -c` inside the container. | `["server","--config=/policies/config.yaml"]` | | infra.containers..env | map of scalar (templated) | Environment variables set inside the container. | `{"LOG_LEVEL":"debug"}` | | infra.containers..image | string (templated) | Image to run. Required. A running container with the same image, command, env, mounts and ports is reused; any change recreates it. | `ghcr.io/cerbos/cerbos:0.40.0` | | infra.containers..per_lane | boolean (templated) | Run one container per lane instead of one shared by every lane. Defaults to false. Per-lane containers and their named volumes are removed by `devlanes lane clean`. | `true` | | infra.containers..ports | map of integer (templated) | Container ports by name. devlanes publishes each on a host port on 127.0.0.1, read as `${{ infra..ports. }}`; `infra..port` is the first one. | `{"grpc":3593,"http":3592}` | | infra.containers..ready | `started` or object | Extra check the start waits for once the container is up (the image's healthcheck, else its first port accepting TCP), before setup, tasks and services run. Write `started` or one of `tcp`, `http`, `log` (matched against the container's logs) or `cmd` (run on the host). If it does not pass within its timeout (default 60s), the start fails. Values: `started`: Count the unit ready as soon as it runs, without probing anything. A dev server whose program crashed under a file watcher still counts as ready, so prefer a check when there is something to probe. | `started` | | infra.containers..ready.cmd | string (templated) or list of string (templated) | Ready once this command exits 0. It runs on the host through `/bin/sh` (a list is quoted into one command line) with its output discarded, is retried until the timeout, and each attempt is cut off after 10 seconds. For a service it gets the service's environment and working directory. | `curl -fsS ${{ self.url }}/healthz` | | infra.containers..ready.http | object | Ready once a GET request to `path` on the unit's main port answers with `status`, or with a 2xx status when `status` is unset. Redirects are not followed. Best when the app has a health route that fails while it is broken. Each request sends `User-Agent: devlanes-ready`, so an app can leave the checks out of its request logs. | `{"path":"/healthz","status":200,"timeout":"60s"}` | | infra.containers..ready.http.host | string (templated) | Host header the check sends, for apps that answer only on their own hostname, such as `${{ self.hosts[0] }}`. The request still goes to 127.0.0.1; only the header changes. Defaults to `127.0.0.1:`. Spaces and control characters are refused. | `${{ self.hosts[0] }}` | | infra.containers..ready.http.path | string (templated) | Path requested with GET, such as `/healthz`; defaults to `/`. | `/healthz` | | infra.containers..ready.http.status | integer (templated) | Status code that counts as ready, between 100 and 599; only that exact code passes. When unset, any status from 200 to 299 counts, so a 404 or a redirect keeps waiting (redirects are not followed). Set it to accept another code, such as `302` for a route that redirects to a login. | `200` | | infra.containers..ready.http.timeout | duration (templated) | How long the HTTP check may take to pass, replacing the check's `timeout`; defaults to 60s. When it runs out, a service is marked failed but keeps running, and for an infra container the start fails. | `15s` | | infra.containers..ready.log | string (templated) | Ready once a line of output matches this regular expression, with colors and other terminal escape codes removed; recent lines printed before the check began count too. Suits workers without a port: have them print a line once connected. | `Connected to Redis` | | infra.containers..ready.tcp | boolean or string | Ready once a port accepts a TCP connection on 127.0.0.1 or ::1, tried every 150 ms. `true` uses the unit's main port; a port name such as `inspector` uses that named port. It only proves the socket is open, not that the app works. | `true` | | infra.containers..ready.timeout | duration (templated) | How long the check may take to pass; defaults to 60s. When it runs out, a service is marked failed (its process keeps running and is not restarted) and `after: services` tasks are skipped; for an infra container the start fails. Raise it for services that compile before they listen. | `15s` | | infra.containers..volumes | list of string (templated) | Mounts as `source:destination[:mode]`. `./relative` and `/absolute` sources are bind mounts, relative ones from the owning worktree; a bare name is a named volume kept per project or per lane. | `["./infra/cerbos:/policies:ro"]` | | infra.env | map of scalar (templated) | Variables for `${VAR}` interpolation in the Compose files only; processes do not see them (use `global_env` for those). | `{"ACME_DB_PORT":15432}` | | infra.exclude | list of string | Compose services devlanes never starts, such as a local reverse proxy the devlanes proxy replaces. | `["caddy"]` | | infra.external | map of object | Servers you run yourself on a loopback port, such as pgAdmin, keyed by name. Every lane lists them, the proxy routes their hostnames, and machines connected with `devlanes remote connect` mirror them while a lane of the project runs. devlanes never starts or checks them. Put personal ones in `devlanes.local.yaml`. | `{"pgadmin":{"address":"127.0.0.1:5050","hosts":"pgadmin.${{ lane.domain }}"}}` | | infra.external..address | string | Where the server listens, `127.0.0.1:` or `[::1]:`. Only loopback addresses work. A port that devlanes or a lane already uses is an error. Required. | `127.0.0.1:5050` | | infra.external..hidden | boolean | Keep the entry away from machines connected with `devlanes remote connect`. They never see, mirror or reach it. This machine still routes its hostnames. Defaults to false. | `false` | | infra.external..hosts | string (templated) or object or list of string (templated) or object | Hostnames the devlanes HTTPS proxy routes to the port. One entry or a list. An entry is a hostname, or a mapping with `host` and optional `fallback` and `host_header`. Expressions can use `lane`, `project`, `infra` and `env`. Put the names under `${{ lane.domain }}` so each lane gets its own. The first host without a wildcard becomes the unit's URL. | `pgadmin.${{ lane.domain }}` | | infra.external..hosts.fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Defaults to false. | `true` | | infra.external..hosts.host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself. Quote it in YAML. Labels hold letters, digits and inner hyphens. Case and a trailing dot are ignored. | `pgadmin.${{ lane.domain }}` | | infra.external..hosts.host_header | `preserve` or `upstream` | Host header the server receives. Defaults to `preserve`, the hostname the browser asked for. `upstream` sends the address devlanes connects to, such as `127.0.0.1:5050`, for servers that only accept their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | infra.external..hosts[].fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Defaults to false. | `true` | | infra.external..hosts[].host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself. Quote it in YAML. Labels hold letters, digits and inner hyphens. Case and a trailing dot are ignored. | `pgadmin.${{ lane.domain }}` | | infra.external..hosts[].host_header | `preserve` or `upstream` | Host header the server receives. Defaults to `preserve`, the hostname the browser asked for. `upstream` sends the address devlanes connects to, such as `127.0.0.1:5050`, for servers that only accept their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | infra.hidden | list of string | Containers that machines connected with `devlanes remote connect` never see, mirror or reach. | `["postgres"]` | | infra.hosts | map of string (templated) or object or list of string (templated) or object | HTTPS hostnames for containers, keyed by Compose service or plain container name, so a browser can open a container's web port: a MinIO console or presigned S3 URLs, Mailpit, a mock OIDC provider. A hostname routes to the container's first published port unless its route sets `port`; each key takes one hostname or route, or a list. | `{"s3mock":"s3.${{ lane.domain }}"}` | | infra.hosts..fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Typical for `*.${{ lane.domain }}` on a gateway that should answer every subdomain other services do not claim. Defaults to false. | `true` | | infra.hosts..host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored. | `api.${{ lane.domain }}` | | infra.hosts..host_header | `preserve` or `upstream` | Host header the unit receives. Defaults to `preserve`, the hostname the browser asked for; `upstream` sends the local address, such as `127.0.0.1:`, for servers that reject or misroute requests for a Host that is not their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | infra.hosts..port | string | Send this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in `self.ports.`, and naming it here allocates that port; in `infra.hosts` it is the container port for Compose services, or the port's name for plain containers. | `inspector` | | infra.hosts.[].fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Typical for `*.${{ lane.domain }}` on a gateway that should answer every subdomain other services do not claim. Defaults to false. | `true` | | infra.hosts.[].host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored. | `api.${{ lane.domain }}` | | infra.hosts.[].host_header | `preserve` or `upstream` | Host header the unit receives. Defaults to `preserve`, the hostname the browser asked for; `upstream` sends the local address, such as `127.0.0.1:`, for servers that reject or misroute requests for a Host that is not their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | infra.hosts.[].port | string | Send this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in `self.ports.`, and naming it here allocates that port; in `infra.hosts` it is the container port for Compose services, or the port's name for plain containers. | `inspector` | | infra.per_lane | list of string | Compose services run once per lane instead of shared, each in its own Compose project with ports from the lane's block and its own named volumes, removed by `devlanes lane clean`. Needs Compose 2.24.4 or newer. | `["mailpit"]` | | infra.profiles | list of string | Compose profiles to enable when resolving and starting the Compose services. | `["development"]` | | infra.project_name | string (templated) | Name of the shared Compose project, fixed so `docker compose -p ` reaches the same containers outside devlanes. Defaults to the name Compose picks itself. | `acme` | | infra.setup | map of object or string (templated) or list of string (templated) | Named commands that prepare each lane's data, such as creating its database in a shared Postgres. They run once per lane after the containers are ready, all at the same time, and are recorded as done so later starts skip them; a failure stops the start unless the entry sets `ignore_errors`. | `{"database":"docker compose exec -T postgres createdb acme_${{ lane.name }}"}` | | infra.setup..container | string | Run this setup entry again whenever the named container has restarted since it last ran, for data that lives in the container and may be gone, such as a RabbitMQ vhost. | `rabbitmq` | | infra.setup..cwd | string (templated) | Working directory, relative to the project file's directory in the lane's worktree; defaults to that directory. | `infra` | | infra.setup..env | map of scalar (templated) | Variables for this command only. | `{"AWS_DEFAULT_REGION":"us-east-1"}` | | infra.setup..ignore_errors | boolean (templated) | Count a failed or timed-out command as done instead of failing the start, for commands whose "already exists" error is fine. Defaults to false. | `true` | | infra.setup..run | string (templated) or list of string (templated) | Command to run: a string runs through `/bin/sh -c`, a list runs the program directly. Write the command you mean, such as `docker compose exec -T postgres ...`; devlanes runs it as written. Required. | `pnpm dev` | | infra.setup..timeout | duration (templated) | Longest the command may run. When it runs out, the command is stopped (SIGTERM, then SIGKILL after 10 seconds) and counts as failed, so a setup entry fails the start unless `ignore_errors` is set. No limit by default. | `15s` | | infra.teardown | map of object or string (templated) or list of string (templated) | Named commands that remove a lane's data when the lane is cleaned (`devlanes lane clean`), one after another; never on stop. A failure is reported and the cleanup goes on. | `{"database":"docker compose exec -T postgres dropdb --if-exists acme_${{ lane.name }}"}` | | infra.teardown..container | string | Run this setup entry again whenever the named container has restarted since it last ran, for data that lives in the container and may be gone, such as a RabbitMQ vhost. | `rabbitmq` | | infra.teardown..cwd | string (templated) | Working directory, relative to the project file's directory in the lane's worktree; defaults to that directory. | `infra` | | infra.teardown..env | map of scalar (templated) | Variables for this command only. | `{"AWS_DEFAULT_REGION":"us-east-1"}` | | infra.teardown..ignore_errors | boolean (templated) | Count a failed or timed-out command as done instead of failing the start, for commands whose "already exists" error is fine. Defaults to false. | `true` | | infra.teardown..run | string (templated) or list of string (templated) | Command to run: a string runs through `/bin/sh -c`, a list runs the program directly. Write the command you mean, such as `docker compose exec -T postgres ...`; devlanes runs it as written. Required. | `pnpm dev` | | infra.teardown..timeout | duration (templated) | Longest the command may run. When it runs out, the command is stopped (SIGTERM, then SIGKILL after 10 seconds) and counts as failed, so a setup entry fails the start unless `ignore_errors` is set. No limit by default. | `15s` | ### lanes | Path | Type | Description | Example | | --- | --- | --- | --- | | `lanes` | object | Which worktrees get a lane, how many ports each lane reserves, and values computed per lane (`lane.`). | `{"hosts_file":"always","primary":"main","vars":{"db_name":"acme_${{ lane.name }}"}}` | | lanes.block_size | integer (templated) | 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. | `80` | | lanes.hosts_file | `auto` or `never` or `always` | 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. | `auto` | | lanes.matrix | list of map of scalar (templated) | Fixed values per lane instead of computed `vars`: entry N holds lane N's values, read as `lane.`. A lane whose index has no entry fails to resolve. Cannot be combined with `vars`. | `[{"domain":"acme.localhost","port":20000},{"domain":"acme1.localhost","port":20100}]` | | lanes.max | integer (templated) | 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. | `6` | | lanes.new_worktrees | `register` or `setup` or `start` | 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 devlanes 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. | `register` | | lanes.primary | 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. | `main` | | lanes.removed_worktrees | `stop` or `clean` | 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. | `stop` | | lanes.vars | map of scalar (templated) | Values computed for each lane and read as `${{ lane. }}`, such as a database name, vhost, bucket or Redis index per lane. 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`. | `{"db_name":"acme_${{ lane.name }}"}` | ### profiles | Path | Type | Description | Example | | --- | --- | --- | --- | | `profiles` | map of list of string or object | Named selections of services for `devlanes start --profile `. A plain `devlanes start` brings back what the lane ran before; `default` is used when there is nothing to bring back, such as after `devlanes stop`. A profile is a list of names, globs and `+tag` selectors, or a mapping that can also exclude services, skip infra, add `env` and remap script names. | `{"default":["+api","+web"],"e2e":{"include":["*"],"run_scripts":{"dev":"start"}}}` | | profiles..env | map of scalar (templated) | Variables for the services this profile starts, above their own `env`. | `{"NODE_ENV":"production"}` | | profiles..exclude | list of string | Services removed from the `include` selection, by name, glob or `+tag`. | `["+desktop","sms-stub"]` | | profiles..include | list of string | Services this profile starts: names, globs such as `crm-*`, and `+tag` selectors. Globs skip services with `autostart: false`; names and tags include them. | `["+api","+web"]` | | profiles..infra | boolean (templated) | Set false to skip containers and `infra.setup`, for example to run only a frontend against another lane's backend. Services that reference `infra.*` then fail to resolve. With several profiles active, infra is skipped only when all of them set false. Defaults to true. | `false` | | profiles..run_scripts | map of string | Swap script names for services that use `run_script`: `{ dev: start }` runs the `start` script wherever a service's `run_script` names `dev`. The file stays the same, and each name is swapped once, not chained. | `{"dev":"start"}` | ### project | Path | Type | Description | Example | | --- | --- | --- | --- | | `project` | string | Project name, the same in every worktree of the repository. It builds each lane's default domain (`.localhost` for lane 0, `.localhost` for lane N), names lanes in commands (`acme@2`), the containers devlanes creates and `DEVLANES_LANE_PROJECT`, and other projects reach this one as `projects.`. Lowercase letters, digits, dots, underscores and dashes. | `acme` | ### services | Path | Type | Description | Example | | --- | --- | --- | --- | | `services` | map of object | Long-running processes of each lane, started together after infrastructure, setup and `lane.start` tasks. Each service gets its own port as `PORT` and, with `hosts`, HTTPS hostnames. A service that exits shows as failed and is not restarted. | `{"api":{"hosts":"api.${{ lane.domain }}","run_script":{"file":"apps/api/package.json","name":"dev"}}}` | | services..autostart | boolean (templated) | Set false for an on-demand service: a plain `devlanes start` without a `default` profile skips it unless the lane ran it before, and so do globs such as `*` in profiles. Naming it or its `+tag`, on the command line or in a profile, still starts it. An expression is evaluated for each lane and acts like the `true` or `false` it gives, such as `${{ lane.index == 0 }}` to autostart only in the main lane. With `replicas`, the service starts all its copies when any copy's expression gives true. Defaults to true. | `true` | | services..cwd | string (templated) | Directory `run` starts in, relative to the project file's directory in the lane's worktree; defaults to that directory. Platform detection also looks here. Cannot be combined with `run_script`, which runs in the script file's directory; `devlanes config check` refuses the pair, including a `cwd` inherited through `extends`. | `apps/api` | | services..env | map of scalar (templated) | Environment variables for this service's process. They override `global_env` and are overridden by the active profile's `env` and `--env`; values may be text, numbers, booleans or `${{ ... }}` expressions. Setting `PORT` replaces the port devlanes allocated; a literal number is the same in every lane, so lanes collide. | `{"API_URL":"${{ services.api.url }}"}` | | services..extends | string | Template under `templates` whose settings this service inherits; its own settings apply on top. Mappings (`env`, `ready`, `stop`, preset options, `run_script`) merge by key, lists (`tags`, `hosts`, `sync`) and single values replace. Setting `run` or `run_script` drops the inherited other one, and one `ready` probe (`tcp`, `http`, `log`, `cmd`) drops the inherited probe. Templates may extend other templates and are resolved after every project file and local override is merged. | `fastify-api` | | services..hidden | boolean (templated) | Keep this service away from machines connected with `devlanes remote connect`. They never see, mirror or reach it, and do not get its `sync` folders. It still runs on this machine. Defaults to false. | `false` | | services..hosts | string (templated) or object or list of string (templated) or object | Hostnames the devlanes HTTPS proxy routes to this service, so `https://` reaches it. One entry or a list; an entry is a hostname or a mapping with `host` and optional `port` (a named port), `fallback` and `host_header`. A `*.` wildcard matches subdomains, and an exact host wins over it. The first non-wildcard host becomes `public_url`, non-wildcard hosts join the lane's `DEVLANES_ORIGINS`, and having hosts makes the default `ready` a TCP check. Keep them under `${{ lane.domain }}` so lanes do not collide. | `api.${{ lane.domain }}` | | services..hosts.fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Typical for `*.${{ lane.domain }}` on a gateway that should answer every subdomain other services do not claim. Defaults to false. | `true` | | services..hosts.host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored. | `api.${{ lane.domain }}` | | services..hosts.host_header | `preserve` or `upstream` | Host header the unit receives. Defaults to `preserve`, the hostname the browser asked for; `upstream` sends the local address, such as `127.0.0.1:`, for servers that reject or misroute requests for a Host that is not their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | services..hosts.port | string | Send this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in `self.ports.`, and naming it here allocates that port; in `infra.hosts` it is the container port for Compose services, or the port's name for plain containers. | `inspector` | | services..hosts[].fallback | boolean (templated) | Make this route a catch-all: it is used only when no other route, exact or wildcard, matches the requested hostname. Typical for `*.${{ lane.domain }}` on a gateway that should answer every subdomain other services do not claim. Defaults to false. | `true` | | services..hosts[].host | string (templated) | Hostname to route, evaluated for each lane. A leading `*.` makes a wildcard that matches any depth below it but not the name itself; quote it in YAML. Labels hold letters, digits and inner hyphens; case and a trailing dot are ignored. | `api.${{ lane.domain }}` | | services..hosts[].host_header | `preserve` or `upstream` | Host header the unit receives. Defaults to `preserve`, the hostname the browser asked for; `upstream` sends the local address, such as `127.0.0.1:`, for servers that reject or misroute requests for a Host that is not their own address. Values: `preserve`: Send the hostname the client requested, such as `api.acme2.localhost`. `upstream`: Send the local address and port the proxy connects to, such as `127.0.0.1:`. | `preserve` | | services..hosts[].port | string | Send this hostname to one of the unit's named ports instead of its main port. For a service it is a port name as in `self.ports.`, and naming it here allocates that port; in `infra.hosts` it is the container port for Compose services, or the port's name for plain containers. | `inspector` | | services..keep_awake | boolean (templated) | While this service runs, devlanes never throttles or freezes its lane, whatever `lanes.throttle_after` and `lanes.freeze_after` in the user config say. Set it on workers, queue consumers, schedulers and tunnels that do work without inbound requests, which a frozen lane would otherwise stall. One such service keeps the whole lane awake. An expression is evaluated for each lane, such as `${{ lane.index == 0 }}` to keep only the main lane awake. Defaults to false. | `true` | | services..name | string | Label shown in the TUI and human output instead of the service key; any text, spaces allowed, with ` #N` added per replica. Commands, profiles and `${{ services. }}` keep using the key. | `Admin API` | | services..next | object | Options for `preset: next`, which adds `--port --hostname 127.0.0.1` to the `next dev` command. Without the hostname flag Next listens on `0.0.0.0` instead of loopback. | `{"args":["--turbopack"]}` | | services..next.args | list of string | Extra arguments for `next dev`, added after the preset's port and hostname flags, for example `[--turbopack]`. A local override or `extends` child that sets `args` replaces the inherited list. Default: none. | `["--turbopack"]` | | services..platform | string | Runtime of the service: `node`, `bun`, `deno`, `python` or `rust`. It decides which variables devlanes adds, such as the devlanes CA (`NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`) and color settings. Detected from the `run_script` file or the working directory when omitted; set it only when detection is wrong. `none` skips detection and adds no platform variables. | `node` | | services..preset | `vite` or `next` or `wrangler` or `tauri` | Framework integration that adds the flags and variables a dev server needs to run in a lane, such as `--port --strictPort --host 127.0.0.1` for `vite`, so you do not pass them yourself. Requires `run_script`; with a hand-written `run`, drop the preset and pass its flags yourself. Its options go under a sibling key with the preset's name, for example `vite: { args: [--open] }`. | `vite` | | services..pty | boolean (templated) | Run the service in a pseudoterminal, so it sees a terminal as it would in your shell and you can type into it from the TUI. Set false to use pipes instead: stdin is empty and stdout and stderr are read separately. Defaults to true. | `true` | | services..ready | `started` or object | When the service counts as up: `devlanes start` waits for it, and `after: services` tasks run once every started service is ready. Write `started` (ready once the process runs) or a mapping with one of `tcp`, `http`, `log` or `cmd`, plus `timeout` (default 60s). Without it, a service with `hosts` waits for TCP on its port and one without hosts uses `started`. A check that times out marks the service failed, which also skips `after: services` tasks; the process keeps running and is not restarted. Values: `started`: Count the unit ready as soon as it runs, without probing anything. A dev server whose program crashed under a file watcher still counts as ready, so prefer a check when there is something to probe. | `started` | | services..ready.cmd | string (templated) or list of string (templated) | Ready once this command exits 0. It runs on the host through `/bin/sh` (a list is quoted into one command line) with its output discarded, is retried until the timeout, and each attempt is cut off after 10 seconds. For a service it gets the service's environment and working directory. | `curl -fsS ${{ self.url }}/healthz` | | services..ready.http | object | Ready once a GET request to `path` on the unit's main port answers with `status`, or with a 2xx status when `status` is unset. Redirects are not followed. Best when the app has a health route that fails while it is broken. Each request sends `User-Agent: devlanes-ready`, so an app can leave the checks out of its request logs. | `{"path":"/healthz","status":200,"timeout":"60s"}` | | services..ready.http.host | string (templated) | Host header the check sends, for apps that answer only on their own hostname, such as `${{ self.hosts[0] }}`. The request still goes to 127.0.0.1; only the header changes. Defaults to `127.0.0.1:`. Spaces and control characters are refused. | `${{ self.hosts[0] }}` | | services..ready.http.path | string (templated) | Path requested with GET, such as `/healthz`; defaults to `/`. | `/healthz` | | services..ready.http.status | integer (templated) | Status code that counts as ready, between 100 and 599; only that exact code passes. When unset, any status from 200 to 299 counts, so a 404 or a redirect keeps waiting (redirects are not followed). Set it to accept another code, such as `302` for a route that redirects to a login. | `200` | | services..ready.http.timeout | duration (templated) | How long the HTTP check may take to pass, replacing the check's `timeout`; defaults to 60s. When it runs out, a service is marked failed but keeps running, and for an infra container the start fails. | `15s` | | services..ready.log | string (templated) | Ready once a line of output matches this regular expression, with colors and other terminal escape codes removed; recent lines printed before the check began count too. Suits workers without a port: have them print a line once connected. | `Connected to Redis` | | services..ready.tcp | boolean or string | Ready once a port accepts a TCP connection on 127.0.0.1 or ::1, tried every 150 ms. `true` uses the unit's main port; a port name such as `inspector` uses that named port. It only proves the socket is open, not that the app works. | `true` | | services..ready.timeout | duration (templated) | How long the check may take to pass; defaults to 60s. When it runs out, a service is marked failed (its process keeps running and is not restarted) and `after: services` tasks are skipped; for an infra container the start fails. Raise it for services that compile before they listen. | `15s` | | services..replicas | integer | Number of copies of this service to run, each with its own port, for example several queue workers. They run as `.1` to `.N`, `${{ replica.index }}` counts from 1, and `services.` in expressions means the first copy; use `${{ replica.index }}` in `hosts` to give each copy its own hostname. A plain number of at least 1, the same in every lane, because each copy reserves ports in every lane's block; `${{ ... }}` expressions are not allowed. Defaults to 1. | `1` | | services..run | string (templated) or list of string (templated) | Command that starts the service. A string runs with `/bin/sh -c`, so pipes, `&&` and multi-line scripts work; a list is an argv run directly without a shell. It starts in the lane's worktree root unless `cwd` is set. devlanes runs it exactly as written, so it cannot be combined with `preset`; prefer `run_script` when the command is a script in a project file. Exactly one of `run` and `run_script` is required after templates are applied. | `pnpm dev` | | services..run_script | object | Script to run from a project file, as `{ file, name }`, such as `{ file: apps/api/package.json, name: dev }`. devlanes picks the tool from the file name (`package.json`, `Makefile`, `justfile`, `deno.json`, `pyproject.toml`, `Cargo.toml`), runs the script in that file's directory and checks that it exists before starting. Presets need it to place their flags, and a profile's `run_scripts` can swap the script name. Exactly one of `run` and `run_script` is required after templates are applied. | `{"file":"apps/api/package.json","name":"dev"}` | | services..run_script.file | string | File that defines the script, relative to the project file's directory, such as `apps/api/package.json`. The script runs in this file's directory. Required unless an override or `extends` child keeps the inherited file. | `apps/api/package.json` | | services..run_script.name | string | Script, target, recipe, task or binary name in that file. Required unless an override or `extends` child keeps the inherited name. | `dev` | | services..stop | object | How devlanes stops the service: `signal` goes to its whole process tree, and after `timeout` every process still running is SIGKILLed. The service then shows as stopped and is not restarted. Defaults to SIGTERM and 10s. | `{"signal":"SIGINT","timeout":"15s"}` | | services..stop.signal | string | Signal sent to the service's whole process tree when devlanes stops or restarts it. One of `SIGTERM` (default), `SIGINT`, `SIGHUP`, `SIGQUIT`, `SIGUSR1`, `SIGUSR2` or `SIGKILL`; use `SIGINT` for programs that only shut down cleanly on Ctrl-C. | `SIGTERM` | | services..stop.timeout | duration (templated) | How long to wait after `signal` before devlanes SIGKILLs every process of the service that is still running. The service then shows as stopped; devlanes never restarts it. Defaults to 10s; raise it for programs that need time to flush or close connections. | `15s` | | services..sync | list of object | Folders mirrored while the service runs, such as build output a browser loads unpacked from a fixed path. Each entry copies `from` to `to` (default `~/devlanes/sync///`) and follows changes; machines connected with `devlanes remote connect` get their own copy. | `[{"from":"apps/extension/.output/chrome-mv3","ignore":["*.map"]}]` | | services..sync[].from | string (templated) | Folder to copy, relative to the project file's directory in the lane's worktree. | `apps/extension/.output/chrome-mv3` | | services..sync[].ignore | list of string | Glob patterns of files left out of the copy and of later updates. | `["*.map"]` | | services..sync[].to | string (templated) | Local destination; `~/` is your home and other relative paths start at the project file's directory. Defaults to `~/devlanes/sync///`. Machines connected with `devlanes remote connect` ignore it and use their own path. | `~/devlanes/sync/acme/${{ lane.name }}/chrome-mv3` | | services..tags | list of string | Labels for selecting and grouping services. `+tag` selects every service with the tag in profiles, in commands such as `devlanes start +api`, and in the TUI filter. Tags also set the service's color: the first tag with a `color` under the top-level `tags` wins, then the first tag naming a category such as `api`, `web` or `worker`, so put that tag first. | `["api","essential"]` | | services..tauri | object | Options for `preset: tauri`, which lets several Tauri v2 dev apps run side by side, one per lane and replica. The values go into a config overlay at `${{ lane.data_path }}/tauri/..conf.json`, passed with `--config` and in `DEVLANES_TAURI_CONFIG`, which Tauri merges over `tauri.conf.json`. | `{"before_dev_command":"","dev_url":"${{ services.desktop_web.url }}","identifier":"io.acme.app.lane${{ lane.index }}.client${{ replica.index }}"}` | | services..tauri.before_dev_command | string | Replaces `build.beforeDevCommand`, the command Tauri runs before the app. Set it to `""` when the frontend runs as its own devlanes service; otherwise every replica starts its own frontend on the port from `tauri.conf.json`. Default: the command in `tauri.conf.json`. | `""` | | services..tauri.dev_url | string | Frontend address the app loads, written to `build.devUrl`. Usually another service's `url`, such as `${{ services.desktop_web.url }}`, so each lane's app loads that lane's frontend. Must start with `http://` or `https://`; when unset, `tauri.conf.json` decides. | `${{ services.desktop_web.url }}` | | services..tauri.identifier | string | Bundle identifier for this lane and replica, which keys the app data, webview data and keychain entries. Required and must differ per lane and replica, for example `com.acme.app.dev.lane${{ lane.index }}.client${{ replica.index }}`; two instances with the same value are refused at start. Only letters, digits, `-` and `.` are allowed, with no empty part between dots. | `io.acme.app.lane${{ lane.index }}.client${{ replica.index }}` | | services..tauri.product_name | string | Replaces the app's `productName` from `tauri.conf.json` for this instance, for example to tell lanes apart. Default: the value in `tauri.conf.json`. | `Acme Dev` | | services..vite | object | Options for `preset: vite`, which adds `--port --strictPort --host 127.0.0.1` to the dev server command. `--strictPort` makes Vite exit when the port is taken instead of moving to another port the proxy does not know about. | `{"args":["--open"]}` | | services..vite.args | list of string | Extra arguments for the Vite command, added after the preset's port and host flags, for example `[--mode, staging]`. A local override or `extends` child that sets `args` replaces the inherited list. Default: none. | `["--open"]` | | services..wrangler | object | Options for `preset: wrangler`, which gives each lane's `wrangler dev` its own `--port `, `--inspector-port ` and dev registry. The `inspector` port is allocated automatically. `args` that pass either port flag are refused by `devlanes config check`, and a `run_script` script that does is refused at start. | `{"args":["--env-file",".dev.vars"],"isolate_registry":true,"vars":{"PUBLIC_BASE_URL":"${{ self.public_url }}"}}` | | services..wrangler.args | list of string | Extra arguments for `wrangler dev`, added after the port and `--var` flags, for example `[--env-file, .dev.vars]`. `--port` and `--inspector-port` (or `--inspectorPort`) are refused here, since the preset already sets them per lane. A local override or `extends` child that sets `args` replaces the inherited list. | `["--env-file",".dev.vars"]` | | services..wrangler.isolate_registry | boolean | Points `WRANGLER_REGISTRY_PATH`, `CLOUDFLARE_DEV_REGISTRY_PATH` and `MINIFLARE_REGISTRY_PATH` at `wrangler-registry` in the lane's data folder (`${{ lane.data_path }}`), so service bindings resolve to workers of the same lane instead of same-named workers in another lane, also when two lanes run from one folder. Set `false` to drop these variables for this service, which then uses Wrangler's shared default registry. Default: `true`. | `true` | | services..wrangler.vars | map of string or number or boolean | Worker variables for this lane, each passed as `--var KEY:VALUE` so it overrides the same name in the Wrangler config's `vars`. Values can be strings, numbers or booleans (sent as text) and may use expressions such as `${{ self.public_url }}`; names must be non-empty and cannot contain `:`. Local overrides and `extends` children merge with inherited vars per name. | `{"PUBLIC_BASE_URL":"${{ self.public_url }}"}` | ### tags | Path | Type | Description | Example | | --- | --- | --- | --- | | `tags` | map of object | Optional color and description per tag. Services list their tags in their own `tags`, and tags group them: `+api` selects every service tagged `api` in profiles and in commands such as `devlanes start +api`. A unit's color comes from the first of its tags with a `color` set here, else the first tag naming a category such as api, web, worker or db, else its preset or name. Tags not listed here work too. | `{"api":{"color":"cyan","description":"HTTP APIs"}}` | | tags..color | `red` or `green` or `yellow` or `blue` or `magenta` or `cyan` or `white` or `gray` or `bright-red` or `bright-green` or `bright-yellow` or `bright-blue` or `bright-magenta` or `bright-cyan` | Color of services with this tag in the TUI and CLI output. When a service has several tags with a color, the first one in its `tags` list wins. Without one, devlanes infers a color from category words such as `api` (blue), `web` (green) or `worker` (magenta) in the service's tags, preset or name. Values: `red`: Show the tag's services in the terminal's red color. `green`: Show the tag's services in the terminal's green color. `yellow`: Show the tag's services in the terminal's yellow color. `blue`: Show the tag's services in the terminal's blue color. `magenta`: Show the tag's services in the terminal's magenta color. `cyan`: Show the tag's services in the terminal's cyan color. `white`: Show the tag's services in the terminal's white color. `gray`: Show the tag's services in the terminal's gray color. `bright-red`: Show the tag's services in the terminal's bright-red color. `bright-green`: Show the tag's services in the terminal's bright-green color. `bright-yellow`: Show the tag's services in the terminal's bright-yellow color. `bright-blue`: Show the tag's services in the terminal's bright-blue color. `bright-magenta`: Show the tag's services in the terminal's bright-magenta color. `bright-cyan`: Show the tag's services in the terminal's bright-cyan color. | `red` | | tags..description | string | Note on what the tag groups, for people reading the config. | `HTTP APIs` | ### tasks | Path | Type | Description | Example | | --- | --- | --- | --- | | `tasks` | map of object | One-shot commands such as installs, migrations and seeds, run by hand with `devlanes run ` or automatically at a lane event set with `when`. Tasks of the same event run in declaration order. | `{"migrate":{"run_script":{"file":"apps/api/package.json","name":"migrate"},"when":"lane.start"}}` | | tasks..after | `services` | Set to `services` to run a `lane.create` or `lane.start` task after the started services are ready instead of before them, for work that goes through the running app, such as seeding through its API. Values: `services`: Run once every started service is ready; the task is skipped when one of them failed or the start timed out. | `services` | | tasks..confirm | string (templated) | Question asked before the task runs, for destructive tasks. Scripts and agents without a terminal must pass `--yes` to run it. | `Reset ${{ lane.db_name }} and re-seed it?` | | tasks..cwd | string (templated) | Working directory for `run`, relative to the project file's directory in the lane's worktree; defaults to that directory. Cannot be combined with `run_script`, which runs in the script file's directory. | `apps/api` | | tasks..env | map of scalar (templated) | Variables for this task only, above `global_env`. | `{"API_URL":"${{ services.api.url }}"}` | | tasks..interactive | boolean (templated) | Give the task your terminal for input and output, for logins, prompts and TUIs. Interactive tasks only run by hand, so they cannot have `when`. Defaults to false. | `true` | | tasks..profiles | list of string | Run this task's `when` hook only while one of these profiles is active; `default` also matches a start without `--profile`. Runs by hand are not affected. Requires `when`. | `["default","backend"]` | | tasks..pty | boolean (templated) | Run the task in a pseudoterminal instead of plain pipes, for tools that only print colors or progress to a terminal. Defaults to the value of `interactive`. | `true` | | tasks..run | string (templated) or list of string (templated) | Command to run: a string runs through `/bin/sh -c` (pipes and multi-line scripts work), a list runs the program directly with those arguments. Use exactly one of `run`, `run_script` or `steps`. | `pnpm dev` | | tasks..run_script | object | Script to run from a project file, as `{ file, name }`, such as `{ file: apps/api/package.json, name: migrate }`. It runs with that file's tool (the project's package manager for package.json) in the file's directory, and a missing script fails before anything starts. Prefer it to `run` for scripts that live in a file. Use exactly one of `run`, `run_script` or `steps`. | `{"file":"apps/api/package.json","name":"dev"}` | | tasks..run_script.file | string | File that defines the script, relative to the project file's directory, such as `apps/api/package.json`. The script runs in this file's directory. Required unless an override or `extends` child keeps the inherited file. | `apps/api/package.json` | | tasks..run_script.name | string | Script, target, recipe, task or binary name in that file. Required unless an override or `extends` child keeps the inherited name. | `dev` | | tasks..steps | list of string | Run these tasks and `infra.setup.` or `infra.teardown.` entries in order, stopping at the first failure, for jobs such as resetting a database. Each step runs whatever its own `when` says, and setup entries run again even when already done. Use instead of `run` or `run_script`. | `["infra.teardown.database","infra.setup.database","migrate","seed"]` | | tasks..timeout | duration (templated) | Longest the task may run. When it runs out, the task is stopped (SIGTERM, then SIGKILL after 10 seconds) and counts as failed; a failed task that runs before services fails the start. No limit by default. | `15s` | | tasks..when | `lane.create` or `lane.start` or `lane.stop` or `lane.clean` | Lane event that runs this task automatically. Without it the task runs only by hand with `devlanes run ` or as a step of another task. Values: `lane.create`: Run on each start until it has succeeded once for the lane, then no longer automatically; for installs, code generation and a first seed. `lane.start`: Run on every start of the lane, before services unless `after: services` is set; for migrations and other steps that are safe to repeat. `lane.stop`: Run before the lane's processes stop when the whole lane stops: `devlanes stop` without unit names, `devlanes daemon stop` and `daemon restart`. Skipped when a signal (logout, system shutdown) stops the daemon. `lane.clean`: Run when the lane is cleaned (`devlanes lane clean`), after its processes stop and before `infra.teardown`. | `lane.create` | ### templates | Path | Type | Description | Example | | --- | --- | --- | --- | | `templates` | map of object | Named service settings that services reuse with `extends: