Skip to content

devlanes is in beta and not ready for production use.Report an issue

services in devlanes.yaml

A top-level key of devlanes.yaml.

Type: mapping of names to mappings.

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.

devlanes.yaml
services:
api:
hosts: api.${{ lane.domain }}
run_script:
file: apps/api/package.json
name: dev

Type: mapping.

A long-running process started with the lane, such as a dev server or a worker. Each service gets its own port from the lane’s block (PORT, ${{ self.port }}); devlanes stops it with the lane and never restarts it when it exits. A service needs run or run_script, directly or through extends.

devlanes.yaml
services:
api:
hosts: api.${{ lane.domain }}
run_script:
file: apps/api/package.json
name: dev
tags:
- api

Type: boolean or an expression.

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.

devlanes.yaml
services:
api:
autostart: true

Type: string or an expression.

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.

devlanes.yaml
services:
api:
cwd: apps/api

Type: mapping of names to strings, booleans, numbers or expressions.

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.

devlanes.yaml
services:
api:
env:
API_URL: ${{ services.api.url }}

Type: 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.

devlanes.yaml
services:
api:
extends: fastify-api

Type: boolean or an expression.

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.

devlanes.yaml
services:
api:
hidden: false

Type: string, mapping or an expression, or a list of these.

Hostnames the devlanes HTTPS proxy routes to this service, so https://<host> 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.

devlanes.yaml
services:
api:
hosts: api.${{ lane.domain }}

Type: boolean or an expression.

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.

devlanes.yaml
services:
api:
hosts:
- host: api.${{ lane.domain }}
fallback: true

Type: string or an expression. Required.

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.

devlanes.yaml
services:
api:
hosts:
- host: api.${{ lane.domain }}

Type: string.

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:<port>, 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:<port>.
devlanes.yaml
services:
api:
hosts:
- host: api.${{ lane.domain }}
host_header: preserve

Type: 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.<name>, 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.

devlanes.yaml
services:
api:
hosts:
- host: api.${{ lane.domain }}
port: inspector

Type: boolean or an expression.

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.

devlanes.yaml
services:
api:
keep_awake: true

Type: 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.<key> }} keep using the key.

devlanes.yaml
services:
api:
name: Admin API

Type: mapping, with preset: next.

Options for preset: next, which adds --port <self.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.

devlanes.yaml
services:
api:
preset: next
next:
args:
- --turbopack

Type: list of strings.

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.

devlanes.yaml
services:
api:
preset: next
next:
args:
- --turbopack

Type: string.

Runtime of the service: node, bun, deno, python, rust, go or java. It decides which variables devlanes adds, such as the devlanes CA (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, a trust store in JAVA_TOOL_OPTIONS) and color settings. Detected from the run_script file or the working directory when omitted; set it only when detection is wrong, such as java for a java -jar command in a folder without a pom.xml or Gradle file. none skips detection and adds no platform variables.

devlanes.yaml
services:
api:
platform: node

Type: string.

Framework integration that adds the flags and variables a dev server needs to run in a lane, such as --port <port> --strictPort --host 127.0.0.1 for vite or SERVER_PORT for spring-boot, so you do not pass them yourself. One of vite, next, wrangler, tauri, spring-boot or quarkus. Requires run_script (quarkus needs a pom.xml or build.gradle(.kts) one); 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] }.

Values:

  • vite
  • next
  • wrangler
  • tauri
  • spring-boot
  • quarkus
devlanes.yaml
services:
api:
preset: vite

Type: boolean or an expression.

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.

devlanes.yaml
services:
api:
pty: true

Type: mapping, with preset: quarkus.

Options for preset: quarkus, which sets the HTTP port and host, lets continuous testing pick a free port and moves the dev-mode debugger from 5005 to self.ports.debug, so two lanes can run dev mode side by side. The preset has no settings, so the key can be left out.

devlanes.yaml
services:
api:
preset: quarkus
quarkus: {}

Type: started or mapping.

When the service counts as up: once its check passed and it has run half a second. devlanes start waits for it, and after: services tasks run once every started service is ready. Write started (no probe) 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 service that exits within that half second failed to start. 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 once it runs, without probing anything; a service once it has run half a second. A dev server whose program crashed under a file watcher still counts as ready, so prefer a check when there is something to probe.
devlanes.yaml
services:
api:
ready: started

Type: string, list of strings or an expression.

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.

devlanes.yaml
services:
api:
ready:
cmd: curl -fsS ${{ self.url }}/healthz

Type: mapping.

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.

devlanes.yaml
services:
api:
ready:
http:
path: /healthz
status: 200
timeout: 60s

Type: string or an expression.

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:<port>. Spaces and control characters are refused.

devlanes.yaml
services:
api:
ready:
http:
host: ${{ self.hosts[0] }}

Type: string or an expression.

Path requested with GET, such as /healthz; defaults to /.

devlanes.yaml
services:
api:
ready:
http:
path: /healthz

Type: integer or an expression.

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.

devlanes.yaml
services:
api:
ready:
http:
status: 200

Type: duration or an expression.

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.

devlanes.yaml
services:
api:
ready:
http:
timeout: 15s

Type: string or an expression.

Ready once a line of the unit’s log, as devlanes logs shows it (for a container, its Docker log), matches this regular expression, with colors removed; lines printed before the check began count too. Suits workers without a port: have them print a line once connected.

devlanes.yaml
services:
api:
ready:
log: Connected to Redis

Type: 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.

devlanes.yaml
services:
api:
ready:
tcp: true

Type: duration or an expression.

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.

devlanes.yaml
services:
api:
ready:
timeout: 15s

Type: integer.

Number of copies of this service to run, each with its own port, for example several queue workers. They run as <name>.1 to <name>.N, ${{ replica.index }} counts from 1, and services.<name> 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.

devlanes.yaml
services:
api:
replicas: 1

Type: string, list of strings or an expression.

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 project file’s directory 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. In a list, an item that is one ${{ }} expression giving a number or true/false becomes its text, such as --port followed by ${{ self.port }}.

devlanes.yaml
services:
api:
run: pnpm dev

Type: mapping.

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, Taskfile.yml, deno.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle(.kts), settings.gradle(.kts)), runs the script in that file’s directory and checks that it exists before starting. For Maven and Gradle, name is the arguments as typed after mvn or gradle, and Maven or Gradle reports a goal or task that does not exist. 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.

devlanes.yaml
services:
api:
run_script:
file: apps/api/package.json
name: dev

Type: 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.

devlanes.yaml
services:
api:
run_script:
file: apps/api/package.json

Type: string.

Script, target, recipe, task, binary or package name in that file. For go.mod, a bare name such as api means ./cmd/api, and . or a path with / is relative to go.mod. For pom.xml and Gradle files it is the arguments as typed after mvn or gradle, such as -pl web -am spring-boot:run or :web:bootRun; quote an argument that contains spaces, as in a shell. It must name at least one goal or task. Required unless an override or extends child keeps the inherited name.

devlanes.yaml
services:
api:
run_script:
name: dev

Type: mapping, with preset: spring-boot.

Options for preset: spring-boot, which sets SERVER_PORT to the service’s port, binds the app to 127.0.0.1, trusts the devlanes proxy’s forwarded headers and turns off LiveReload, whose fixed port 35729 collides between lanes.

devlanes.yaml
services:
api:
preset: spring-boot
spring-boot:
docker_compose: true

services.<name>.spring-boot.docker_compose

Section titled “services.<name>.spring-boot.docker_compose”

Type: boolean.

Lets Spring Boot’s own Docker Compose support (spring-boot-docker-compose) start the project’s compose file. Default: false, which sets SPRING_DOCKER_COMPOSE_ENABLED=false: devlanes already runs the project’s containers per lane or shared, and Spring’s support would start a second copy for every worktree. Set true only when devlanes does not manage those containers.

devlanes.yaml
services:
api:
preset: spring-boot
spring-boot:
docker_compose: true

Type: mapping.

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.

devlanes.yaml
services:
api:
stop:
signal: SIGINT
timeout: 15s

Type: 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.

devlanes.yaml
services:
api:
stop:
signal: SIGTERM

Type: duration or an expression.

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.

devlanes.yaml
services:
api:
stop:
timeout: 15s

Type: list of mappings.

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/<project>/<lane>/<folder>) and follows changes; machines connected with devlanes remote connect get their own copy.

Each item: Folder copied to a fixed path and kept up to date, for build output another program loads from a stable location, such as an unpacked browser extension. Also streams to machines connected with devlanes remote connect.

devlanes.yaml
services:
api:
sync:
- from: apps/extension/.output/chrome-mv3
ignore:
- "*.map"

Type: string or an expression. Required.

Folder to copy, relative to the project file’s directory in the lane’s worktree.

devlanes.yaml
services:
api:
sync:
- from: apps/extension/.output/chrome-mv3

Type: list of strings.

Glob patterns of files left out of the copy and of later updates.

devlanes.yaml
services:
api:
sync:
- from: apps/extension/.output/chrome-mv3
ignore:
- "*.map"

Type: string or an expression.

Local destination; ~/ is your home and other relative paths start at the project file’s directory. Defaults to ~/devlanes/sync/<project>/<lane>/<folder>. Machines connected with devlanes remote connect ignore it and use their own path.

devlanes.yaml
services:
api:
sync:
- from: apps/extension/.output/chrome-mv3
to: ~/devlanes/sync/acme/${{ lane.name }}/chrome-mv3

Type: list of strings.

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.

devlanes.yaml
services:
api:
tags:
- api
- essential

Type: mapping, with preset: tauri.

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/<service>.<replica>.conf.json, passed with --config and in DEVLANES_TAURI_CONFIG, which Tauri merges over tauri.conf.json.

devlanes.yaml
services:
api:
preset: tauri
tauri:
before_dev_command: ""
dev_url: ${{ services.desktop_web.url }}
identifier: io.acme.app.lane${{ lane.index }}.client${{ replica.index }}

Type: 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.

devlanes.yaml
services:
api:
preset: tauri
tauri:
before_dev_command: ""

Type: 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.

devlanes.yaml
services:
api:
preset: tauri
tauri:
dev_url: ${{ services.desktop_web.url }}

Type: 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.

devlanes.yaml
services:
api:
preset: tauri
tauri:
identifier: io.acme.app.lane${{ lane.index }}.client${{ replica.index }}

Type: 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.

devlanes.yaml
services:
api:
preset: tauri
tauri:
product_name: Acme Dev

Type: mapping, with preset: vite.

Options for preset: vite, which adds --port <self.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.

devlanes.yaml
services:
api:
preset: vite
vite:
args:
- --open

Type: list of strings.

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.

devlanes.yaml
services:
api:
preset: vite
vite:
args:
- --open

Type: mapping, with preset: wrangler.

Options for preset: wrangler, which gives each lane’s wrangler dev its own --port <self.port>, --inspector-port <self.ports.inspector> 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.

devlanes.yaml
services:
api:
preset: wrangler
wrangler:
args:
- --env-file
- .dev.vars
isolate_registry: true
vars:
PUBLIC_BASE_URL: ${{ self.public_url }}

Type: list of strings.

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.

devlanes.yaml
services:
api:
preset: wrangler
wrangler:
args:
- --env-file
- .dev.vars

Type: 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.

devlanes.yaml
services:
api:
preset: wrangler
wrangler:
isolate_registry: true

Type: mapping of names to strings, numbers or booleans.

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.

devlanes.yaml
services:
api:
preset: wrangler
wrangler:
vars:
PUBLIC_BASE_URL: ${{ self.public_url }}