Add devlanes to a project
You need devlanes on your machine, as Install devlanes sets it up, and the ideas from A service, a port and a hostname.
Use this guide when your project starts today with a dev script or a few terminals. A coding agent with the devlanes skill can do all of it for you; Set up a coding agent gives it the skill.
::example{slug="basics-hello-node"}
Write the project file
Section titled “Write the project file”Create devlanes.yaml at the root of the repository. Each long-running command becomes a service that points at its script, a service you open in a browser gets a hostname, and the ready check names a route that answers once the app works.
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 project name goes into the lane’s domain and is shared by every worktree, so choose one you will keep. Run scripts your project already has covers other script files and plain commands.
Listen on the port devlanes gives
Section titled “Listen on the port devlanes gives”devlanes passes each service its port in PORT and the loopback address in HOST. Read both where the server starts listening. A server that keeps a fixed port of its own never passes its ready check.
const port = Number(process.env.PORT ?? 3000);const host = process.env.HOST ?? "127.0.0.1";
server.listen(port, host);Run a service in its runtime has the same lines for other runtimes.
Check and start
Section titled “Check and start”$ devlanes config check$ devlanes start --no-uiThe check points at the line of any mistake. The start runs the script, waits for the ready check and prints the hostname to open. Commit the file, so every worktree of the repository has it.
If the command takes its port as a flag
Section titled “If the command takes its port as a flag”Pass the port with an expression. For Vite and Next.js a preset adds the flags, as Run Vite and Next.js shows, and for Spring Boot and Quarkus a preset sets the variables, as Run Spring Boot and Quarkus shows.
services: api: run: node server.mjs --port ${{ self.port }}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>.runCommand 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 }}.
If another tool runs the project today
Section titled “If another tool runs the project today”Migrate from another process manager turns an mprocs, Procfile or Compose setup into a project file.