Lerd

Lerd, a local PHP development environment

This project runs on lerd, a Podman-based PHP development environment. It is framework-agnostic: Laravel, Symfony, WordPress, Drupal, Magento, CakePHP and any custom framework are all driven by a framework definition (YAML), never by lerd hardcoding a framework's name. The lerd MCP server is available — use it to manage the environment without leaving the chat.

The MCP surface is twelve grouped tools, each driven by an action argument: site, service, db, env, runtime, worker, exec, framework, diag, logs, worktree, workspace. Always pass action. Most actions also accept an optional path that defaults to the directory the assistant was opened in (then LERD_SITE_PATH if set), so you can usually omit it. Start by calling site with action: "list" to discover sites.

Architecture

• PHP runs in Podman containers named lerd-php<version>-fpm (e.g. lerd-php84-fpm); each container includes composer and node/npm; the PHP version is resolved from .lerd.yaml → .php-version → composer.json require.php constraint (matched against installed versions) → global default
• Nginx routes *.test domains to the correct PHP-FPM container
• Services (MySQL, Redis, PostgreSQL, etc.) and custom services run as Podman containers via systemd quadlets
• Node.js versions run through a version manager, fnm (bundled, fetched on demand) or user nvm (declining managed Node picks nvm; node.manager + node.nvm_dir; node:manager/dashboard; nvm keeps PATH, fnm uses shims); per-project version via a .node-version file. The package manager is the project's, not lerd's: a packageManager pin in package.json wins, then the lockfile (pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lock* → bun, else npm). pnpm and yarn run through corepack, and installs use the manager's frozen-lockfile mode (pnpm install --frozen-lockfile, yarn install --immutable, npm ci). Never assume npm run dev/npm ci — the worker command and the setup steps follow the detected manager
• Framework workers (queue, schedule, reverb, horizon, messenger, vite, etc.) run as systemd user services named lerd-<worker>-<sitename>; commands are defined per-framework in YAML; Laravel Horizon is auto-detected from composer.json and replaces the queue toggle when installed; Laravel ships with a vite host worker that runs the project's dev script on the host for HMR, through whichever package manager the project pins; workers and setup commands support optional check (file or composer) for conditional visibility; workers with conflicts_with auto-stop conflicting workers on start. Per-worker flags: host: true (run on host via the version manager instead of in FPM container — HMR-sensitive Node tools), per_worktree: true (worker runs independently per worktree under lerd-<worker>-<site>-<branch>), replaces_build: true (worker provides asset manifest while running, so a worktree add skips the static npm run build step when this worker is opted in)
• Custom workers can be added per-project (.lerd.yaml custom_workers) or globally (~/.config/lerd/frameworks/<name>.yaml); use the worker tool's add/remove actions — both survive framework store updates
• Framework setup commands (one-off bootstrap steps like migrations, storage links) are defined in the framework YAML and shown by framework action: "setup"; Laravel has built-in storage:link/migrate/db:seed; custom frameworks can define their own
• Service version placeholders ({{mysql_version}}, {{postgres_version}}, {{redis_version}}, {{meilisearch_version}}) are available in framework env vars and resolved from the service image tag at env-setup time
• Custom containers: non-PHP sites (Node.js, Python, Go, etc.) can define a Containerfile.lerd and a container: section in .lerd.yaml with a port; lerd builds a per-project image, runs it as lerd-custom-<sitename>, and nginx reverse-proxies to it; the project directory is volume-mounted at its host path with --workdir set automatically — do NOT add WORKDIR or COPY to the Containerfile; workers exec into the custom container; services are accessible by name on the shared lerd Podman network; hot-reload file watchers must use polling on macOS (inotify does not fire across Podman Machine's virtiofs mount) — nodemon: --legacy-watch, Vite: server.watch.usePolling: true, webpack: watchOptions: { poll: 1000 }
• Custom-image PHP sites (custom-FPM): a PHP project can define a Containerfile.lerd (must build FROM lerd-php<ver>-fpm:local) plus a container: section with no port; lerd builds a per-site image (lerd-custom-<site>:local), runs a dedicated FPM container lerd-cfpm-<site>, and serves it by fastcgi instead of the shared lerd-php<ver>-fpm. It is a normal PHP site otherwise (xdebug, dumps, profiler, lerd shell, php/artisan/composer/tinker, queue/horizon all run in the per-site container). The PHP version is fixed by the FROM line (the UI version selector is read-only); lerd rebuild rebuilds the image. Same key as custom containers, the port is the discriminator: with a port it is a reverse-proxied non-PHP app, without a port it is a fastcgi PHP image. runtime for these reports fpm-custom.
• Git worktrees automatically get a <branch>.<site>.test subdomain (deep *.<branch>.<site>.test wildcard cert + nginx server_name on secured sites); vendor/, node_modules/, .env are seeded from the main checkout. .lerd.yaml env_overrides declares templated env vars ({{domain}}, {{scheme}}, {{site}}) layered on the default APP_URL rewrite — for multi-tenant apps (per-branch cookies, signed-URL hosts, tenant routing)

DNS modes

Lerd has two install-time DNS modes recorded in ~/.config/lerd/config.yaml:

• Managed (default): dns.enabled: true, dns.tld: test. Sites at *.test via lerd-dns + mkcert; site tls_enable works.
• Disabled: dns.enabled: false, dns.tld: localhost. Sites at *.localhost via RFC 6761; no mkcert CA, TLS toggling unavailable.

Read diag action: "status" for dns.tld and dns.enabled instead of assuming .test; do not propose tls_enable when dns.enabled is false.

MCP tools

Twelve grouped tools, each selecting behaviour via action.

site — sites and their configuration

Actions: list (discover sites — CALL FIRST), link, unlink, domain_add, domain_remove, group_assign, group_unassign, group_label, group_db, group_list, tls_enable, tls_disable, tls_renew, php, node, pause, unpause, restart, rebuild, runtime, nginx_read, nginx_write, nginx_reset, park, unpark.

• link registers a directory; non-PHP sites need .lerd.yaml container.port + a Containerfile first, or they register as PHP (wrong)
• link runs lerd link and returns its output verbatim, so read the reply. It will NOT start a proxy.command dev server (command not approved); ask the user to run lerd link --yes
• domain_* take a domain without the .test TLD; you can't remove the last domain
• group_* nest a secondary site under a main's subdomain (one level deep): they identify the secondary by path (defaults to cwd), not by site; group_assign with main + label (+ optional share_db), group_db = share|separate
• a group secondary follows its main's HTTPS: group_assign under a secured main secures the secondary, tls_enable on a main secures its secondaries too, and tls_disable on a secondary is refused while its main is secured (the main's *.<main> wildcard would answer the subdomain and serve the main's app). Disable the main's TLS first
• certificates renew themselves before they expire; tls_renew forces it by hand for one site
• php/node take version; pass branch to pin the override on a worktree's checkout
• runtime switches fpm ↔ frankenphp (worker: true enables frankenphp worker mode)
• nginx_write saves a custom override (runs nginx -t, backs up, reloads); branch targets a worktree
• park registers a parent dir and auto-registers every PHP project under it; unpark reverses it (project files kept)

service — built-in & custom services

Actions: start, stop, restart, pin, unpin, update, rollback, migrate, remove, reinstall, add, expose, port, env, config_read, config_write, config_restore, config_reset, config_list_backups, preset_list, preset_search, preset_install, check_updates, entities, entity_action.

• update pulls a newer image (safe, in-strategy); migrate dumps + restores across a cross-strategy upgrade; reinstall with reset_data: true wipes data and reprovisions; remove with remove_data: true renames the data dir aside
• stop marks the service paused — lerd start skips it until started again; pin keeps it always running
• add registers a custom OCI service (depends_on wires dependencies, init: true for mysql/mariadb); prefer preset_install for anything in preset_list (phpmyadmin, pgadmin, mongo, mongo-express, selenium, stripe-mock, mysql, mariadb…)
• preset_list returns the installable presets with the metadata each one declares: category (the discovery heading), icon, and admin_for — the services this preset's admin UI administers, which is not depends_on. phpMyAdmin depends on mysql but administers mariadb too, and RedisInsight administers valkey without depending on it. To answer "which dashboard administers this database", read admin_for, not depends_on. preset_search queries the store by name for presets that are not bundled locally
• env returns the recommended .env connection keys; expose publishes an extra host:container port
• port moves the service's primary published host port (published_port, or reset: true for the default); it stays bound to 127.0.0.1, the container-internal port is unchanged, and a host-proxy site that points at the old port is realigned automatically
• entities lists what a service holds that is not a database: the kinds its preset declares (RustFS buckets today, more later), each kind's rows and the actions it supports. Databases have their own tool, so they are not repeated here. entity_action runs one of those declared actions (kind, entity, entity_action); export and import stream a file and stay on the CLI and the dashboard
• config_* read/write/restore/reset a service's runtime tuning override

db — databases

Actions: list, set, move, create, export, import, snapshot, snapshots, restore, snapshot_delete, extension_list, extension_add.

• list reports an engine's databases with sizes; service picks the engine, else it resolves from the project. No introspect command, nothing to report
• set picks the project DB (database: sqlite, mysql, postgres, or a family alternate like mariadb / postgres-pgvector / postgres-timescaledb / mysql-5-7); persists to .lerd.yaml, rewrites DB_ keys, starts the service, creates the DB + _testing
• move migrates sites between two installed same-family services (from/to, sites: [...] or all: true) and repoints each .env; source data is left intact
• create/export/import auto-detect service and database; pass service to override. import drops a hosted provider's ownership/DEFINER statements (which can never apply here) and creates any extension the dump's types need; pass fresh: true to empty the database first so a dump replaces what is there instead of colliding with it. What an engine can list and act on is declared in its preset, so this is not a mysql/postgres-only set
• extension_list/extension_add are postgres-only. An import already creates whatever extension the dump's types reach for, so use these to see what the engine offers and what the database has, or to add one (extension: postgis) before any dump arrives
• snapshot/snapshots/restore/snapshot_delete are named, restorable snapshots (MySQL/MariaDB/PostgreSQL); restore is destructive; all_databases covers the whole service

env — .env management

Actions: setup, check, override.

• setup configures services, DBs, APP_KEY and APP_URL; on a fresh Laravel clone call db set first to move off sqlite, then env setup, then ALWAYS framework setup or migrations never run
• check compares .env against .env.example
• override manages the personal, gitignored .env.lerd_override (its set KEY=VALUE win over lerd defaults; LERD_EXTERNAL_SERVICES=<svc,svc> marks vars lerd writes but won't start)

runtime — PHP/Node versions & extensions

Actions: versions, node_install, node_uninstall, node_manager, php_list, ext_list, ext_add, ext_remove, ports_list, ports_add, ports_remove, ini_read, ini_write, ini_reset.

• ext_add/ext_remove change one declared set applying to EVERY PHP version, so a site keeps its extensions across a version change. They rebuild one version's FPM container now (slow); others rebuild on next use. ext_add accepts apk_deps for extra Alpine build packages
• ext_list reports the declared set plus, per version: has it, predates the set (rebuild fixes), or cannot load it (rebuild won't). Never assume a declared ext is present: mongodb needs 8.1+, 7.4/8.0 are Alpine 3.16
• node_manager with no argument reports the version manager lerd drives, whether nvm is present and whether lerd manages Node at all; with manager: fnm|nvm it switches, which also rewrites the PATH shims and regenerates host workers
• php_list sets base_update when the published base image a version was built from has been republished (an upstream PHP or Alpine fix); lerd php:rebuild <version> picks it up
• ports_add/ports_remove/ports_list publish extra host ports on a PHP version's shell (FPM) container so a process started in lerd shell is reachable at localhost:PORT. ports_add takes host and optional container (defaults to host); a busy host port shifts to the next free one. Per version and independent, loopback-bound (follows lan:expose), restarts that version's FPM. Prefer host-proxy or a worker+proxy for a single site. CLI: lerd php:ports add/remove/list [--php version]
• ini_read/ini_write/ini_reset edit php.ini: pass version for a per-version file, or shared: true for the shared file applied to every version. The shared file loads below the per-version one, so a per-version key still wins and an unknown key on some version is ignored (not fatal). Prefer shared for a setting you want everywhere, so a version change never drops it. ini_write takes full content, backs up, and restarts the affected FPM containers. CLI: lerd php:ini [version|shared]
• extra Alpine packages: lerd php:pkg add/remove/list <packages> (CLI) bakes runtime apk packages (CLI tools, libs) into every FPM image, saved in config under php.packages and re-applied on every rebuild, so they survive php:rebuild and base image updates. One declared set applies to every PHP version. Layered onto the shared image, not the published base.
• Pest browser testing (CLI-only): lerd pest:browser install|doctor|remove [version] sets up pestphp/pest-plugin-browser inside the FPM container by baking Alpine's musl chromium into the images. Chromium only, and current PHP versions only (the 7.4/8.0 legacy tier is rejected). Needs the playwright npm package first; re-run install after bumping it. Tests then run through the normal lerd test/lerd pest.
• bun: lerd never installs or version-manages bun. On the host, JS install/dev/build run through bun when the project is a bun project (bun.lockb/bun.lock/bunfig.toml/packageManager: bun) or when Node is unmanaged, no system Node exists, and bun is present. CLI-only: lerd node:manage/node:unmanage opt in or out of lerd-managed Node (unmanage drops fnm versions, never a user's nvm ones), lerd js:runtime [bun|node|auto] pins one site's runtime, and lerd php:bun install|update|version manages an in-container bun for lerd shell. These are host operations, not container exec actions.

worker — background workers

Actions: list (CALL FIRST), start, stop, add, remove, health, heal, mode_get, mode_set, and the framework workers queue_start, queue_stop, horizon_start, horizon_stop, reverb_start, reverb_stop, schedule_start, schedule_stop, stripe_start, stripe_stop, stripe_config.

• call list to discover a site's workers before start; pass branch to target a per-worktree unit
• use horizon_* instead of queue_* when laravel/horizon is installed (mutually exclusive); queue_start needs Redis running when QUEUE_CONNECTION=redis
• add saves a custom worker to .lerd.yaml (or the user overlay with global: true); does not auto-start
• health reports unhealthy units (read-only); heal resets and restarts them (unit for one, omit for all); mode_get reports the macOS worker runtime, mode_set switches it (mode: exec|container)
• a worker's health state is one of failed (the unit died), expected-but-stopped (it should be running and isn't), or unreachable — the unit is happily active but the server it publishes no longer accepts connections, a dev server that wedged without exiting. All three are heal-able; heal restarts the unit. Per-worktree units (lerd-<worker>-<site>-<branch>) are covered by the same pass, so a dead per-worktree Vite heals like any other. A worker with a schedule is a oneshot driven by a timer and is idle between ticks by design, which is healthy
• Stripe secret is read from .env (STRIPE_SECRET / STRIPE_SECRET_KEY / STRIPE_API_KEY); stripe_config sets webhook_path / secret_env_key in .lerd.yaml
• Auto-reload (CLI-only): lerd horizon:reload [on|off] and lerd octane:reload [on|off] (FrankenPHP worker mode) restart workers on file changes; both need the project's chokidar npm package
• Idle-suspend (CLI-only): lerd idle on/off toggles activity-driven suspension globally; suspended workers stop after the idle timeout (lerd idle timeout <dur>) and resume on the next request/CLI/MCP/file-save. lerd idle pin/unpin <site> exempts a site; lerd idle status reports policy and last-active. A worker shown as suspended is healthy, not failed, so do not heal it