Services

Services are the long-running processes that make up your project — your dev server, an API, a background worker, anything you’d normally leave running in a terminal tab. lpm starts them together when you click Start and stops them when you click Stop. Most projects have at least one; a project with none still works as a home for terminals and agents — it just has no Start button.

If a command runs continuously, it’s a service. If it finishes and exits — tests, a build, a migration — it belongs in Actions instead. Each service can be written as a one-line shorthand (just the command) or as the full form when you need cwd, port, or env.

~/.lpm/projects/myapp.ymlvalid

name: myapp
root: ~/Projects/myapp
services:
  # shorthand — key is the name, value is the command
  server: node server.js

  # full form — use this when you need cwd, port, env, or dependsOn
  web:
    cmd: npm run dev
    cwd: ./web                # run from a subfolder (great for monorepos)
    port: 3000                # a label: shown in the Start menu, used by Open in browser
    dependsOn: [server]       # start "server" first, pulled in automatically
    env:                      # extra env vars just for this service
      API_URL: http://localhost:4000

cmd*string
The shell command that starts the process — exactly what you’d type into a terminal yourself, like npm run dev or node server.js. lpm runs it in the background, where it keeps running even after you quit the app, and streams its output into a read-only pane. lpm doesn’t restart a command that exits on its own.
cwdstring
Start the service from a different folder than the project root — handy for monorepos where each app lives in its own subfolder like ./apps/web. Relative paths resolve from root; absolute paths are used as-is. See Path resolution for ~ and SSH projects.
portint
The port this service listens on. It’s a label and a conflict check, not an assignment: lpm shows it next to the service in the Start menu, offers it under Open in browser until it sees the port the service actually opened, and checks that nothing else holds it when you press Start. lpm doesn’t pass it to your command — put the port in cmd or env yourself. Give each service its own port — lpm config validate flags two services that share one.
portConflictstring
What to do when port is already taken at Start. ask (the default) asks before freeing it, free frees it without asking, and fail refuses to start. Freeing stops the other lpm project holding the port, or ends the process that holds it.
envmap
Extra environment variables to set just for this service — things like API_URL or NODE_ENV. Useful when you don’t want to commit them to a .env file.
dependsOn[]string
Other services this one needs — name them here and lpm starts them first, pulling them in automatically whenever you start this service (even if you only picked this one). It’s ordering only: the dependencies launch ahead of this service, but lpm doesn’t wait for them to finish booting or start listening before it moves on. Also accepted as depends_on.

Field	Type	Description
`cmd`*	string	The shell command that starts the process — exactly what you’d type into a terminal yourself, like `npm run dev` or `node server.js`. lpm runs it in the background, where it keeps running even after you quit the app, and streams its output into a read-only pane. lpm doesn’t restart a command that exits on its own.
`cwd`	string	Start the service from a different folder than the project root — handy for monorepos where each app lives in its own subfolder like `./apps/web`. Relative paths resolve from `root`; absolute paths are used as-is. See Path resolution for `~` and SSH projects.
`port`	int	The port this service listens on. It’s a label and a conflict check, not an assignment: lpm shows it next to the service in the Start menu, offers it under Open in browser until it sees the port the service actually opened, and checks that nothing else holds it when you press Start. lpm doesn’t pass it to your command — put the port in `cmd` or `env` yourself. Give each service its own port — `lpm config validate` flags two services that share one.
`portConflict`	string	What to do when `port` is already taken at Start. `ask` (the default) asks before freeing it, `free` frees it without asking, and `fail` refuses to start. Freeing stops the other lpm project holding the port, or ends the process that holds it.
`env`	map	Extra environment variables to set just for this service — things like `API_URL` or `NODE_ENV`. Useful when you don’t want to commit them to a `.env` file.
`dependsOn`	[]string	Other services this one needs — name them here and lpm starts them first, pulling them in automatically whenever you start this service (even if you only picked this one). It’s ordering only: the dependencies launch ahead of this service, but lpm doesn’t wait for them to finish booting or start listening before it moves on. Also accepted as `depends_on`.

* required

Services that depend on each other. When one service builds on another — a web app that talks to an API, an API that reads from the database — list the ones it needs in dependsOn. Start web here and lpm pulls in api and db for you and launches them in order: db, then api, then web. It starts them in that order but doesn’t wait for each one to be ready before moving to the next, so a service that connects on boot should retry until its dependency answers.

~/.lpm/projects/myapp.ymlvalid

name: myapp
root: ~/Projects/myapp
services:
  db: docker compose up postgres
  api:
    cmd: npm run api
    dependsOn: [db]           # lpm starts db before api
  web:
    cmd: npm run dev
    dependsOn: [api]          # lpm starts api before web

Starting and stopping

Click Start in the project toolbar and lpm brings your services up together; click Stop and they all come down. To run just one, switch it on in the Start button’s dropdown — lpm pulls in whatever it depends on. Selecting a project in the sidebar never starts it; a double-click can, if you turn on Double-click to start/stop in Settings.

If you usually want a subset — say, the web app without the worker — define a profile and pick it from the same dropdown.