A lane corresponds to a Git worktree. Lane 0 follows the primary branch, except under CI, where the checkout takes lane 0 on any branch when lane 0 is free; other worktrees keep persisted indexes. A worktree other than the primary one gets its lane the first time devlanes runs in it, and a lane whose folder is gone stays until lane gc cleans it, unless lanes.removed_worktrees: clean has the daemon clean it once nothing runs in it. Worktree identity uses the Git common directory and worktree administration entry, so moving a worktree preserves its identity. lane new --name adds another lane for one folder: a worktree row whose identity is the folder’s plus #lane=<name>, which follows that folder and never takes lane 0. Non-Git projects have one lane per folder unless extra lanes are added.
A project is identified by its project: name, and a name belongs to one repository. One repository can hold several projects, each read from its own project file: the nearest devlanes.yaml above the current directory, up to the repository root, or a file registered once with --file and stored with the project relative to the repository root. A worktree has a lane in a project while its copy of that file names the project, so a rename or a branch switch leaves the old lane in place until lane gc collects it, once nothing runs there.
The daemon owns processes, ports, proxy routes and SQLite. CLI and TUI clients exchange structured requests and events with it. Closing a client does not stop services. Integration crates implement core traits and are registered by the binary; Docker containers belong to infrastructure adapters rather than process runners.
Each lane receives a non-overlapping block from the machine-wide port pool. Named service offsets persist within that block. A service must accept its assigned port; listening-socket inspection is diagnostic only. Hostnames put the lane in the registrable label, such as api.acme2.localhost.
Startup orders infrastructure, per-lane setup, lifecycle tasks, concurrent services, then after-services tasks. There is no service dependency graph or automatic restart: a failed unit stays failed. Each lane saves the services it runs and its profiles (never the environment), so a plain start, lane resume or daemon restart from a shell brings back what ran after the daemon stopped; a whole-lane stop clears that. A restart starts the new daemon before it stops the old one: the new one waits for the singleton lock, with the lanes to start again and the restarting client’s environment handed over in memory on its stdin, so the restart finishes even when that client goes away. Monitoring reports resource use without enforcing limits. Throttling and freezing an idle lane is neither automatic restart nor enforcement: its processes keep their state, ports and PIDs, and activity on the lane thaws them (lane lifecycle).
YAML configuration merges the files a project file extends, each followed by its local file, then the project file and its local file. Maps merge by key and lists/scalars replace, and templates expand after the merge. ${{ ... }} expressions use strict undefined-variable handling. Client environments stay in daemon memory; .env files supply expression values, not implicit process environment injection.
The daemon reloads a lane’s config when any file the last load read changes, .env included, and never stops or restarts a unit because of it. It keeps what each running service was spawned with in memory only, since that holds environment values, and compares it with what the new config would spawn to report per-unit drift; reload applies that drift on request. While units run and the file does not load, the lane’s routes follow the last config that loaded.
The daemon’s HTTPS proxy signs certificates for registered hosts with a per-user CA, devlanes’ own or mkcert’s (tls.ca). SSH transport mirrors registered, non-hidden TCP ports. HTTP-based GUI viewers can be ordinary services; built-in window streaming, relay transport, public DNS resolution and iOS/Android certificate trust are outside v1.
examples has commented configuration files for these contracts.