Environment and expressions
Each time a service or task of a lane starts, devlanes puts its environment together. It begins with the shell you ran devlanes from, then adds what tool managers and devlanes set, then what the project file and the command line set. Values in the project file can be expressions, worked out for each lane, so one file gives each lane its own ports, hostnames and database names.
Layers stack from the shell to the command line
Section titled “Layers stack from the shell to the command line”A unit, a service or task of a lane for example (Glossary), gets seven layers. When two set the same name, the higher one wins. From the bottom up:
- client: your shell’s environment, which the lane keeps as described below. Services and tasks from the project file get it without the variables coding agents set to identify themselves, such as
CLAUDECODEandAI_AGENT, so they run the same whether you or an agent started the lane. - contributor: what mise and direnv add, the variables that point Node, Python and the other runtimes at the devlanes CA, and a preset’s settings for a dev server such as Vite.
- devlanes: devlanes’ own variables, such as
PORTandHOST. - global:
global_envin the project file, for every unit of the lane. - service: the unit’s own env.
- profile: the env of the profiles, named selections of services, that the start selected.
- override: values given with
--envon the command line.
Because devlanes’ own variables sit above the shell, a PORT left in your shell cannot move a service. global_env sits above them, so do not set the port there: every service would get the same one. To see where each variable of a unit came from:
$ devlanes env show api --explainEnvironment variables lists what devlanes sets.
The lane keeps the shell’s environment in memory
Section titled “The lane keeps the shell’s environment in memory”The lane keeps the environment of the last shell that started, restarted, ran or executed something in it, and uses it for what it starts next. A devlanes reload reuses it, while a start or restart from another shell replaces it. After a change in your shell, such as a new PATH, restart from that shell so the lane picks it up.
The daemon writes that environment to no file and no log, since it can hold tokens and other secrets. So it does not outlive the daemon: after a reboot each lane waits for one start from a shell (The daemon). It is still not hidden from your own programs, since any process running as you can ask the daemon for it (Security).
Expressions are evaluated for each lane
Section titled “Expressions are evaluated for each lane”A value in the project file can hold an expression written as ${{ }}, which reads the lane: its number and domain, its services’ ports and URLs, its containers and the shell’s variables.
services: worker: autostart: ${{ lane.index == 0 }} web: env: VITE_API_URL: "${{ services.api.public_url }}"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>.autostartSet 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.
services.<name>.envEnvironment 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.
services.<name>.env.<name>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.
A value that is one expression keeps its type, so the worker’s setting is true or false. A name that does not exist is an error rather than an empty string, and default() makes a value optional. Expressions lists what an expression can read.
A .env file feeds expressions, not processes
Section titled “A .env file feeds expressions, not processes”An expression such as ${{ env.STRIPE_KEY }} takes the variable from your shell, or from the .env file next to the project file when the shell has none. devlanes does not pass the rest of .env to a process: you name each value a process needs, so everything a process gets from devlanes is in the project file.
global_env: STRIPE_KEY: ${{ env.STRIPE_KEY }} SENTRY_DSN: ${{ env.SENTRY_DSN | default('') }}global_envVariables 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 }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
global_env.<name>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 }}. An entry without a value, such as one that reads a container a profile with infra: false left stopped, fails every service and task of the lane, so a value only some services need belongs in their env. devlanes exec leaves such an entry out and names it. Never set PORT here: it would replace every service's own port.
Read .env values and pin tool versions sets this up.