Desktop App

Yerd ships a desktop GUI: a small tray-first window over everything the CLI does. Built with Tauri v2, Vue 3, TypeScript, and Tailwind, it's a thin client of the daemon, just like the yerd CLI. Every button maps to one IPC request to yerdd, so the GUI and CLI can't drift out of sync.

It's the recommended way to run Yerd: it installs and verifies the daemon and CLI for you, then walks you through the one-time setup. If you live in the terminal, the CLI is a first-class alternative.

Install the bundles

The app is the only artifact, with the daemon + CLI + helper embedded:

Platform	Artifact	Install
macOS (Apple Silicon)	Yerd_MacOS_AppleSilicon_v<ver>.dmg	Open the DMG, drag Yerd to Applications
Linux · Debian/Ubuntu (x86-64)	Yerd_Linux_x86_64_v<ver>.deb	sudo apt install ./Yerd_Linux_x86_64_v<ver>.deb
Linux · Debian/Ubuntu (arm64)	Yerd_Linux_Arm64_v<ver>.deb	sudo apt install ./Yerd_Linux_Arm64_v<ver>.deb
Linux · Arch (x86-64)	Yerd_Linux_x86_64_v<ver>.pkg.tar.zst	sudo pacman -U ./Yerd_Linux_x86_64_v<ver>.pkg.tar.zst

The macOS DMG targets Apple Silicon (aarch64) only; Intel (x86-64) Macs are not supported at this time. There's no Windows bundle yet: the daemon's named-pipe address isn't client-derivable.

The GUI sets up the backend for you

The GUI is a client of the daemon, and the daemon (yerdd), the yerd CLI, and yerd-helper are all bundled inside the app - nothing is downloaded at runtime. On first launch the app simply starts its bundled daemon, then lands you on the Overview dashboard. On macOS that makes setup essentially drag-and-drop: drag Yerd to Applications, launch it, done. On macOS the daemon registers as a background SMAppService login item (shown as "Yerd" in System Settings → Login Items); on Linux the package (.deb/.pkg.tar.zst) puts yerd on your PATH and grants the daemon its privileged-port capability.

Tray-first by design

The window is something you summon, not keep open.

• Closing the window hides it to the tray instead of quitting. The daemon and your sites keep running.
• The tray menu is a live dropdown, not a static list. It shows daemon status (running/stopped, with the bound HTTP/HTTPS ports) and Restart / Stop (or Start when stopped); an inline Default PHP switcher over your installed versions (a tick marks the current default, pick another to switch); Update Yerd / Update PHP when an update is waiting (otherwise Check for updates); shortcuts to open the Mail and Dumps viewer windows; New Laravel site, Link Site, Park Directory; page-navigation shortcuts; Open Yerd; and Quit (exits the GUI, not the daemon). The menu refreshes from the daemon even while the window is hidden to the tray.
• The tray icon also carries status badges: a small red dot when a Yerd or PHP update is available, and an orange dot when there's unread captured mail.
• You don't need to click Check for updates for the badge to stay current: the daemon checks for new Yerd releases on its own roughly every 4 hours, and the app also checks immediately on launch (or when you re-open an already-running Yerd) if the last check is more than 4 hours old.
• On macOS, left-click the tray icon to open the menu. On Linux (AppIndicator), use the menu's Open Yerd to reshow the window.
• Single-instance: launching again re-focuses the existing window.

The window is borderless with a custom title bar (macOS-style traffic lights for close / minimize / zoom) and looks identical on both platforms. A status pill in the bottom-left of the sidebar shows whether the daemon is connected, unreachable, or connecting.

If the daemon isn't running, every data-backed page shows the same Yerd isn't running screen - the page's header plus a Start Yerd hero that launches the bundled yerdd (through your per-user service) without leaving the app. The button keeps spinning until the daemon actually connects. The Overview, Settings, and About pages stay reachable even when the daemon is down. You can also start it from a terminal with yerdd serve &.

First run vs. later starts

On a brand-new install the app opens the onboarding journey, which installs and starts the daemon for you (and walks through PHP, parking, and elevation). Once you've been set up, later launches go straight to the dashboard - or the Start Yerd screen if the daemon happens to be stopped. On macOS, registering the background service may prompt you to enable Yerd in System Settings → Login Items - the app shows a button to take you there. It never runs as root to do this.

The window at a glance

The sidebar opens on Overview and groups the rest:

Group	Pages
(top)	Overview - a live dashboard of what's running
Environment	PHP · Sites
Developer	Tooling · Services · Mail · Dumps
Integrations	Share - publish a site over a public URL (guide)
System	Settings · Doctor · About

Overview

The landing dashboard. With the daemon running it shows a serving summary - the number of live .test sites (each a clickable chip that opens in your browser), stat tiles for PHP versions, sites, services, and captured mail (each links to its page), and a system-health strip (Local CA, .test resolver, privileged ports). When the daemon is down, the same surface becomes a Start Yerd hero.

Settings

App- and daemon-level settings (one of the pages that stays usable when the daemon is down, since it can start or install it):

• Daemon. Whether yerdd is running (with pid), a Start or Stop button, and a list of the daemon's in-process subsystems - the DNS resolver, the HTTP and HTTPS proxy listeners (with bound ports, including when macOS's pf redirect carries :80/:443), Mail capture (by port), and Dump capture (by port). The daemon row has a Restart button. Start/Stop/Restart go through your per-user service manager (systemd --user on Linux, a launchd LaunchAgent on macOS), with a detached-process fallback where none exists; the same actions are in the tray menu.
• Start at login. Three toggles - start the daemon at login, start the app at login, and start the app minimized (hidden to the tray). The daemon-at-login toggle is disabled where no per-user service manager is available.
• Appearance. A System / Light / Dark theme selector, applied live and remembered across launches.

PHP

Manages your installed PHP versions:

• A table of installed versions showing live FPM pool state, patch level, pool memory (RSS), and whether an update is available.
• Install opens a picker of installable versions (already-installed ones are hidden). Installs download a prebuilt static build, which can take a few minutes with no progress bar; the daemon reports only on completion.
• Refresh re-checks for updates. Update all updates every version with a pending update. Updates are notify-only.
• Each row's ⋯ menu offers Restart (only when the pool is running or failed), Update (only when available), Set default (marks it with a star), and Uninstall. Restart all restarts every running pool.
• A Default settings card edits the global ini defaults applied to every version: memory_limit, max_execution_time, max_input_time, max_file_uploads, upload_max_filesize, post_max_size, error_reporting, and display_errors. Leave a field blank to use PHP's built-in default. Saving restarts running pools to apply.

Sites

The home base for managing sites. Two cards:

Parked folders. Each parked directory shows a count of the .test sites it produces (one per child directory). Park folder opens a native directory picker; each row's menu offers Reveal folder or Un-park (with confirmation).

Sites. Every parked and linked site:

Column	What it does
Site	The name.test URL. Click to open in your browser. A badge marks it parked or linked.
Document root	The project directory. Click to reveal it in your file manager.
Served from	The web root actually served (e.g. public, or / for the project root), auto-detected per framework. Click to change it.
PHP	A per-site PHP picker (dropdown of installed versions), changed inline.
HTTPS	A toggle to flip HTTPS on or off for that one site.
Actions	⋯ menu: Open in browser, Reveal folder, Set web root…, Auto-detect web root, and (linked sites only) Unlink.

Link site opens a modal to link one directory under a name you choose (a single DNS label, validated as [a-z0-9-]+). Set web root… opens a modal to pin the served subdirectory (or pick it with a folder browser); Auto-detect web root clears the override and lets Yerd detect it again. Parked sites have no destructive action here; remove them by un-parking their folder, or they'd reappear.

Untrusted CA banner

If your local CA isn't trusted in the system store, the Sites view shows a banner (browsers will warn on HTTPS sites until fixed). It links to the Doctor page's Environment panel, where one click runs the fix. See HTTPS & Certificates.

Tooling

Installs self-contained developer tools - Composer, Node, and Bun - onto your PATH alongside PHP, each managed by Yerd (install / update / uninstall) so they don't collide with system installs. See Tooling.

Services

The database and cache engines Yerd supervises - Redis (Valkey), MySQL, MariaDB, and PostgreSQL. Install a version, then Start / Stop / Restart it. Each installed engine's ⋯ menu also offers Configuration (copy the Laravel .env for that engine - with a database picker that pre-fills DB_DATABASE for SQL engines), Edit port, View logs, Manage databases (create / drop / back up / restore, SQL engines only), Change version, and Uninstall. The daemon auto-starts every installed engine on boot. See Services & Databases.

Mail

The built-in SMTP mail capture server - point your app's mailer at 127.0.0.1 on the shown port and every outgoing email is captured for preview instead of being sent. Toggle capture, set the port, and open the separate Mails viewer with Show Mails. A Laravel configuration card emits the .env mail keys (MAIL_HOST, MAIL_PORT, …) to paste into your app, with editable From name/address. Captured mail is tracked read/unread: the sidebar Mail item shows an unread-count pill (click it to jump straight to the viewer), and opening a message marks it read. See Mail Capture.

Dumps

Laravel telemetry interception - dump()/dd() plus queries, jobs, views, requests, logs, cache, and outgoing HTTP - streamed to a separate viewer window with no code changes, captured by a per-version PHP extension. Enable interception, pick which signals to record, set the port, and open the viewer with Show Dumps. See Laravel ▸ Dumps.

Doctor

Mirrors yerd doctor:

• Health. Lists problems by severity (Healthy / Warning / Problem) with a copyable remedy command. Run safe fixes applies the safe one-click fixes; Re-check re-runs diagnostics. A clean machine shows an "all clear" panel.
• Environment. OS-level state: Local CA trusted, .test resolver installed, and Privileged ports (80/443). A Fix (elevate) button runs the privileged action where a row isn't configured; once a row is configured, an Unelevate button reverts it - behind an in-app confirm dialog and the OS prompt. Unelevating the .test resolver restores your previous resolver on macOS; reverting privileged ports is macOS-only (Linux setcap has no clean reverse, so no button is shown there).

"Fix" actions never run the GUI as root

The Fix buttons run the audited yerd elevate helper under an OS prompt; the GUI never runs elevated. On Linux this uses pkexec, on macOS an osascript … with administrator privileges prompt. You may be asked for your password. See Elevation & Privileges.

About

Shows the app, daemon, and negotiated IPC protocol versions, plus your local environment: the TLD (.test), the DNS responder address, and the local CA certificate path and fingerprint (both copyable, with reveal-in-finder). It also links to the project repository.

Keyboard shortcuts

The window is fully keyboard-driven. Shortcuts follow each platform's convention: where macOS uses Cmd (⌘), Linux uses Ctrl with the same letter. Two of them are all you need to remember - the command palette (⌘K / Ctrl+K) jumps to any page or runs any action by typing, and the shortcuts overlay (⌘/ / Ctrl+/) lists everything below in the app itself.

The command palette also lists your sites at the bottom (grouped by domain): Open a site in the browser, or Secure / Unsecure it (toggle HTTPS), without leaving the keyboard.

Action	macOS	Linux	What it does
Command palette	⌘K	Ctrl+K	Search-and-run overlay for every page and action
Shortcuts	⌘/	Ctrl+/	Show this list inside the app
Go to a page	⌘1 … ⌘9	Ctrl+1 … Ctrl+9	Jump straight to a sidebar page (see order below)
Settings	⌘,	Ctrl+,	Open the Settings page
Find	⌘F	Ctrl+F	Focus the page's filter box (Sites, Dumps)
New	⌘N	Ctrl+N	Start the page's primary action (Add site, Install PHP)
Refresh	⌘R	Ctrl+R	Re-fetch the current page's data
Restart daemon	⇧⌘R	Ctrl+Shift+R	Restart yerdd
Toggle theme	⇧⌘L	Ctrl+Shift+L	Switch light / dark (applies to every window)
Open Mail viewer	⇧⌘M	Ctrl+Shift+M	Open the standalone Mail capture window
Open Dumps viewer	⇧⌘D	Ctrl+Shift+D	Open the standalone Dumps telemetry window
Link Site	⇧⌘N	Ctrl+Shift+N	Open the Link-site dialog on the Sites page
Park Folder	⇧⌘P	Ctrl+Shift+P	Open the park-folder picker on the Sites page
Cycle Dumps tabs	⌃⇥ / ⌃⇧⇥	Ctrl+Tab / Ctrl+Shift+Tab	Move between categories in the Dumps viewer
Close window	⌘W	Ctrl+W	Hide the window to the tray
Close dialog	Esc	Esc	Dismiss the open modal

⌘1…⌘9 follow the sidebar order: 1 Overview, 2 PHP, 3 Sites, 4 Tooling, 5 Services, 6 Mail, 7 Dumps, 8 Settings, 9 Doctor.

Quitting the app

There's no Quit shortcut: closing the window (⌘W / Ctrl+W) hides it to the tray and leaves the daemon running, by design. Quit from the tray menu, or on macOS with the standard ⌘Q.

How it fits together

The daemon owns all state; the window is a view onto it; privileged work goes through the audited helper behind an OS prompt. Both the GUI and CLI are clients of the same daemon, so anything you do in one shows up immediately in the other.

Related

• Getting Started - install Yerd (the app sets up the daemon and CLI for you) or take the terminal-first path
• The Daemon - what yerdd is and how it runs
• Sites · PHP Versions · HTTPS & Certificates - the features the GUI surfaces
• Elevation & Privileges - how "Fix" actions stay root-free
• Desktop App Internals - the Tauri/Vue architecture for contributors
• Source on GitHub - apps/yerd-gui