lpm config reference

Project#

A project is one app you work on with lpm — a website, an API, a blog, anything you’d normally start in a terminal. Each one is a file in ~/.lpm/projects/, and it starts with the folder the code lives in.

Edit the YAML — the preview updates live.

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev

SSH projects. Swap root for an ssh block and the same services, actions, and terminals run on a remote machine. Adding an SSH host in the app writes this for you, with one shell service that opens a login shell on the host. lpm doesn’t scan remote folders for services, so add your own.

name: staging
ssh:
  host: staging.example.com
  user: deploy
  dir: ~/apps/shop
services:
  shell: exec "$SHELL" -l     # what adding an SSH host writes
  api: npm run start
actions:
  logs:
    cmd: tail -f log/production.log
    type: terminal

Automatic service detection#

When you add a folder or clone a repository, lpm reads the project’s own files and writes a service for each thing it can run. Nothing is sent anywhere and no AI is involved, so adding a project stays instant. The app then tells you what it found, like “Found 2 services: web, api”.

Where it looks. The project root first, then every workspace member declared in package.json or pnpm-workspace.yaml, then these subfolders if they exist: api, app, backend, client, frontend, server, ui, web, www, and every folder under apps/ or services/.

What it recognizes. Node commands use the package manager your repo declares or locks. Python commands run through the folder’s .venv (or venv), uv, Poetry, or Pipenv when it has one.

Names and ports. At the root, a service is named for its role — web, api, app, or the Procfile’s process name. In a subfolder, a lone service takes the folder’s name and a cwd pointing there; several share the folder name as a prefix, like backend-web. A port is written when the command names one (--port 3001, PORT=3001, localhost:5173) or the framework has a usual dev port. Adding a folder with a Compose file at the root, a Django app with its own .venv in backend/, and a Vite app using pnpm in frontend/ writes:

name: shop
root: ~/Projects/shop
services:
  compose:
    cmd: docker compose up
  backend:
    cmd: .venv/bin/python manage.py runserver
    cwd: backend
    port: 8000
  frontend:
    cmd: pnpm dev
    cwd: frontend
    port: 5173

Limits. Detection stops at 20 services. In a monorepo, the root’s own script (say, turbo dev) is left out once the workspace members turn up services of their own, so nothing starts twice. It runs once, when the project is added, and never rewrites a config you’ve edited.

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.

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

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.

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

Actions#

Actions are the commands you run once in a while — your test suite, a database migration, a deploy script. Services run continuously; actions fire once, do their job, and show you the result. Each one is a button in the project toolbar — or in the footer bar under the terminal — and one click runs it.

Try it — click test or Deploy to Production in the preview below. Actions with confirm: true ask before running; everything else just runs.

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  test: npm test              # shorthand

  deploy:                     # full form
    cmd: ./scripts/deploy.sh
    label: Deploy to Production  # display name in the UI
    confirm: true             # ask before running
    display: header           # main button row (default; omit to get the same)
    env:
      NODE_ENV: production

Other fields. The table covers what the examples on this page use. Actions also accept color (an accent for the button and the tab it opens), shortcut (a key combo that runs the action while the project is open), inputs (values lpm asks for before running and fills into the command), prompt (text sent to the agent a terminal action opens, once it’s ready), reuse (use the terminal that’s already open), port and portConflict (ports that must be free first, as a number, a range like "3002-3010", or a list), and on SSH projects mode (remote or sync). The app’s action editor sets most of them for you.

Shorthand. If all your action needs is a command, write it as a single line — the key becomes the label and you skip the nested form entirely. Great for everyday dev commands:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  test: npm test
  lint: npm run lint
  build: npm run build
  typecheck: npx tsc --noEmit
  format: npx prettier --write .

Destructive actions. For anything you don’t want to click by accident — cache wipes, rollbacks, production deploys — add confirm: true to get a confirmation dialog, and pair it with display: header (the default) so the action lives in the toolbar where you’ll find it:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  reset-cache:
    cmd: rm -rf .next node_modules/.cache
    label: Reset Cache
    confirm: true
    display: header
  rollback:
    cmd: ./scripts/rollback.sh
    label: Rollback Deploy
    confirm: true
    env:
      NODE_ENV: production

Grouping related actions. Give a parent action both a cmd and nested actions and lpm renders it as a split button: the main part runs the parent’s command, the chevron opens a menu with the children. Use this when there’s a sensible default plus a few alternatives — like “Deploy staging” with production and preview tucked behind it:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  deploy:
    cmd: ./deploy.sh staging     # split button — main click runs this
    label: Deploy
    emoji: 🚀                    # icon shown next to the label
    display: header
    confirm: true
    actions:                     # chevron opens these
      production:
        cmd: ./deploy.sh production
        label: Production
        emoji: 🔴
        confirm: true
      preview:
        cmd: ./deploy.sh preview
        label: Preview
        emoji: 👁️

Remembering your last choice. Add primary: last-used instead of a parent cmd and the main part of the split button becomes whichever option you clicked last — deploy to staging once, and the button reads “Staging” until you pick something else. Set primary to a child’s name (like primary: staging) to pin one option as the default instead:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  deploy:
    primary: last-used           # main click repeats the last used option
    actions:                     # chevron opens these
      staging:
        cmd: ./deploy.sh staging
        label: Staging
        emoji: 🟢
      production:
        cmd: ./deploy.sh production
        label: Production
        emoji: 🔴
        confirm: true

Dropdown-only groups. Drop the parent’s cmd and the whole button becomes a dropdown. Good for a set of related commands with no obvious default — like a database toolkit (Migrate, Seed, Reset):

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  db:
    label: Database
    emoji: 🗄️
    display: header
    cwd: ./backend
    actions:
      migrate:
        cmd: python manage.py migrate
        label: Migrate
        emoji: 📦
      seed:
        cmd: python manage.py seed
        label: Seed
        emoji: 🌱
      reset:
        cmd: python manage.py flush
        label: Reset
        emoji: 💣
        confirm: true

Background actions. For slow, boring commands where the only thing you care about is whether they succeeded — builds, migrations, docker pulls, git fetch — add type: background. The command runs hidden while a small live card counts the time and keeps its output a click away, with Cancel and Copy output, then shows success or failure when it’s done. No modal to dismiss, no terminal tab to clean up, and you can fire several in parallel while you keep working:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  db-reset:
    cmd: npm run db:reset && npm run db:seed
    label: Reset DB
    type: background       # runs hidden, with a live progress card
    confirm: true          # pair with confirm for destructive ones

Terminals#

Terminals are persistent interactive shells you open from the desktop app with a single click — a live log tail, a Node or Python REPL, or an AI coding agent like Claude Code. Unlike a service, a terminal isn’t something lpm starts and stops with the project; unlike an action, it doesn’t run once and exit. It stays open and you type in it until you close it.

A terminal is just an action with type: terminal — same fields as any action, it simply opens in a pane and stays open instead of running once. A standalone terminals: section still works as a deprecated alias, but new configs should use type: terminal.

Declaring a terminal. Give the entry a cmd and set type: terminal so it opens in a pane and stays open instead of running once. Reach for a friendlier label, tuck it into the footer with display: footer, or set a cwd or env when you need them:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  codex:                      # minimal — key becomes the label
    cmd: codex
    type: terminal

  claude:                     # full form
    cmd: claude
    label: Claude Code        # nicer name than the key
    display: header           # pin to the toolbar, one click away (default)
    type: terminal

AI coding agents, one click away. This is where terminals really shine. List the agents and REPLs you actually use and they’re waiting as one-click buttons in the project toolbar every time you open the project — each one starts in the project’s folder, so there’s no hunting for the right window or directory:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev
actions:
  claude:
    cmd: claude              # AI pair programmer
    type: terminal
  codex:
    cmd: codex               # another AI agent, swap at will
    type: terminal
  node:
    cmd: node                # quick REPL for poking at things
    type: terminal
  logs:
    cmd: tail -f ./logs/dev.log  # live-tail your dev server logs
    type: terminal

Profiles#

Profiles group services into named workflows so you don’t have to spin up everything every time. Working on a CSS tweak? Start just the frontend. Building a feature end-to-end? Fire up the full stack. Pick a profile from the Start button’s dropdown in the project toolbar and lpm starts those services right away, plus anything they depend on.

Start small. Even two profiles pay off right away — a lightweight one for quick UI fixes and a full one for feature work. Here’s the smallest useful setup: a frontend and a backend, with a frontend profile that skips the API when you don’t need it:

name: myapp
root: ~/Projects/myapp
services:
  web: npm run dev              # frontend UI
  api:
    cmd: node server.js
    port: 4000                  # backend API
profiles:
  # Just the frontend — fastest startup, good for UI-only fixes
  frontend: [web]
  # Full stack — frontend + backend for feature work
  full:     [web, api]

Every name in a profile list must match a service defined above in services. Services can appear in as many profiles as you like — overlap is fine and expected.

Multiple profiles for different modes. Once your project grows a third or fourth service — a background worker, a queue, a second frontend — a single profile isn’t enough. Define one profile per workflow you actually use, so you can jump between “just the UI”, “normal dev”, and “everything running” without touching the config:

name: shop
root: ~/Projects/shop
services:
  web: npm run dev              # React frontend
  api:
    cmd: python -m api.server
    port: 5000                  # Flask backend
  worker: celery -A tasks       # background jobs
profiles:
  # Quick UI fixes — no backend needed
  frontend: [web]
  # Normal day-to-day development — web + api
  local:    [web, api]
  # Everything, including background workers
  full:     [web, api, worker]

Config layers#

A project’s settings can come from three files. lpm merges them every time it loads the project, so your team can share one setup while you keep personal tweaks out of the repo. Higher layers win.

1. 1
   Your project file~/.lpm/projects/<name>.yml

   Everything: root or ssh, services, actions, terminals, profiles. Personal — stays outside the repo. The User tab in the app’s config editor.

2. 2
   Repo config<project root>/.lpm.yml

   Services, actions, terminals, profiles. Shared — commit it with the code. The Repo tab in the app’s config editor.

3. 3
   Global config~/.lpm/global.yml

   Actions and terminals. Every project on this Mac. The Global tab in the app’s config editor.

Sharing a setup with your team. Commit a .lpm.yml at the root of the repository. Anyone who adds the folder to lpm gets its services, actions, terminals, and profiles — no name or root needed, since those come from each person’s own project file:

services:
  web:
    cmd: npm run dev
    port: 3000
  api:
    cmd: npm run api
    cwd: ./server
    port: 4000
actions:
  test: npm test
  migrate:
    cmd: npm run db:migrate
    label: Migrate DB
    confirm: true
profiles:
  frontend: [web]
  full: [web, api]

Overriding one field. Entries with the same key merge field by field: whatever the higher layer sets wins, and anything it leaves out comes from the layer below. To run the shared web service on another port, override its command and port in your own file — everything else about it still comes from the repo:

name: shop
root: ~/Projects/shop
services:
  web:
    cmd: npm run dev -- --port 3100   # wins over the repo's cmd
    port: 3100                        # and its port; the rest is inherited

Global config#

Some things aren’t tied to any one codebase — system maintenance, utilities, your favorite agent. Put those in ~/.lpm/global.yml and they show up in every project automatically. If a project defines an action with the same key, the project-level entry wins. Edit it from Settings → Global Config, or the Global tab of any project’s config editor.

What a fresh install starts with. On a fresh install, lpm writes a global.yml with two terminal actions, claude and codex, so Claude Code and Codex are one click away in every project. Edit or remove them like any other entry. A minimal file of your own might add a Docker cleanup and a system monitor — notice there’s no name or root:

actions:
  docker-prune:
    cmd: docker system prune -f
    label: Docker Prune
    confirm: true             # asks before wiping images and caches

  htop:
    cmd: htop                 # live system monitor, one click away
    type: terminal

System-wide utilities. A fuller example: prune merged git branches, upgrade Homebrew, and keep a few system monitors one click away. These all live above individual projects — click them from any project and they just work.

actions:
  prune-branches:
    cmd: git branch --merged main | grep -v main | xargs git branch -d
    label: Prune merged branches
    confirm: true             # deletes local branches — ask first
  brew-upgrade:
    cmd: brew update && brew upgrade
    label: Brew upgrade       # keep Homebrew packages fresh

  htop:
    cmd: htop                 # live CPU and memory
    type: terminal
  btop:
    cmd: btop                 # prettier process viewer
    type: terminal
  ncdu:
    cmd: ncdu ~               # explore what's eating your disk
    type: terminal

Editing in the app#

You rarely need a text editor. Open a project’s config in lpm and you get one tab per layer — User, Repo, and Global — with three ways to change it.

From the terminal. lpm config validate <file> checks a project, repo, global, or template file (see Validation). Turn on Agent tools in Settings and coding agents like Claude Code and Codex can write and apply configs for you — see lpm skills for Claude Code and Codex.

Recipes#

Full working configs you can copy and adapt. The sections above each show one concept in isolation; the recipes here stitch services and actions together into configs that mirror how a real project looks on day one. Find the one closest to your stack, paste it into a new project, and tweak from there.

Minimal blog. Start here if you just want one dev server and nothing else — a personal blog, a tiny side project, the “hello world” version of lpm. One service, no actions, no ceremony.

name: blog
root: ~/Projects/blog
services:
  web: npm run dev # the only thing you need to hit Start

Blog with tests and linting. Add this when your tests, linter, or build start taking long enough that retyping them feels wasteful. Same dev server as above, plus three one-click buttons in the toolbar.

name: blog
root: ~/Projects/blog
services:
  web: npm run dev
actions:
  # one-click buttons for the chores you used to retype
  test: npm test
  lint: npm run lint
  build: npm run build

Next.js plus a Node API. For the classic two-process web app: a Next.js front-end in the project root and a Node backend in ./server. Shows how to set cwd per service, label a port, add a guarded deploy, and pin a log tail to its own terminal tab.

name: webapp
root: ~/Projects/webapp
services:
  web: npm run dev # Next.js front-end
  server:
    cmd: node server.js # API the front-end talks to
    cwd: ./server # lives in a subfolder
    port: 4000 # label for the Start menu and Open in browser
actions:
  deploy:
    cmd: ./scripts/deploy.sh
    confirm: true # ask before shipping
  logs:
    cmd: tail -f ./logs/server.log # keep server logs one click away
    type: terminal

Next.js with dev env vars. Pick this when your app needs a handful of environment variables to boot locally and you’re tired of remembering them. lpm sets them every time the service starts — keep real secrets in your own .env file, not here.

name: webapp
root: ~/Projects/webapp
services:
  web:
    cmd: npm run dev
    port: 3000
    env:
      # dev-only values — real secrets belong in your own .env
      API_URL: http://localhost:4000
      NEXTAUTH_SECRET: dev-secret
      NODE_ENV: development

Monorepo with an app and docs. For a repo that holds more than one thing you want running at once — say an app in apps/web and a docs site in apps/docs. Both services live under one project and start together, each from its own folder.

name: mono
root: ~/Projects/mono
services:
  web:
    cmd: npm run dev
    cwd: ./apps/web # one app in the monorepo
    port: 3000
  docs:
    cmd: npm run dev -- --port 3001 # lpm doesn't pass the port for you
    cwd: ./apps/docs # another app, started together
    port: 3001

Path resolution#

• ~ expands to your home directory in root
• Relative cwd paths resolve relative to root
• Absolute paths are used as-is
• On a local project, ~ is not expanded in cwd — a ~/… working folder is read as a folder named ~ inside the project, so use a relative or absolute path there
• On an SSH project, a relative cwd resolves from ssh.dir, and ~ means your home folder on the remote host