docsfs

package module

v1.28.1 Latest Latest Go to latest Published: Jul 8, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/geodro/lerd

Links

README ¶

Lerd

Open-source Herd-like local PHP development environment for Linux and macOS, with Windows supported via WSL2 (beta). Podman-native, rootless, with a built-in Web UI.

Lerd dashboard tour

Lerd runs Nginx, PHP-FPM, and your services as rootless Podman containers, designed for PHP developers on Linux and macOS, and on Windows through WSL2 (beta). No Docker. No sudo. No system pollution. Just lerd link and your project is live at project.test with HTTPS.

Built for Linux PHP developers

If you're a PHP developer on Linux and want frictionless local development — automatic .test domains, per-project PHP versions, one-click HTTPS, zero Docker — Lerd is built for you. Works with Laravel, Symfony, WordPress, Drupal, CakePHP, Statamic, and any custom PHP framework.

Features

🌐 Automatic .test domains with one-command TLS that auto-reissues before it expires, or opt out of lerd-managed DNS and use *.localhost, toggling lerd-managed DNS on or off later with dns:enable / dns:disable / dns:repair (no dnsmasq, no system resolver tweak, no sudo for the DNS bits)
🐘 Per-project PHP version (8.1–8.5, plus a frozen 7.4 / 8.0 legacy tier for hosted-on-the-old-stack projects), switch with one click
⚡ FrankenPHP runtime per site as an alternative to shared PHP-FPM, with Laravel Octane and Symfony Runtime worker mode
📦 Node.js isolation per project (Node 22, 24), or bun as the JS runtime on the host and, opt-in, inside the container
🖥️ Built-in Web UI with a dashboard root, sites and services overview dashboards, live widgets, a global Cmd+K command palette, install/remove of PHP and Node versions from the System page, and fourteen dashboard languages (English, German, Spanish, French, Indonesian, Dutch, Portuguese, Turkish, Simplified Chinese, Japanese, Romanian, Italian, Polish, Vietnamese)
✏️ Edit config in the browser — per-site and global nginx, per-version php.ini, .env files, and database/service runtime tuning, each validated (nginx -t where it applies), with timestamped backups and one-click restore
🧪 Tinker tab - in-browser PHP REPL per site with autocomplete (project models, composer helpers, PHP built-ins), live php -l syntax checking, and a collapsible tree view for dump() output. Works on Laravel (artisan tinker), Symfony, and any composer-based PHP project
🛰️ Debug window that intercepts every dump() / dd() and streams it to the dashboard, TUI (D key), MCP, and lerd dump tail, scoped per site and per worktree branch, with the original response left clean unless you flip passthrough on. The same window captures SQL queries with N+1 and slow-query detection, plus outgoing mail, rendered views, dispatched events, queued jobs, and outgoing HTTP, across both Laravel and Symfony, with optional opt-in capture of queue-worker activity
🔥 SPX profiler with one-click on/off, every PHP-FPM request becomes a flame graph viewable in a same-origin Profiler view in the dashboard. No FPM restart, no code changes, and lerd profile run profiles a one-shot artisan or CLI command
📈 Request timing analytics per site, a durable view of typical and p95 response times, throughput, error rate, and the slowest routes ranked by recent p95 with one-click profiling, surfaced as a site-doctor warning and an opt-in slow-route push notification, all read from real traffic. Agents get the same signal over MCP with route_timing and optimize_route, which joins a slow route to the N+1 queries and CPU hotspots behind it
🩺 Site doctor — framework-agnostic health checks (env file and drift, application key, composer/node install and lockfile state, security audits, database presence, PHP version range) plus each framework's own store-declared checks, from the web UI, the TUI, lerd site:doctor, and MCP, with one-click fixes for dependency and audit findings
💻 Terminal dashboard (lerd tui) - btop-style TUI with live status, site detail pane, inline domain and version editing, shell drop-in, log tailing, and filter/sort — the same operations surface as the web UI, for tmux and SSH workflows
🗄️ One-click services: MySQL, PostgreSQL, Redis, Meilisearch, RustFS, Mailpit, Gotenberg, Stripe Mock, Reverb, soketi, OpenSearch, RedisInsight, Beanstalkd and more, the default stack built in and every add-on fetched from an external store that updates without a new lerd release. Each is a YAML preset you can update, migrate, rollback, or reinstall in place, including a reset-data reinstall that auto-recreates linked sites' databases and buckets. Move a project's database between same-family services with lerd db:move, expose each service's client tools (mysqldump, pg_dump, psql, redis-cli) as host shims with lerd shims, control published and extra ports from the dashboard or lerd service port, and coexist with a host-installed database of the same engine by auto-shifting the container's published port
🔗 Site groups — group related sites so a main owns a base domain and the rest occupy its subdomains, with a shared or separate database per secondary
🧱 Host-proxy sites — run a Node, Python, Go, or any non-PHP dev server on the host and have nginx serve it at a .test domain with HTTPS, git worktrees included
🌳 First-class git worktrees with auto-detected branch domains, per-worktree PHP/Node versions, optional per-worktree database isolation (clone from main or empty), a per-worktree LAN-share proxy, env_overrides templating in .lerd.yaml for multi-tenant apps, automatic wildcard cert SANs for *.branch.site.test, a built-in Vite dev server worker that runs on the host per branch, and a dashboard modal for adding and removing worktrees without touching the CLI
⚒️ Worker self-heal, failed queue, schedule, horizon, reverb, and stripe workers are surfaced everywhere (CLI, dashboard banner, TUI, MCP) and recovered with one click or lerd worker heal
💤 Idle-suspend, activity-driven suspension of a site's workers (queue, schedule, horizon, reverb, stripe, Vite) after a configurable idle timeout, resumed on the next request, CLI command, MCP call, or file save, with per-site pinning
📋 Live logs for PHP-FPM, Queue, Schedule, Reverb, per site
🔒 Rootless & daemonless - Podman-native, no Docker required, dual-stack IPv4 + IPv6
🤖 MCP server - let AI assistants (Claude Code, Cursor, JetBrains Junie, Codex CLI, Gemini CLI, GitHub Copilot, Google Antigravity, Windsurf) manage your environment directly
🧩 Framework store - community definitions for Laravel, Symfony, WordPress, Drupal, CakePHP, Statamic with versioned auto-detection
⚡ Framework-agnostic workers, env setup, and nginx proxy — driven by YAML definitions, not hardcoded

AI Integration (MCP)

Lerd ships a built-in Model Context Protocol server. Connect it to Claude Code, Cursor, JetBrains Junie, Codex CLI, Gemini CLI, GitHub Copilot, Google Antigravity, Windsurf, or any MCP-compatible AI assistant and manage your dev environment without leaving the chat.

lerd mcp:enable-global   # register once, works in every project

Then just ask:

You: set up the project I just cloned
AI:  → site(action: "link")
     → exec(action: "composer", args: ["install"])
     → env(action: "setup")        # detects MySQL + Redis, starts them, creates DB, generates APP_KEY
     → framework(action: "setup")  # storage:link + migrate for Laravel, doctrine:migrations:migrate for Symfony
     ✓  myapp → https://myapp.test ready

Eleven grouped tools, each driven by an action: site, service, db, env, runtime, worker, exec, framework, diag, logs, and worktree. Scaffold projects, run migrations, manage services, toggle workers, tail and search logs, enable Xdebug, manage databases and PHP extensions, park directories, switch runtimes between PHP-FPM and FrankenPHP, and more, all from your AI assistant.

📖 MCP documentation

Why Lerd?

	Lerd	DDEV	Lando	Laravel Herd
Podman-native	✅	🟡	❌	❌
Rootless	✅	❌	❌	✅
Web UI	✅	❌	❌	✅
Terminal dashboard	✅	❌	❌	❌
Linux	✅	✅	✅	❌
macOS	✅	✅	✅	✅
Windows (WSL2)	🧪	✅	✅	✅
MCP server	✅	❌	❌	✅

🟡 DDEV runs on Docker by default and can also use Podman as an alternative runtime; Lerd is built exclusively for rootless Podman.

🧪 Lerd's Windows support runs inside WSL2 and is currently beta, see the Windows (WSL2) guide.

Install

Linux

curl -fsSL https://lerd.sh/install.sh | bash

Update later with:

lerd update

macOS

curl -fsSL https://lerd.sh/install.sh | bash

Update later with:

lerd update

The installer needs the podman CLI; it will offer to brew install podman if it's missing.

Install via Homebrew instead

brew install lerd-env/lerd/lerd
lerd install

Recent Homebrew versions block third-party taps until trusted, so you may need to run brew trust lerd-env/lerd first. Update later with brew upgrade lerd && lerd install.

NixOS

NixOS has its own flake, since its declarative model doesn't fit the one-line installer's imperative DNS and self-install steps.

nix run github:lerd-env/lerd-nixos -- --help

The lerd-nixos flake packages the binary and ships the configuration.nix blocks the stack needs. See the NixOS guide for the full runbook.

[!NOTE] See the installation docs for details.

Quick Start

cd my-laravel-project
lerd link
# → https://my-laravel-project.test

lerd install already starts everything for you on first run, so you can lerd link immediately. Day-to-day:

lerd start          # boot DNS, nginx, PHP-FPM, services, workers, UI
lerd stop           # stop containers and workers (UI and watcher stay up)
lerd quit           # full shutdown including UI, watcher, and tray
lerd autostart enable   # boot lerd on every login
lerd status         # health snapshot

See Start, Stop & Autostart for the full lifecycle reference.

Framework Store

Install community framework definitions from lerd-env/frameworks:

lerd framework search                   # list all available
lerd framework install symfony          # auto-detects version from composer.lock
lerd framework install drupal@11        # explicit version
lerd framework list --check             # compare local vs store

Frameworks auto-detect when you lerd link a project. Workers, env setup, nginx proxy, and setup commands are all driven by the framework definition — no hardcoded behavior.

Services work the same way. The binary ships the default stack and every add-on lives in lerd-env/services, fetched on demand and cached, so a new service ships without a new lerd release:

lerd service search                     # browse the store
lerd service preset pgadmin             # install a store-only preset

Documentation

📖 lerd.sh

License

MIT

Documentation ¶

Index ¶

Variables

Constants ¶

This section is empty.

Variables ¶

View Source

var FS embed.FS

Functions ¶

This section is empty.

Types ¶

This section is empty.

Source Files ¶

View all Source files

docsfs.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
lerd command
lerd-tray command
internal
activityping Package activityping is the host-side client for the lerd-watcher's idle control socket: it keeps a worked-on site awake under idle-suspend and asks the watcher to resume all suspended workers when the feature is switched off.	Package activityping is the host-side client for the lerd-watcher's idle control socket: it keeps a worked-on site awake under idle-suspend and asks the watcher to resume all suspended workers when the feature is switched off.
agentenv Package agentenv forwards AI coding-agent detection variables across the container boundary so tools like laravel/pao (via laravel/agent-detector) still switch to JSON output when run through `lerd php`, tinker, or MCP.	Package agentenv forwards AI coding-agent detection variables across the container boundary so tools like laravel/pao (via laravel/agent-detector) still switch to JSON output when run through `lerd php`, tinker, or MCP.
applog
certs
cfgedit Package cfgedit is a small service for editing user-owned config files that lerd seeds but never overwrites (per-site nginx overrides, the global http-level nginx override, php.ini overrides).	Package cfgedit is a small service for editing user-owned config files that lerd seeds but never overwrites (per-site nginx overrides, the global http-level nginx override, php.ini overrides).
cleanup Package cleanup reclaims podman disk lerd's own image rebuilds leave behind.	Package cleanup reclaims podman disk lerd's own image rebuilds leave behind.
cli
composer Package composer holds settings shared by every code path that runs composer inside a lerd FPM container — the `lerd composer` CLI and the MCP composer tools alike — so they stay consistent.	Package composer holds settings shared by every code path that runs composer inside a lerd FPM container — the `lerd composer` CLI and the MCP composer tools alike — so they stay consistent.
config
devtoolsops Package devtoolsops contains the shared logic for toggling the lerd_devtools collector.	Package devtoolsops contains the shared logic for toggling the lerd_devtools collector.
dns
dumps Package dumps receives, buffers, and fans out PHP `dump()`/`dd()` events captured by the lerd debug bridge (auto_prepend_file).	Package dumps receives, buffers, and fans out PHP `dump()`/`dd()` events captured by the lerd debug bridge (auto_prepend_file).
dumpsops Package dumpsops contains the shared business logic for toggling the lerd debug bridge.	Package dumpsops contains the shared business logic for toggling the lerd debug bridge.
envfile Package envfile provides helpers for reading and updating .env files while preserving comments, blank lines, and line order.	Package envfile provides helpers for reading and updating .env files while preserving comments, blank lines, and line order.
eventbus Package eventbus is an in-process pub/sub hub for UI state-change events.	Package eventbus is an in-process pub/sub hub for UI state-change events.
feedback Package feedback renders lerd's CLI progress output (animated steps, a live line, summaries, prompts, warnings) and owns the shared lerd colour palette.	Package feedback renders lerd's CLI progress output (animated steps, a live line, summaries, prompts, warnings) and owns the shared lerd colour palette.
freeport Package freeport provides a shared, dependency-free TCP host-port allocator: a dual-stack bindability probe and a predicate-injected free-port search.	Package freeport provides a shared, dependency-free TCP host-port allocator: a dual-stack bindability probe and a predicate-injected free-port search.
git
grouping Package grouping manages site groups: a main site that owns a base domain and one or more secondary sites that each occupy a chosen subdomain label of that base domain (e.g.	Package grouping manages site groups: a main site that owns a base domain and one or more secondary sites that each occupy a chosen subdomain label of that base domain (e.g.
idle Package idle implements activity-driven worker suspension: it tracks when each site was last active and (later) suspends a quiet site's suspendable workers, resuming them on the next activity.	Package idle implements activity-driven worker suspension: it tracks when each site was last active and (later) suspends a quiet site's suspendable workers, resuming them on the next activity.
imgledger Package imgledger records the container image refs lerd itself pulled.	Package imgledger records the container image refs lerd itself pulled.
logsource Package logsource gives a single, filtered view over every log lerd can reach: framework application log files, PHP-FPM/nginx/dns/service container stdout, and worker/watcher/ui units (systemd journal on Linux, launchd log files on macOS).	Package logsource gives a single, filtered view over every log lerd can reach: framework application log files, PHP-FPM/nginx/dns/service container stdout, and worker/watcher/ui units (systemd journal on Linux, launchd log files on macOS).
man
mcp
nginx
node
origin Package origin centralises every URL lerd fetches its own assets from: release binaries, the framework and service stores, the changelog, and the GHCR base images.	Package origin centralises every URL lerd fetches its own assets from: release binaries, the framework and service stores, the changelog, and the GHCR base images.
php
phpantom Package phpantom manages the phpantom_lsp PHP language server binary that powers tinker autocomplete, diagnostics, and hover in the web UI.	Package phpantom manages the phpantom_lsp PHP language server binary that powers tinker autocomplete, diagnostics, and hover in the web UI.
podman
presetfixtures Package presetfixtures embeds the add-on service presets that ship in the external lerd-env/services store rather than the binary, and exposes them as an fs.FS.	Package presetfixtures embeds the add-on service presets that ship in the external lerd-env/services store rather than the binary, and exposes them as an fs.FS.
profiler Package profiler turns the SPX profiler on or off globally.	Package profiler turns the SPX profiler on or off globally.
push Package push owns Web Push plumbing: per-install VAPID keys, browser subscription store, and the encrypted POST that wakes a service worker when the notifier dispatches a new event.	Package push owns Web Push plumbing: per-install VAPID keys, browser subscription store, and the encrypted POST that wakes a service worker when the notifier dispatches a new event.
registry Package registry queries OCI registries for available tags so lerd can surface "update available" badges and apply minor/patch updates to default services.	Package registry queries OCI registries for available tags so lerd can surface "update available" badges and apply minor/patch updates to default services.
reqstats Package reqstats turns the nginx access feed into a per-site view of request timing: the typical response time and the routes that run well above their own baseline.	Package reqstats turns the nginx access feed into a per-site view of request timing: the typical response time and the routes that run well above their own baseline.
serviceops Package serviceops contains the shared business logic for installing, starting, stopping, and removing lerd services.	Package serviceops contains the shared business logic for installing, starting, stopping, and removing lerd services.
services Package services provides a platform-agnostic abstraction over the underlying service manager (systemd on Linux, launchd on macOS).	Package services provides a platform-agnostic abstraction over the underlying service manager (systemd on Linux, launchd on macOS).
shims Package shims is the single owner of the client-tool host shims that lerd services expose (mysqldump, pg_dump, psql…): the tri-state install decisions, host-conflict detection, script generation, and the reconcile that brings the shim dir in line with the installed services.	Package shims is the single owner of the client-tool host shims that lerd services expose (mysqldump, pg_dump, psql…): the tri-state install decisions, host-conflict detection, script generation, and the reconcile that brings the shim dir in line with the installed services.
sitedoctor Package sitedoctor runs app-level health checks for a single site.	Package sitedoctor runs app-level health checks for a single site.
siteinfo
siteops
spxreport Package spxreport reads the SPX profiler's on-disk captures and distills each into a handful of timing outliers.	Package spxreport reads the SPX profiler's on-disk captures and distills each into a handful of timing outliers.
stats Package stats reads cheap per-container resource usage via `podman stats` and exposes a structured view both lerd-ui (for the dashboard widget) and the TUI (for its Dashboard pane) can share.	Package stats reads cheap per-container resource usage via `podman stats` and exposes a structured view both lerd-ui (for the dashboard widget) and the TUI (for its Dashboard pane) can share.
store
systemd
tray
tui Package-level UI helpers: small render primitives that don't fit cleanly into any one feature module.	Package-level UI helpers: small render primitives that don't fit cleanly into any one feature module.
ui
unitlog Package unitlog centralises how lerd locates a unit's logs across platforms: whether a unit runs as a detached podman container (logs via `podman logs`) versus a launchd-supervised service on macOS (logs in ~/Library/Logs/lerd), and the framework-worker classification both decisions lean on.	Package unitlog centralises how lerd locates a unit's logs across platforms: whether a unit runs as a detached podman container (logs via `podman logs`) versus a launchd-supervised service on macOS (logs in ~/Library/Logs/lerd), and the framework-worker classification both decisions lean on.
update
version Package version holds build-time version information injected via ldflags.	Package version holds build-time version information injected via ldflags.
watcher
workerheal Package workerheal detects and recovers worker units stuck in systemd's "failed" state.	Package workerheal detects and recovers worker units stuck in systemd's "failed" state.
wsl Package wsl holds the WSL2-specific detection and config-patching logic that `lerd wsl:setup` and the doctor's WSL checks share.	Package wsl holds the WSL2-specific detection and config-patching logic that `lerd wsl:setup` and the doctor's WSL checks share.
xdebugops Package xdebugops contains the shared business logic for toggling Xdebug on a PHP version: mode validation, config persistence, ini write, FPM quadlet update, and unit restart.	Package xdebugops contains the shared business logic for toggling Xdebug on a PHP version: mode validation, config persistence, ini write, FPM quadlet update, and unit restart.
pkg
distro