PHP development on Omarchy

Omarchy hands you a finished Arch and Hyprland desktop: the terminal, the editor, the keybindings and the theming are all decided for you. What it deliberately does not decide is your web stack. There is no nginx, no PHP-FPM, no .test routing and no local TLS, so the first day of any PHP work on a fresh Omarchy box is the one part of the setup that is still yours to solve.

Lerd is that missing half. One install, and every project gets a .test URL, a trusted certificate, the PHP version it asks for and the databases it needs, all as rootless Podman containers under your own user. It fits the Omarchy shape: no sudo after install, nothing written into system directories, everything under ~/.config and ~/.local/share, and a bar widget so the state of the stack is on screen instead of behind a command.

curl -fsSL https://lerd.sh/install.sh | bash
cd ~/code/myapp
lerd link

Your project is live at https://myapp.test. That is the whole setup.

Why it suits Omarchy

What Omarchy already gives you	What Lerd adds on top
Arch with a curated package set, Hyprland launched through uwsm	nginx, PHP-FPM and services as rootless Podman containers, managed by systemd user units
A terminal, an editor, and language toolchains you install yourself	PHP 7.4 and 8.0 to 8.5, picked per project by lerd isolate 8.4 or read from composer.json
No local web server, no vhost management	An nginx vhost generated on lerd link, with overrides when a project needs them
No local domain routing	Automatic .test domains through a dnsmasq container wired into systemd-resolved, no /etc/hosts edits
No local TLS	lerd secure, a real mkcert certificate trusted by your system and browsers
Docker available if you install it	Rootless Podman, no daemon, no root, no docker-compose.yml per project
A themed bar with a plugin system	A native bar widget showing sites, services, workers, DNS and container memory
A tray that follows graphical-session.target	A system tray that autostarts there, because Omarchy runs Hyprland under uwsm

Installing on Omarchy

Omarchy is Arch-based, so the installer takes the Arch path and Podman is already new enough. Arch ships podman 4.5 or newer out of the box, which is Lerd's minimum.

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

The installer checks the prerequisites, offers to install anything missing, points the system resolver at the .test domains (the one place it needs sudo) and installs the binary to ~/.local/bin/lerd. Nothing goes into /usr/local.

Two Arch defaults are worth knowing about, because they differ from the Debian and Fedora side:

crun is not the default runtime. Arch defaults to runc. Both work, but crun is lighter and purpose-built for rootless containers, and lerd doctor will tell you it is missing:

sudo pacman -S crun

nss provides certutil. mkcert needs it to install the CA into Chrome and Firefox, so lerd secure produces a certificate the browser accepts with no warning page:

sudo pacman -S nss

Then start it and check the environment:

lerd start
lerd doctor

lerd doctor is the fastest way to confirm the resolver, the trust store, linger and the container runtime all landed correctly. If systemctl --user units do not survive logout, run loginctl enable-linger $USER once.

The bar widget

lerd Glance is an optional plugin for the Omarchy Quattro shell. It carries Lerd's mark in the bar and stays quiet while everything is healthy, showing a coloured dot only when a service, a worker or DNS needs attention.

omarchy plugin add https://github.com/lerd-env/lerd-omarchy-glance.git --enable

Clicking opens a panel with the site and service counts, one row per worker type, nginx and .test resolution status, the running PHP versions, the containers with their versions and ports, and total CPU and memory across the whole environment. Two buttons: open the dashboard, and clean up reclaimable disk space when there is any.

It reads the local dashboard API on 127.0.0.1:7073 and sends nothing anywhere else.

The tray, and the uwsm detail

Lerd's tray unit is wired to graphical-session.target. Omarchy launches Hyprland through uwsm, which reaches that target on login, so the tray autostarts with no extra work.

This is worth knowing if you ever move off Omarchy's session setup: bare Hyprland, Sway or i3 started without uwsm never reaches graphical-session.target, and the tray will not autostart. Either run the compositor under uwsm, or change WantedBy=graphical-session.target to WantedBy=default.target in ~/.config/systemd/user/lerd-tray.service. Every other Lerd unit uses default.target and is unaffected either way.

.test domains on a systemd-resolved-only host

Omarchy uses systemd-resolved without NetworkManager, which used to be the awkward case: .test resolution could stop working when there was no network link for systemd-resolved to hang the route on.

Lerd now keeps an always-up dummy interface, lerd0, that carries the ~test route. Because that link never goes down, systemd-resolved keeps forwarding .test to the Lerd resolver even with no network connection at all. It is created by a small system service, lerd-dns-link.service, which starts on every boot, so it survives reboots and applies on your next lerd start with nothing to run by hand.

If you would rather not touch the system resolver at all, pick the .localhost mode at install time. .localhost resolves to loopback by convention, so no resolver configuration is involved and the dnsmasq and certutil prerequisites are skipped entirely.

A first project

lerd new myapp          # scaffolds through the framework's own installer, then links it
cd myapp
lerd service start mysql
lerd env                # rewrites .env to match the running services

Or take a repo you already have:

cd ~/code/existing-app
lerd link

Lerd detects the framework, picks the PHP version from composer.json, writes the vhost, registers the .test hostname and provisions the certificate. Use lerd init instead if you would rather choose the PHP version, HTTPS and services through a wizard and commit the answers to .lerd.yaml.

Services are shared rather than per project, which is why several running sites cost around 200 MB of RAM rather than a full stack each. MySQL, PostgreSQL, Redis, Meilisearch, MongoDB, S3-compatible storage and Mailpit are all a lerd service start away.

Beyond PHP

Omarchy attracts people working across several stacks at once. Lerd serves non-PHP projects through a Containerfile.lerd in the project root: Node, Python, Go and Rails apps get the same .test domain, the same certificate and the same dashboard row as a PHP site. A Rails app on blog.test and a Laravel app on shop.test sit side by side with one nginx in front of both.

Frequently asked questions

Does Omarchy include a PHP environment? No. It gives you the desktop, the terminal and the editor. The web stack is yours to install, which is what Lerd is for.

Is Lerd in the AUR? Not yet. Install with the one-line installer, which handles the Arch prerequisites, or with Homebrew on Linux if you already use it. lerd update self-replaces the binary on a script install.

Will it fight with Docker? No. Lerd uses rootless Podman with no daemon, so Docker can stay installed and running for other work.

Does it need sudo? Once, at install, to point the system resolver at the .test domains. Everything after that runs as your own user. The .localhost mode skips even that.

Does it survive a reboot? Yes, provided loginctl enable-linger $USER is set, which the installer handles. The DNS route is re-created by lerd-dns-link.service on every boot.

Does it theme with Omarchy? The bar widget follows the Quattro shell's own styling. The web dashboard has its own light and dark themes and follows your browser.

Next steps

• Requirements and installation
• Quick start, a project served in two commands
• Omarchy bar widget, the full panel reference
• Comparison against Laravel Herd, Sail, DDEV and Lando