A service, a port and a hostname
myapp starts as one API with a dev script. Under devlanes that script becomes a service with a port of its own and an HTTPS hostname, run by a background daemon instead of your terminal.
One file describes the project
Section titled “One file describes the project”You add one file, devlanes.yaml, at the root of the repository and commit it with the rest of the code. It names the project and lists its services, the long-running processes the project is made of.
project: myapp
services: api: run_script: file: api/package.json name: dev hosts: "api.${{ lane.domain }}" ready: http: path: /healthzprojectProject name, the same in every worktree of the repository. It builds each lane's default domain (<project>.localhost for lane 0, <project><N>.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.<project>. Lowercase letters, digits, dots, underscores and dashes.
servicesLong-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.
services.<name>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.
services.<name>.run_scriptScript 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.
services.<name>.run_script.fileFile 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.
services.<name>.run_script.nameScript, 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.
services.<name>.hostsHostnames 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.
services.<name>.readyWhen 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.
services.<name>.ready.httpReady 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.
services.<name>.ready.http.pathPath requested with GET, such as /healthz; defaults to /.
The file says which script starts the API, which hostname it wants and how to tell that it is ready. That last part is a ready check: a request devlanes repeats until the service answers. In the hostname, ${{ lane.domain }} is an expression that devlanes replaces with the lane’s domain, myapp.localhost here. No port appears anywhere.
The service listens where it is told
Section titled “The service listens where it is told”devlanes picks a port for each service and passes it in the PORT variable, with the address to listen on in HOST. Reading them is the one thing the project has to do.
const port = Number(process.env.PORT ?? 3000);const host = process.env.HOST ?? "127.0.0.1";
server.listen(port, host, () => { console.log(`api listening on http://${host}:${port}`);});A dev server that takes its port as a flag gets it another way, which Services that find each other shows.
A start runs the script and waits for it
Section titled “A start runs the script and waits for it”$ devlanes start --no-uidevlanes runs the dev script with its port, repeats the ready check until the API answers, and prints https://api.myapp.localhost. This is lane 0 of myapp, on the main branch. A lane is one worktree’s place to run the project, with a number, ports and hostnames of its own; Every worktree gets a lane adds another.
On a terminal, devlanes start opens the TUI, a full-screen view of each lane and its output; --no-ui prints the start as text instead. Starting again while the API runs starts nothing.
A background daemon keeps the API running
Section titled “A background daemon keeps the API running”The start hands the API to a background daemon and returns, and from then on the daemon runs it, whichever terminal you type in next.
$ devlanes statusThe status shows the lane with its domain, https://myapp.localhost, where nothing answers yet, and below it the lane’s units, the things devlanes runs in a lane. Here the only unit is the API, ready on its port behind api.myapp.localhost. When you stop the lane, the API’s process ends and the lane keeps its port and hostname for the next start.
The daemon keeps what the API prints
Section titled “The daemon keeps what the API prints”$ devlanes logs api --tail 10You can read the API’s output back later from any terminal, here its last ten lines, which so far are the one where it says which port it listens on.
Next you start a checkout feature on a branch of its own, and the same file runs the API a second time, on other ports and another hostname.