---
url: 'https://yerd.app/guide/introduction.md'
---
# What is Yerd?

Yerd is a fast, rootless, open-source local PHP development environment. It serves your projects on `.test` domains over HTTP and HTTPS, runs a different PHP version per site, and manages everything from one small background daemon. No Docker, no `sudo` for daily work, no subscription.

If you've used [Laravel Herd](https://herd.laravel.com), you know the appeal: open `https://my-app.test` and it just works - the right PHP version, a trusted certificate, no fuss. Yerd does the same, on macOS and Linux, and it's fully open-source.

## Why Yerd?

Setting up local PHP the traditional way means stitching together a web server, a DNS tool, a certificate workflow, and some way to juggle PHP versions. Docker hides the wiring but trades it for image pulls and a VM you didn't want. Yerd gives you the same result as plain, native processes:

* **Zero-config sites.** Drop a project into a parked folder and it's instantly live at `<name>.test` - no config files, no virtual hosts. [Sites →](./sites)
* **HTTPS that just works.** Yerd issues a trusted certificate for every site on demand: a green padlock, no browser warnings, no `mkcert` dance. [HTTPS →](./https)
* **Any PHP version, per site.** Install as many versions as you need and point each project at the one it wants. [PHP versions →](./php-versions)
* **Rootless by design.** After a single one-time setup, nothing runs as administrator - the daemon, CLI, and app all run as you. [Elevation →](./elevation)
* **Tiny and native.** One small daemon (~8 MB), no containers, no VM, no Electron. PHP builds download only when you ask.
* **Batteries included.** Databases and caches (MySQL, MariaDB, PostgreSQL, Redis), mail capture, live Laravel dump streaming, and one-click public [sharing](./sharing) over Cloudflare Tunnel are built in - not bolt-ons.
* **Self-diagnosing.** Built-in health checks show what's wrong and repair the safe problems for you. [Diagnostics →](./diagnostics)

## One tool, two ways to drive it

Under the hood Yerd is a single background daemon that owns everything - your sites, PHP, HTTPS, and DNS. You drive it however you like:

* the **[desktop app](./desktop-app)** - a native tray app (shown above), or
* the **[`yerd` command line](../reference/cli/)** - first-class and fully scriptable.

Both are just clients of the same daemon, so a change in one shows up in the other immediately - they can never disagree about what's running.

## How it works

When you open `https://my-app.test`:

1. Yerd's built-in DNS answers `*.test` with your own machine (`127.0.0.1`).
2. Its reverse proxy matches the address to a site and hands the request to the right PHP version.
3. For secured sites it serves HTTPS using a certificate from Yerd's own local certificate authority - trusted once, valid everywhere.

That's the whole path, and it all lives inside the one daemon. Curious about the internals? See the [Architecture](../developer/architecture) overview.

## A quick taste

```sh
yerd install php 8.5          # grab a PHP version
yerd park ~/Sites             # serve every project in a folder
yerd secure my-app            # turn on trusted HTTPS
# open https://my-app.test - done
```

The [Getting Started](./getting-started) guide walks through it from a clean machine.

## Who Yerd is for

* **PHP and Laravel developers** who want Herd-style `.test` sites and trusted HTTPS on macOS or Linux.
* **Anyone juggling multiple PHP versions** who needs a specific one per project.
* **People who'd rather not run Docker** for local dev and prefer light, native processes.
* **Open-source-minded developers** who want a tool they can read, audit, and contribute to.

## Next steps

* [Getting Started](./getting-started) - install Yerd and serve your first site.
* [Features](./desktop-app) - a tour of everything Yerd can do, screen by screen.

---

---
url: 'https://yerd.app/guide/getting-started.md'
description: >-
  Install the Yerd desktop app and use its first-run onboarding journey to get
  from a clean machine to your first site live at https://my-app.test.
---

# Getting Started

This guide takes you from a clean machine to your first site live at
`https://my-app.test`, using the **Yerd desktop app** - the recommended,
GUI-first way to run Yerd.

Yerd runs entirely **as your user**. `sudo` shows up in exactly two
non-ongoing places: installing the system package (standard for any
`.deb`/`.pkg.tar.zst`/`.rpm`), and a single, optional, **one-time** privileged
setup step that the app walks you through. Day-to-day use never touches root.

::: info Supported platforms
Yerd ships a single desktop app for **macOS** (Apple Silicon) and **Linux**
(Debian/Ubuntu `.deb` for x86-64 and arm64, an Arch `.pkg.tar.zst` for x86-64,
and a Fedora `.rpm` for x86-64 and arm64). The daemon, the `yerd` CLI, and the
privileged
helper are all bundled inside it - there is nothing else to install. PHP itself is
**not** bundled - Yerd downloads prebuilt static PHP builds on demand once you
pick a version, so the install stays tiny and fast.
:::

::: warning Apple Intel not supported
Intel (x86-64) Macs are not supported at this time. macOS builds target Apple
Silicon (arm64) only.
:::

## Install

Grab the latest **stable release** from the
[releases page](https://github.com/forjedio/yerd/releases):

| Platform | Download | Install |
|---|---|---|
| macOS (Apple Silicon) | `Yerd_MacOS_AppleSilicon_v<ver>.dmg` | open, 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` |
| Linux · Fedora (x86-64) | `Yerd_Linux_x86_64_v<ver>.rpm` | `sudo dnf install ./Yerd_Linux_x86_64_v<ver>.rpm` |
| Linux · Fedora (arm64) | `Yerd_Linux_Arm64_v<ver>.rpm` | `sudo dnf install ./Yerd_Linux_Arm64_v<ver>.rpm` |

::: tip Arch Linux
Remove any leftover `/usr/bin/yerd` from the old v1 (Go) project first - pacman
won't install over a file it doesn't own - and `pacman -Syu` before installing so
the bundled GUI's WebKit/GTK libraries match your system.

If you are upgrading from Yerd v2.0.3 or earlier, in-app update cannot see this
release, so reinstall once by hand with the same
`sudo pacman -U ./Yerd_Linux_x86_64_v<ver>.pkg.tar.zst` command from the
[releases page](https://github.com/forjedio/yerd/releases); your settings and
sites are preserved, since it is a normal package upgrade, and in-app updates
work again from this version on.
:::

The macOS `.dmg` installer window - drag **Yerd** onto **Applications** to install.

On macOS that makes setup essentially **drag-and-drop**: drag Yerd to
Applications and launch it. On Linux the package puts `yerd` on your `PATH`
automatically. Everything else below happens inside the app.

::: tip Prefer the terminal, or building from source?
Everything in this guide has a `yerd` CLI equivalent - see the [CLI Reference](../reference/cli/).
The app comes with the CLI bundled: open **Settings → Terminal CLI** and click
**Install** on macOS (the Linux package puts it on `PATH` automatically). To
build and run from source instead, see [Building from Source](../developer/building).
:::

## First launch: the onboarding journey

The first time you open Yerd on a fresh machine, it greets you with a short,
guided **onboarding journey** instead of dropping you straight into the
dashboard. It walks you through the handful of one-time steps that turn a
clean install into a working `.test` environment: starting the daemon,
installing a PHP version, pointing Yerd at your projects, and granting the OS
privileges for HTTPS and ports 80/443.

Every step except the daemon install has a **Skip for now**, and you can move
**Back** at any point - nothing you skip is lost, it just lives on its normal
page in the app. Following it end to end gets you from install to serving
sites in a couple of minutes.

### Step 1 - Install the daemon

The journey opens by introducing **`yerdd`**, the small background service that
does all the real work - it supervises PHP-FPM, serves your `.test` sites over
HTTP/HTTPS, answers DNS, and runs databases. The app is just a client of it and
**never runs as root**.

Click **Install & start daemon**. The button keeps spinning until the daemon
actually connects, then turns into a green **Running** badge and **Continue**
unlocks. This is the one required step - everything after it is skippable.

Installing the daemon here also sets sensible login defaults: the **daemon and
the app both start at login**, with the **app started minimized** to the tray.
Change any of the three later under **Settings → Start at login**.

::: tip macOS background approval
On macOS the daemon registers as a background **SMAppService** login item (it
shows as "Yerd" in System Settings → Login Items). If macOS asks you to
approve it first, the step shows an **Open Login Items** button to take you
there; once approved it connects automatically.
:::

### Step 2 - Install a PHP version

Pick a PHP version to install - the **latest** is selected for you, and the
**first version you install automatically becomes your default**. It downloads
a prebuilt, self-contained build (this can take a minute or two with no
progress bar). Add or change versions any time later on the [PHP page](./php-versions).

Not ready? Click **Skip for now** and install one later.

### Step 3 - Park a projects folder

Point Yerd at a folder of projects and every subfolder is served automatically
at `<name>.test`. Click **Choose a folder…**, pick your `~/Sites` (or wherever
your projects live), and you're done. This is the fastest way to get many
sites at once; you can also link individual projects later. See [Sites](./sites)
for the difference between parking and linking.

Skippable - park a folder whenever you're ready.

### Step 4 - Trust & system access

For HTTPS on `.test` and serving on the standard ports 80/443, Yerd needs three
OS-level privileges:

* **Trust the local CA** so browsers accept your `.test` HTTPS certificates
  without warnings.
* **Install the `.test` resolver** so `*.test` names resolve to Yerd.
* **Bind privileged ports 80/443** (otherwise Yerd falls back to `8080`/`8443`).

Use **Fix all** to grant them in one go - you'll be asked for your password by
the OS. This step is optional; you can do it later from the [Doctor page](./diagnostics),
and Yerd works on high ports until you do. For exactly what runs and why it's
safe, see [Elevation & Privileges](./elevation).

::: tip Reverting later
Anything you grant here is reversible from Doctor (or `sudo yerd unelevate`).
See [Elevation & Privileges](./elevation) for details.
:::

### Step 5 - You're all set

That's it. Click **Get started** and Yerd marks setup complete and drops you on
the **Overview** dashboard.

The journey won't show again on this machine - next time the app opens
straight into the dashboard, or the **Start Yerd** screen if the daemon happens
to be stopped. If you ever want to see it again, run
[`yerd uninstall`](../reference/cli/uninstall) to reset to a clean state, then
reopen the app. See the [Features](./desktop-app) guide for the full tour of
every page.

## Serve, secure, and check on your first site

Whatever you skipped in the journey lives on its normal page in the app:

* **PHP** - install or switch versions, set a global default, or pin one site.
* **Sites** - park a folder, link a single project, and toggle HTTPS per site.
* **Doctor** - grant or revert the CA/resolver/ports privileges, and see a
  health check with one-click fixes.

Open `https://my-app.test` once it's parked or linked and secured - that's it.

## Uninstall

To remove Yerd completely, run the bare `uninstall` command (no subcommand)
from a terminal. It prompts for confirmation, then tears down the daemon, the
PATH entry, all config/data/downloads, and the binaries:

```sh
sudo yerd uninstall      # recommended - also reverts the one-time elevate changes
yerd uninstall           # without root - removes everything except the elevate changes
```

Run it with **`sudo`** so it can also reverse the `elevate` system changes (the
CA in your trust store, the `*.test` resolver, and the macOS port redirect).
Those need root to undo, and they **can't** be undone once the binaries are
gone - so without `sudo`, yerd warns you and prints the exact manual commands to
clean them up later. Add `--yes` to skip the prompt in scripts. A `.deb` install
is removed the usual way (`sudo apt purge yerd`); the macOS app is dragged to the
Trash. Full details in the [Uninstall reference](../reference/cli/uninstall).

## Where to next

* [Features](./desktop-app) - a tour of every page in the app.
* [Sites](./sites) - parking, linking, and per-site settings in depth.
* [PHP Versions](./php-versions) - pools, ini defaults, and updates.
* [HTTPS & Certificates](./https) and [DNS & .test Domains](./dns).
* [Elevation & Privileges](./elevation) - exactly what the one-time setup grants.
* [CLI Reference](../reference/cli/) and
  [Configuration Reference](../reference/configuration) for the full surface.

---

---
url: 'https://yerd.app/guide/guides.md'
description: >-
  Short video walkthroughs of installing Yerd, setting up services and tooling,
  and creating your first Laravel site.
---

# Guides

Prefer to watch instead of read? These short videos walk through the same ground as the written guides - installing Yerd, serving your first site, and setting up the extras.

## Installing Yerd

Download the app, install it, and get through the first-run onboarding journey. See the written version in [Getting Started](./getting-started).

## Services & additional tooling

Databases, caches, and the developer tools (Composer, Node, Bun) Yerd can install and supervise for you. See [Services & Databases](./services) and [Tooling](./tooling).

## Creating a new Laravel site

Park or link a project and serve it at its own `.test` domain. See [Sites](./sites) for the full walkthrough.

---

---
url: 'https://yerd.app/guide/switching-to-yerd.md'
description: >-
  A step-by-step guide to switching to Yerd from Laravel Herd, Valet, or Lerd -
  stop the other tool's services first, elevate Yerd, verify, and how to switch
  back cleanly.
---

# Switching to Yerd

Yerd, [Laravel Herd](https://herd.laravel.com), [Valet](https://laravel.com/docs/valet), and [Lerd](https://github.com/geodro/lerd) all do the same OS-level job for local development, which means they all reach for the **same three system resources**:

* **Ports 80 and 443** - only one process can listen on each at a time.
* **The `*.test` resolver** - one OS resolver route per TLD (`/etc/resolver/test` on macOS, or systemd-resolved/NetworkManager snippets on Linux).
* **A trusted local CA** - each tool installs its own into the system trust store.

Because those are single-owner, **two tools can't run at once** without fighting over ports and DNS. Switching is therefore mostly about handing those three things over cleanly: stop the old tool, let Yerd take the ports/resolver, and (if you ever go back) hand them back.

::: tip The one rule
**Stop the other tool's services before you `sudo yerd elevate`.** Everything else is detail.
:::

This guide is for switching *machines you already use* for PHP dev. On a clean machine there's nothing to migrate - just follow [Getting Started](./getting-started).

## Before you start

* **Your project code is safe.** None of these tools own your source - they just serve folders. Switching changes *what's serving* `*.test`, not your files. You don't need to move or copy any project.
* **PHP versions don't carry over.** Yerd installs its own [prebuilt PHP builds](./php-versions); it doesn't reuse Herd/Valet/Homebrew PHP. [Getting Started](./getting-started) walks through installing the version(s) you need.
* **You can keep the old tool installed.** You don't have to uninstall Herd/Valet/Lerd to try Yerd - you just can't have both *serving* at the same time. Keeping it installed makes switching back trivial.

::: warning Subdomains are apex-only by default
If you relied on Valet/Herd resolving *any* subdomain of a site (`api.my-app.test`, `admin.my-app.test`, ...) implicitly, note that in Yerd a site answers only its exact apex `my-app.test` by default. Register the ones you need explicitly, or re-add the old catch-all behaviour with `yerd domain add my-app '*.my-app.test'`. See the [domains reference](../reference/cli/domains).
:::

## Step 1 - Stop the other tool

Stop whatever currently serves `*.test` so it releases ports 80/443 and stops answering `.test` DNS. Pick your tool:

### From Laravel Herd

Herd runs `nginx` + `dnsmasq` as background services.

* **Quit Herd** (or, in the app, pause/stop its services), **or** from the terminal:
  ```sh
  herd stop          # stop Herd's nginx/php/dnsmasq services
  ```
* Herd may relaunch its services on login. If you're switching for good, quit Herd fully (and consider removing it from Login Items) so it doesn't grab port 80 again on your next reboot.

### From Laravel Valet

Valet runs `nginx` + `dnsmasq` via Homebrew.

```sh
valet stop         # stop nginx + dnsmasq (releases 80/443 and *.test DNS)
```

To go further and have Valet remove its own DNS/loopback hooks too:

```sh
valet uninstall    # removes Valet's nginx/dnsmasq config (keeps your sites list)
```

`valet stop` is enough to switch; `valet uninstall` is for a permanent move.

### From Lerd

Lerd runs your stack in **rootless Podman containers**.

```sh
lerd stop          # stop Lerd's containers (frees 80/443)
```

If a stray container still holds a port, stop it directly with `podman stop <name>` (or `podman ps` to find it).

### Any other tool

The principle is the same: **stop whatever is listening on 80/443 and answering `*.test`.** To find a squatter on the ports:

```sh
# macOS / Linux - who holds 80 and 443?
sudo lsof -nP -iTCP:80 -sTCP:LISTEN
sudo lsof -nP -iTCP:443 -sTCP:LISTEN
```

## Step 2 - Install Yerd

With the other tool stopped, follow **[Getting Started](./getting-started)** to install Yerd and go through its first-run onboarding journey - it installs and starts the daemon, installs a PHP version, and parks a projects folder, all from the app.

You can do all of this **before** elevating: without elevation Yerd serves on the [rootless fallback ports](./elevation#the-rootless-fallback) `8080`/`8443`, so you can sanity-check it (`http://my-app.test:8080`) while the old tool is stopped.

## Step 3 - Elevate Yerd

Hand the three system hooks to Yerd. In the desktop app this is the **Doctor → Fix all** button; from the terminal:

```sh
sudo yerd elevate          # trust the CA · route *.test · allow 80/443
```

This trusts Yerd's local CA, points the `*.test` resolver at Yerd's DNS, and lets the daemon serve on 80/443 (a `pf` redirect on macOS, `setcap` on Linux). See [Elevation & Privileges](./elevation) for exactly what each step does.

::: tip macOS backs up your old resolver
On macOS, if a `/etc/resolver/test` already exists (a Valet/Herd leftover), `yerd elevate resolver` **saves a backup** before replacing it - so [switching back](#switching-back) can restore your previous DNS exactly. Linux has no backup mechanism; the drop-in is simply added/removed.
:::

## Step 4 - Verify

```sh
yerd doctor        # checks CA trust, the *.test resolver, ports, PHP, and sites
```

`doctor` is the source of truth for a clean switch. Watch for:

* **`ForeignWebListener`** - something *other than Yerd* is still holding 80 or 443. That's the old tool not fully stopped (go back to [Step 1](#step-1-stop-the-other-tool)). Yerd detects this by checking for its own `Server: yerd` marker on the port.
* **Ports fell back to 8080/8443** - elevation didn't take the privileged ports (often the same cause). Re-stop the other tool and re-run `sudo yerd elevate ports`.
* **Resolver / CA not configured** - re-run the matching `sudo yerd elevate <target>`.

Then open `https://my-app.test` - padlock and all.

::: warning Flush DNS / restart the browser
After the resolver changes, your OS or browser may still cache the old answer (or an HSTS/redirect from the previous tool). If a `.test` site won't resolve or shows a cert warning:

```sh
# macOS - flush the DNS cache
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
```

On Linux, Yerd reloads the detected supported resolver manager for you. Restart the browser if a site is stuck on the old CA or an HTTPS redirect.
:::

## Running side by side (without switching)

If you only want to *try* Yerd without giving up your current tool, **don't elevate**. Leave the other tool owning 80/443 and `*.test`, and reach Yerd's sites on its rootless ports instead:

* `http://my-app.test:8080` / `https://my-app.test:8443`

This avoids any conflict - but it's a trial mode, not the "just type the URL" experience. To make Yerd the default, stop the other tool and elevate.

## Switching back

Switching back is the reverse: hand the three hooks back to the other tool.

1. **Un-elevate Yerd** so it releases the resolver, CA trust, and ports:
   ```sh
   sudo yerd unelevate        # revert all three
   ```
   * On **macOS**, `unelevate resolver` **restores the resolver backup** taken in Step 3 (returning DNS to its pre-Yerd state), and `unelevate ports` removes the `pf` redirect.
   * On **Linux**, it removes all Yerd-owned systemd-resolved and NetworkManager resolver snippets. `setcap` has no clean reverse, so `unelevate ports` just prints the manual command (`sudo setcap -r <path-to-yerdd>`) - harmless to leave, but run it if you want it gone.

2. **Stop Yerd's daemon** so it isn't holding ports when the other tool starts:
   ```sh
   yerd stop          # or quit the desktop app (which stops the daemon)
   ```

3. **Start the other tool's services again** and let it re-claim the ports, DNS, and its own CA:
   ```sh
   valet start        # Valet  (or `valet install` if you uninstalled it)
   # herd start / launch Herd
   # lerd start
   ```

4. **Flush DNS** (see the warning above) and restart your browser.

::: tip Both CAs trusted is fine
Switching back doesn't *require* removing Yerd's CA - having more than one trusted local CA in your system store is harmless (the browser trusts certs from any of them). `sudo yerd unelevate trust` removes Yerd's if you want a tidy store; the helper only ever removes the cert whose subject is `Yerd Local CA`, never anyone else's root.
:::

## Removing Yerd entirely

If you're not coming back, do a full uninstall - which runs the same `unelevate` (all three targets) **before** deleting the binaries, so the system changes are reversed while `yerd-helper` still exists to reverse them:

```sh
sudo yerd uninstall        # un-elevates, then removes daemon, config, data, binaries
```

Run it **with `sudo`** - the trust/resolver/port changes can't be undone once the helper is gone. See the [Uninstall reference](../reference/cli/uninstall).

## See also

* [Getting Started](./getting-started) - install and first site
* [Elevation & Privileges](./elevation) - exactly what `elevate`/`unelevate` change
* [DNS & .test Domains](./dns) - how `*.test` resolution works
* [HTTPS & Certificates](./https) - the local CA and per-site certs
* [Diagnostics](./diagnostics) - `yerd doctor` and what it checks

---

---
url: 'https://yerd.app/guide/upgrading-from-v1.md'
---
# Upgrade Guide

Coming from the original Go-based Yerd (`LumoSolutions/yerd`, "v1")? This page covers what changed and how to move your local sites to v2.

::: warning This is a replacement, not an in-place upgrade.
Yerd v2 (`forjedio/yerd`) is a ground-up Rust rewrite. Different binaries, a different on-disk layout, an incompatible config format, and a redesigned command set. There is no automatic migration. You uninstall v1 and set up v2 fresh.
:::

## What changed

| Area | v1 (Go) | v2 (Rust) |
|---|---|---|
| Privileges | leaned on `sudo` for most operations | rootless; elevates once, then runs as your user |
| PHP | built from source | prebuilt, signed static builds downloaded on demand |
| Platforms | - | macOS + Linux today (Windows on the [roadmap](./services)) |
| Config & layout | v1's format | new, incompatible TOML config and layout |
| Commands | v1's names | redesigned; don't assume names carry over |

So v2 installs small and fast (no compiler needed for PHP), doesn't ask for your password every time you touch a site, and behaves the same across operating systems.

::: info Rootless by design
`sudo` appears in only two places: installing the system package (normal for any `.deb`/`.pkg.tar.zst`), and the one-time `sudo yerd elevate`. After that, day-to-day use never touches root. See [Elevation & Privileges](./elevation).
:::

## What does not carry over

* **v1 config is not read.** v2 uses its own TOML config; see the [Configuration Reference](../reference/configuration).
* **PHP versions are not reused.** Reinstall the versions you need (fast, no compilation).
* **Sites are not migrated.** Re-park and re-link them with the v2 commands below.
* **Command names may differ.** Use the [CLI Reference](../reference/cli/) or `yerd --help`.
* **The local CA is regenerated.** You trust the new CA once during setup.

## Migration, step by step

### 1. Stop and remove the v1 install

Shut down anything v1 is running so it can't fight v2 over ports 80/443, the DNS resolver, or your `.test` domains. Stop its daemon/service, then uninstall the Go binary and its files.

If v1 changed your system DNS resolver or installed a CA into your trust store, undo those too (v1's own uninstall is the right tool). A stale resolver or trusted CA is the most common cause of "it half-works" symptoms after switching.

::: tip
After removing v1, reboot or flush DNS so the OS forgets v1's resolver before v2 installs its own.
:::

### 2. Install Yerd v2

Follow **[Getting Started](./getting-started)** to install the app and go through its first-run onboarding journey - it installs and starts the daemon for you. You can install a PHP version and park a projects folder there too, or hold off and do it explicitly in the migration-specific steps below.

### 3. Run the one-time privileged setup

The only command that uses root in normal use. It trusts the local CA, routes `*.test` to Yerd's DNS responder, and lets the daemon bind ports 80/443:

```sh
sudo yerd elevate
```

You can grant the pieces individually:

```sh
sudo yerd elevate trust       # trust the local CA in the system store
sudo yerd elevate resolver    # route *.test queries to Yerd's DNS responder
sudo yerd elevate ports       # allow the daemon to bind ports 80/443
```

Reverse any of these with `sudo yerd unelevate` (optionally `trust`, `resolver`, or `ports`). See [Elevation & Privileges](./elevation).

::: tip Ports without elevation
Skip `sudo yerd elevate ports` and the daemon falls back to `8080`/`8443`. `yerd doctor` reports what's in effect.
:::

### 4. Reinstall the PHP versions you need

These download prebuilt static builds, so it's quick:

```sh
yerd install php 8.5
yerd install php 8.3
```

Set a global default (this drives the terminal `php` shim and the per-site fallback):

```sh
yerd use 8.5
```

Check what's installed and what updates are available:

```sh
yerd list php                 # installed versions + the global default
yerd list php --available     # versions installable from the distribution
yerd list php --check         # refresh "update available" status (polls now)
```

See [PHP Versions](./php-versions) for installs, updates, and per-site pinning.

### 5. Re-park and re-link your sites

To turn a directory whose sub-folders should each become a `.test` site, **park** it:

```sh
yerd park ~/Sites
#   ~/Sites/blog  ->  http://blog.test
```

For a single project served under a name you choose, **link** it:

```sh
yerd link my-app ~/code/my-app
#   ->  http://my-app.test
```

Verify:

```sh
yerd sites                    # every parked or linked site
yerd list parked              # the registered parked directory roots
```

Later, `yerd unlink <name>` removes a linked site and `yerd unpark <path>` un-parks a directory. See [Sites](./sites).

### 6. Turn HTTPS back on per site

HTTPS isn't on by default. Promote the sites that need it:

```sh
yerd secure my-app
#   ->  https://my-app.test  (trusted, via the local CA)
```

Use `yerd unsecure <name>` to turn it off. Since the CA was trusted in step 3, secured sites get a green padlock with no browser warnings. See [HTTPS & Certificates](./https).

### 7. Pin per-site PHP versions (optional)

The two-argument form of `yerd use` targets a single site:

```sh
yerd use my-app 8.3
```

### 8. Confirm everything is healthy

```sh
yerd status                   # daemon, proxy, DNS, ports, CA, PHP health
yerd doctor                   # diagnose common problems
yerd doctor fix               # attempt safe, unprivileged repairs
```

`yerd doctor` is most useful right after migrating: it flags a left-over v1 resolver, a port conflict, or an untrusted CA and tells you what to do. Add `--json` for machine-readable output. See [Diagnostics](./diagnostics).

## Command map

Commands you'll use most while migrating. For the rest, see `yerd --help` and the [CLI Reference](../reference/cli/).

| Task | v2 command |
|---|---|
| Park a directory of projects | `yerd park <dir>` |
| Link one project as a named site | `yerd link <name> <dir>` |
| Remove a linked site | `yerd unlink <name>` |
| Un-park a directory | `yerd unpark <dir>` |
| List sites | `yerd sites` |
| List parked roots | `yerd list parked` |
| Install a PHP version | `yerd install php <version>` |
| Set the global PHP default | `yerd use <version>` |
| Pin a site's PHP version | `yerd use <site> <version>` |
| List / update PHP | `yerd list php` · `yerd update php [<version>]` |
| HTTPS on / off | `yerd secure <site>` · `yerd unsecure <site>` |
| Manage a site's domains | `yerd domain list\|add\|remove\|primary\|reset <site>` |
| One-time privileged setup | `sudo yerd elevate [trust\|resolver\|ports]` |
| Reverse setup | `sudo yerd unelevate [...]` |
| Health & repair | `yerd status` · `yerd doctor` · `yerd doctor fix` |

v2 lets a site answer multiple domains, subdomains, and wildcards through `yerd domain` (see the [domains reference](../reference/cli/domains)). Unlike some setups, subdomains are explicit: a site answers only its exact apex until you add more.

::: details Lineage
Yerd v2 is a ground-up rewrite of our own v1 package ([`LumoSolutions/yerd`](https://github.com/LumoSolutions/yerd)). v1 is reference-only: no command-surface or config-format compatibility. The full project lives at [github.com/forjedio/yerd](https://github.com/forjedio/yerd).
:::

## Where to go next

* New to the concepts? See the [Introduction](./introduction) and [Features](./desktop-app).
* Setting up from scratch: [Getting Started](./getting-started).
* The full command list: [CLI Reference](../reference/cli/).
* The new config format and layout: [Configuration Reference](../reference/configuration).

---

---
url: 'https://yerd.app/guide/desktop-app.md'
description: >-
  A tour of the Yerd desktop app, screen by screen - the recommended way to
  install and run Yerd, a fast, rootless, open-source local PHP environment for
  macOS and Linux.
---

# Features

Yerd is a fast, rootless, open-source local PHP environment for macOS and Linux. It serves projects on `.test` domains over HTTP and HTTPS, runs a different PHP version per site, and manages it all from one small daemon. No Docker, no `sudo` for daily work, no subscription.

The **desktop app** is the recommended way to run all of it: 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](./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. This page is a tour of everything it can do, screen by screen; each section links to the full guide for that feature.

If you live in the terminal, the [CLI](../reference/cli/) is a first-class alternative. Not installed yet? See [Getting Started](./getting-started).

## 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](./sharing)) |
| 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. While the daemon is running, this page polls it every 5 seconds, so a change made from the CLI or another window shows up without a manual refresh.

### 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.
* **Application Ports** (while the daemon is running). Editable HTTP/HTTPS (the rootless fallback ports used when 80/443 need elevation), DNS, mail-capture, and dumps ports. If a port is in use elsewhere the page flags it here (site serving or `.test` resolution shows as unbound) so you can pick a free one. Change a value and **Save & restart** validates it, saves, restarts the daemon, and rechecks. HTTP/HTTPS are locked while ports are elevated - un-elevate them on the Doctor page first.
* **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.
* **Terminal CLI** (macOS and Linux). Installs `yerd` - and your installed tools (`php`, `composer`, ...) - onto your shell `PATH`. On a packaged Linux install `yerd` itself is already on `PATH`, so this is mainly how Linux users get the PHP/tool shims on `PATH` too.
* **Appearance.** A System / Light / Dark theme selector; a **Tray icon** selector (Automatic, Light Y, Dark Y, Full icon) for the menu bar / system tray icon; and a **Title bar** selector (Automatic, macOS, Linux, Linux (Reversed), Windows) that forces a window-control style regardless of host platform. All three apply live and are remembered across launches.

### PHP

Manages your installed [PHP versions](./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; progress streams live next to the Install button as it happens.
* 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.
* A Per-version configuration card lists your versions down the side, newest first. Picking one scopes everything to that version: a settings form overriding the defaults above (empty fields inherit), its custom extensions, and free-form ini directives. See [Per-version configuration](./php-versions#per-version-configuration).
* The Extensions section of that card registers extra `.so` extensions for the selected version (loaded into both FPM and the CLI): Add… browses for the file, optionally names it and toggles Zend extension. Each is load-probed before saving, and any whose file has gone missing is flagged. See [Custom extensions](./php-versions#custom-extensions).

### Sites

The home base for [managing sites](./sites). Polls the daemon every 5 seconds while running, so sites added or changed elsewhere show up without a manual refresh. 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 is a card: the `name.test` URL (click to open in your browser), the document root, and badges for kind (`parked`/`linked`), PHP version, HTTPS/HTTP, and the [served web root](./sites#web-root-the-served-directory) when it isn't the project root. A `+N` badge appears when the site answers extra domains beyond its apex, and an amber warning shows when another site claims this site's apex.

Each card's `⋯` menu offers **Edit…**, **Manage domains…** (set the primary domain, add or remove aliases and wildcards), Open in browser, Reveal folder, **Share publicly…** (jumps to the [Share page](#share)), and (linked sites only) Unlink. **Edit…** opens one dialog covering everything about the site: PHP version, web root (blank means auto-detect), the HTTPS toggle, and its [group](./sites#site-groups). Parked sites have no destructive action here; remove them by un-parking their folder, or they'd reappear.

Sites can also be organized into named, reorderable groups shown as collapsible sections on this page; see [Sites](./sites) for the full walkthrough.

::: tip 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](./https).
:::

### 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](./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](./services).

### 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](./mail).

### 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](./laravel-dumps).

### Share

Publishes a local site to the public internet over Cloudflare Tunnel. A **Cloudflare Tunnel** card shows the detected `cloudflared` version; a **Shared sites** card picks a site and opens a Quick Tunnel with one click, alongside a live table of active tunnels. A separate **Named tunnels** card walks through connecting a Cloudflare account and exposing sites on your own domain. See [Sharing Sites](./sharing).

### Doctor

Mirrors [`yerd doctor`](./diagnostics):

* **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).

::: info "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](./elevation).
:::

### 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.

* **Updates.** A release-channel selector (Stable / Edge pre-releases), a **Check now** button, and the last-checked status (current version, latest stable/edge, and how long ago it checked). When an update is available, an **Apply update** button downloads, verifies, and installs it, restarting the app.
* **Troubleshooting.** **Logs** opens a dialog tailing the GUI's own session log (`yerd-gui.log`) alongside the daemon log, tab-switchable, with a copy button. **Diagnostics** gathers a shareable text snapshot of app/daemon state with its own copy button - useful when reporting a problem.

## 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.

::: info 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`.
:::

## Related

* [Getting Started](./getting-started) - install Yerd and walk through the first-run onboarding journey
* [The Daemon](./daemon) - what `yerdd` is and how it runs
* [Sites](./sites) · [PHP Versions](./php-versions) · [HTTPS & Certificates](./https) - the features the GUI surfaces
* [Elevation & Privileges](./elevation) - how "Fix" actions stay root-free
* [CLI Reference](../reference/cli/) - the `yerd` command line, a first-class alternative
* [Desktop App Internals](../developer/gui) - the Tauri/Vue architecture for contributors
* [Source on GitHub](https://github.com/forjedio/yerd) - `apps/yerd-gui`

---

---
url: 'https://yerd.app/guide/sites.md'
---
# Sites

A **site** is a target Yerd serves on the `.test` TLD. Each one has a name, a document root, a **served web root** (auto-detected per framework), a PHP version, and an HTTPS flag. The daemon keeps a registry and resolves every request's `Host:` header to exactly one site.

You register sites two ways:

* **Parking** points Yerd at a *parent* directory, and every child folder becomes a site (`<folder>.test`). Good for a `~/Sites` workspace you add to often.
* **Linking** registers *one* directory under a name you choose. Good for a project outside your parked workspace, or when the site name shouldn't match the folder name.

Both route identically; only the registration differs.

## In the desktop app

The **Sites** page (under **Environment** in the sidebar) is the home base for managing your sites. It lists every `.test` site as a scannable card you can act on, with the registration controls in the header. Most day-to-day site work happens here without touching the terminal.

* Each card is a site you can click to open in your browser (at its primary domain), with badges for `parked`/`linked`, PHP version, HTTPS/HTTP, a `+N` badge when the site has extra domains, and an amber notice if another site has claimed its apex.
* A card's **Edit…** dialog (from its `⋯` menu) covers PHP version, [web root](#web-root-the-served-directory), HTTPS, and [group](#site-groups) in one place - no commands. The same `⋯` menu has **Manage domains…** for setting the primary domain and adding/removing aliases and wildcards.
* **Park folder** and **Link site** in the header register new sites: Park folder opens a directory picker, Link site opens a modal to name a single directory.
* A separate **Parked folders** section lists each parked root with a count of the sites it produces, plus Reveal folder and Un-park.

For the full tour of the app, see [Features](./desktop-app#sites).

### Site groups

Sites can be organised into named groups - a GUI-only, cosmetic layer for scanning a large site list (client work, personal projects, whatever grouping makes sense to you). Groups don't affect routing, PHP, or HTTPS; the CLI has no concept of them.

* **Create a group** from the header's **⋯** menu → **New group…**. The page still shows the classic flat grid until at least one group exists; once it does, sites render as collapsible group sections instead.
* **Assign a site to a group** from its **Edit…** dialog: a **Group** field lists the groups you've created plus **No group**. A site only shows up in a group once you've set this.
* **Reorder groups** with the up/down arrows next to a group's name (shown on hover).
* **Rename or delete a group** from the pencil icon next to it, which opens one **Edit group** dialog: change the name and **Save**, or click **Delete group** for a second confirmation step naming the group. Deleting a group doesn't remove its sites - they fall back to Unallocated.
* Each group is a **collapsible section** with a site count badge; collapsed/expanded state is remembered per group.
* Sites with no group assigned - or whose assigned group was deleted - appear in a synthetic **Unallocated** section at the end, with no management controls of its own.

Group names are unique case-insensitively (like site names) and can't be `Unallocated`, which is reserved for the synthetic bucket.

## Create a new Laravel site

Beyond registering folders you already have, the app can **scaffold a brand-new Laravel project** for you. Open the **Create** menu in the Sites header and choose **New Laravel site** to launch a short, four-step wizard - **Basics → Stack → Testing → Review** - that runs `laravel new` under the PHP version you pick and registers the result as a `.test` site automatically.

::: tip Prerequisites
Creating a Laravel site needs a PHP version, **Composer**, and the **Laravel installer**. If any are missing, the wizard offers to install them first; it can also use ones you already have [installed externally](./tooling#external-tools) (e.g. a global Composer). Starter kits that need Node or Bun pull the runtime in during the build.
:::

### Basics

* **Project name** - the site is served at `<name>.test`.
* **Location** - pick the parent folder. If it's a [parked](#parking-a-directory) root the new site is served automatically; any other folder is [linked](#linking-a-directory) under the project name.
* **PHP version** - the version the site (and the installer) runs on.
* **HTTPS** - serve it over TLS from day one (you can toggle this later too).

### Stack

Choose a **starter kit**: **None** (a plain skeleton, no auth scaffolding), the official **React**, **Vue**, or **Svelte** kits (Inertia + TypeScript), **Livewire** (Blade + PHP), or **Community…** to scaffold from any `--using <package>`.

### Testing

* **Testing framework** - **Pest** or **PHPUnit**.
* **Database** - SQLite, MySQL, MariaDB, PostgreSQL, or SQL Server.
* **Initialise git** - run `git init` in the new project.
* **Laravel Boost** - install [Boost](https://laravel.com/docs) for AI-assisted coding.

### Review

A final summary of your choices - site name, path, PHP version, and HTTPS. Click **Create** and the dialog switches to a live progress view (**Preflight → Scaffolding → Registering → Done**) streaming the installer's output, so you can watch the scaffold and dependency install happen.

When it finishes, the project is on disk, registered (parked or linked), served at `<name>.test`, and ready to open in your browser or reveal in your file manager - no extra steps.

## Create a new WordPress site

The same **Create** menu can scaffold a brand-new WordPress install for you. Choose **New WordPress site** to launch a four-step wizard - **Basics → WordPress → Database → Review** - that provisions a database, runs WP-CLI's `core download`/`config create`/`core install`, sets pretty permalinks, and registers the result as a `.test` site automatically.

::: tip Prerequisites
Creating a WordPress site needs a PHP version and **WP-CLI**, and the wizard offers to install whatever's missing. WP-CLI must be Yerd's own build - Yerd runs it directly rather than through a `wp` on your `PATH`, so an [externally installed](./tooling#external-tools) `wp` doesn't count and your own copy is left alone. Yerd's **Composer** builds WP-CLI, so it's offered as a prerequisite too when WP-CLI still needs installing - see [Tooling](./tooling).
:::

### Basics

* **Project name** - the site is served at `<name>.test`.
* **Location** - pick the parent folder. If it's a [parked](#parking-a-directory) root the new site is served automatically; any other folder is [linked](#linking-a-directory) under the project name.
* **PHP version** - the version the site (and WP-CLI) runs on.
* **HTTPS** - serve it over TLS from day one (you can toggle this later too).

### WordPress

* **Core version** - a specific WordPress release, or **Latest**.
* **Locale** - the install language (e.g. `en_US`, `en_GB`).
* **Site title** - WordPress's own site name, set at install time.
* **Admin username / email / password** - the first administrator account. **Generate** fills in a random password; the daemon re-validates all three server-side regardless of what the wizard sent.

### Database

* **Database engine** - **MySQL** or **MariaDB** (the only two WordPress core itself supports).
* **Database name** and **table prefix** - defaults are derived from the project name; both can be edited.

Yerd provisions the database as part of creating the site, installing/starting the chosen engine first if it isn't already running - see [Services & Databases](./services).

### Review

A final summary of your choices. Click **Create** and the dialog switches to a live progress view streaming each phase - **Preflight → Provisioning database → Downloading WordPress → Configuring → Installing → Registering → Done**.

When it finishes, the site is on disk, registered, served at `<name>.test`, and ready to use - **Open folder**, **Open in browser**, or **WP Admin** to sign in as the administrator you just created (see below).

## WordPress one-click admin login

A WordPress site created through the wizard has **one-click admin login** turned on by default: opening **WP Admin** signs you in as the site's administrator instead of showing WordPress's own login screen. Existing or parked WordPress sites can opt in the same way.

* A WordPress site's card shows a **WP Admin** action in its `⋯` menu, plus a **WPA** badge when one-click login is on - both open the site's `/wp-admin/` pre-authenticated.
* Turn it on or off, and choose **who** to sign in as, from the site's **Edit…** dialog: the **WordPress Auto Admin Login** toggle and a **Sign in as** picker (defaults to the earliest-created administrator).

::: info How it works
Opening **WP Admin** mints a short-lived, single-use login token and appends it to the `/wp-admin/` URL. The proxy recognises and consumes the token on the first request, signing you in before redirecting - it's never valid a second time, and it does nothing outside that one request. If the resolver is off ([Localhost Access](./localhost-access)) or minting fails for any reason, **WP Admin** falls back to WordPress's ordinary login screen instead.
:::

## From the command line

Everything the Sites page does maps to a `yerd` command. These are the same operations against the same daemon, so anything you do here shows up in the app immediately.

### Parking a directory

`yerd park <dir>` registers a directory as a **parked root**. Each immediate child directory becomes a site named after the folder:

```sh
yerd park ~/Sites
#   ~/Sites/blog      ->  http://blog.test
#   ~/Sites/shop      ->  http://shop.test
#   ~/Sites/my-app    ->  http://my-app.test
```

Add a folder and its site is live; delete it and the site disappears. The child folder is the document root.

::: tip
You can park multiple roots. They all contribute children to one flat namespace of `.test` names.
:::

To stop serving a parked root, un-park it. This removes only the parked root, not any linked sites:

```sh
yerd unpark ~/Sites
```

Un-parking matches the stored path exactly. List the parked roots first if you're unsure what was registered:

```sh
yerd list parked
```

::: info
`yerd list parked` shows every parked root, including empty ones. An empty root produces no sites, so it won't appear in `yerd sites`, but it's still parked.
:::

### Linking a directory

`yerd link <name> <dir>` registers a single directory as a named site. The name becomes `<name>.test`; the directory is its document root:

```sh
yerd link my-app ~/code/my-app
#   ->  http://my-app.test
```

Name and directory are both optional shorthand for the current directory:

```sh
cd ~/code/my-app

yerd link              # links the cwd, named "my-app" after its folder
yerd link my-app       # same, with an explicit name
yerd link ../other-app # links a relative path, named "other-app" after its folder
```

A single positional argument is treated as a directory (and the name derived from its
folder) when it contains a path separator or is `.`/`..`; otherwise it's treated as a
bare name and the current directory is linked. Web-root detection (`public/` for
Laravel, etc. - see [Web root](#web-root-the-served-directory)) runs automatically the
first time a site is linked, so a Laravel app's `SERVED` directory is usually already
correct with no extra `yerd root` step.

To remove it, unlink by name:

```sh
yerd unlink my-app
```

### Site name rules

A site name is a single DNS label, validated and lowercased before it reaches the daemon (a bad name fails as a usage error, no connection made):

* ASCII letters, digits, and hyphen only (`[a-z0-9-]`).
* No dots; a name is one label, not a domain.
* No leading or trailing hyphen.
* 1-63 characters.
* Case-insensitive: `My-App` is stored and served as `my-app`.

Valid: `my-app`, `api2`, `wp-site`. Invalid: `my.app`, `my_app`, `-app`, `app-`.

::: warning
Names are unique. Since they're lowercased first, `Foo` and `foo` collide, so the second registration is a duplicate.
:::

### Listing your sites

`yerd sites` lists every site (parked and linked) with its kind, PHP version, secure flag, served subdirectory, and document root:

```sh
yerd sites
```

```
NAME     KIND     PHP   SECURE   SERVED   DOCROOT
blog     parked   8.5   false    public   /Users/you/Sites/blog
my-app   linked   8.3   true     /        /Users/you/code/my-app
shop     parked   8.5   false    public   /Users/you/Sites/shop
```

The `SERVED` column is the web root relative to the document root; `/` means the project root itself is served.

Sites print in name order; an empty registry prints `no sites`. Add `--json` for machine-readable output:

```sh
yerd sites --json
```

### Command reference

| Command | What it does |
|---|---|
| `yerd park <dir>` | Park a directory; each child folder is served at `<name>.test`. |
| `yerd unpark <dir>` | Un-park a directory. Linked sites are untouched. |
| `yerd link [name] [dir]` | Serve a directory as a named site; both args are optional shorthand for the current directory. |
| `yerd unlink <name>` | Remove a site by name. |
| `yerd sites` | List every site (name, kind, PHP, secure, served path, doc-root). |
| `yerd list parked` | List parked roots, including empty ones. |
| `yerd secure <name>` / `yerd unsecure <name>` | Turn HTTPS on / off for a site. |
| `yerd root <name> <path>` | Set the served directory (web root) for a site. |
| `yerd root <name> --auto` | Reset a site to automatic web-root detection. |
| `yerd domain <list\|add\|remove\|primary\|reset>` | Manage a site's domains (primary, aliases, subdomains, wildcards). See [Domains](../reference/cli/domains). |

For per-site PHP, see [PHP Versions](./php-versions). For the full command surface, see the [CLI Reference](../reference/cli/sites).

## How routing works

Yerd normalises the `Host:` header and resolves it to a site using the rules below.

### The `.test` TLD

By default Yerd serves on `.test`, a reserved TLD that's safe for local development. A host only resolves if it ends in the configured TLD:

```
blog.test        ->  site "blog"
blog.example     ->  no match (wrong TLD)
blog.notthetest  ->  no match (suffix collision doesn't count)
```

The bare TLD (`test`, or `test.`) has no site label and never resolves.

::: info
The TLD is configurable (for example `dev.local`); the default is `.test`, and `yerd status` shows the active one. See [DNS & .test Domains](./dns) for how `*.test` requests reach the daemon.
:::

### Host cleanup

Matching is case-insensitive and tolerant of cosmetic bits clients send. Before matching, Yerd:

* Lowercases the host (`FOO.TEST` matches `foo`).
* Strips a port (`foo.test:8443` becomes `foo.test`; a trailing `:` is fine).
* Strips one trailing FQDN dot (`foo.test.` becomes `foo.test`).

Hosts that can't be a `.test` name never match: IPv6 literals (`[::1]`), non-ASCII (`föö.test`), an empty host, a leading dot, or a malformed port (`foo.test:abc`).

### Domains, subdomains, and wildcards

By default a site answers for **exactly one** host: its apex `<name>.test`. A site can hold more than one domain, and can answer subdomains and wildcards, but each is **explicit** - you register it with [`yerd domain`](../reference/cli/domains). After confirming the host ends in `.test`, Yerd resolves it with one exact lookup, then one single-label wildcard lookup:

```text
foo.test          ->  foo            (exact apex)
corp.test         ->  foo            (only if `corp` was added to foo)
api.foo.test      ->  no match       (404 by default; subdomains are not implicit)
api.foo.test      ->  foo            (once `*.foo.test` is added to foo)
x.api.foo.test    ->  no match       (a wildcard matches one label; needs `*.api.foo.test`)
```

**This changed in v2.** Earlier builds made every subdomain fall through to its parent site implicitly. That catch-all is gone: `api.foo.test` is a 404 until you register it. Re-enable the old behavior for a site with `yerd domain add foo '*.foo.test'`. The upside is that `foo.test` and `*.foo.test` can now be **two different sites**.

**Exact beats wildcard.** The exact lookup runs first, so a registered `api.foo.test` (exact) wins over a `*.foo.test` wildcard on another site. A wildcard is never a site's primary (canonical) domain - only exact domains can be primary.

Manage a site's domains from the CLI:

```sh
yerd domain list blog                  # show blog's domains, primary marked
yerd domain add blog corp.test         # add an alias
yerd domain add blog '*.blog.test'     # add a wildcard (quote it for the shell)
yerd domain primary blog corp.test     # make corp.test the canonical address
yerd domain remove blog blog.test      # drop a domain (a site keeps >=1 exact)
yerd domain reset blog                 # back to the default apex only
```

For a WordPress site, changing the primary domain also rewrites its `siteurl`/`home`. In the desktop app the same lives under a site's **⋯ → Manage domains…**. See the [domains reference](../reference/cli/domains) for the full command surface and rules.

### Document roots and the served web root

The **document root** is the project directory a site maps to: the child folder for a parked site, or the path you passed to `yerd link`. It's shown in `yerd sites`.

The directory actually served to the browser is the document root's **web root** - which, for most modern frameworks, is a subdirectory rather than the project root itself. Yerd detects this automatically (see [Web root](#web-root-the-served-directory) below), so a Laravel app parked at `~/Sites/blog` is served from `~/Sites/blog/public` without any configuration.

### The secure (HTTPS) flag

Sites start insecure (HTTP only). Securing one serves it over HTTPS with a certificate from Yerd's local CA:

```sh
yerd secure my-app      # serve over HTTPS
yerd unsecure my-app    # back to HTTP only
```

::: tip
`yerd secure` promotes a parked site to a tracked (linked) entry so the flag has somewhere to live, then flips it. See [HTTPS & Certificates](./https) for how the CA and per-site certificates work.
:::

## Web root (the served directory)

Most PHP frameworks don't serve from the project root - they put a front controller in a subdirectory and keep application code out of the document root. Yerd detects the right directory automatically and serves it, so you don't hand-configure a web server:

| Framework | Served from |
|---|---|
| Laravel, Symfony (4+), CodeIgniter 4 | `public/` |
| CakePHP | `webroot/` |
| Drupal (Composer), Yii2 | `web/` |
| Magento 2 | `pub/` |
| WordPress, plain PHP | the project root |

Detection runs in the daemon when a site is registered and whenever its project changes - it reads `composer.json`, looks for framework marker files (`artisan`, `wp-config.php`, `bin/console`, …), and probes for a front controller (`index.php`) in the conventional subdirectories. A site with nothing to detect yet (an empty folder) serves the project root for now, and Yerd watches it so that **cloning a project into a parked folder makes it serve from the right directory within a second or so - no restart, no refresh**.

The served path shows up in `yerd sites` (the `SERVED` column, `/` meaning the project root itself).

::: info Static files are served directly
A request that resolves to a real file under the served root (a stylesheet, image, `favicon.ico`, compiled JS, …) is returned straight from disk by the proxy, with a guessed `Content-Type` - it never touches PHP. A directory request (including the site root) falls back to `index.html` or `index.htm` from that directory when there's no `index.php` there, so a plain static site (no PHP at all) works with no extra configuration. Everything else is handed to the framework's front controller (`index.php`). PHP source files are never served as static bytes. A symlink is allowed to point anywhere inside the site's project directory - so Laravel's `public/storage -> ../storage/app/public` link works with no extra setup - but a symlink that escapes the project directory entirely is refused with an explicit `403 Forbidden` naming the requested path, rather than being silently handed to PHP.
:::

### Overriding the served path

When detection guesses wrong, or you have an unconventional layout, set the served directory explicitly:

```sh
yerd root my-app public      # serve my-app.test from <docroot>/public
yerd root my-app web/app     # a nested directory is fine
yerd root my-app --auto      # forget the override; go back to auto-detection
```

`yerd root <site>` with no path also resets to auto-detection. The path is relative to the site's directory (an absolute path inside it works too); Yerd validates that it resolves to a directory **inside** the project and rejects anything that escapes it. A manual override always wins and is never overwritten by re-detection.

::: tip In the desktop app
The [Sites view](./desktop-app#sites) shows the served web root as a badge per site, and its **Edit…** dialog sets it directly - leave the field blank to go back to auto-detection.
:::

## Related

* [PHP Versions](./php-versions) - set the global default and pin a site to a version.
* [HTTPS & Certificates](./https) - the local CA and the `secure` flag.
* [DNS & .test Domains](./dns) - how `*.test` requests reach the daemon.
* [Configuration Reference](../reference/configuration) - where sites and the TLD are stored.

---

---
url: 'https://yerd.app/guide/proxies.md'
---
# Reverse Proxies

Yerd can put a `.test` address in front of a service it doesn't run itself - a
Reverb server, a Node or Vite dev server, a Docker container, anything already
listening on a port. The service gets Yerd's DNS, its trusted HTTPS, and a clean
`.test` hostname, with no extra config on the service's side.

There are two shapes, and you'll usually want the second for Laravel work:

* A **whole-host proxy** gives a service its own hostname: `reverb.test` → a
  service on `localhost:8080`.
* A **path rule** routes one path *on an existing site* to a service:
  `myapp.test/app` → a service, while every other path on `myapp.test` is still
  served by PHP. This keeps everything **same-origin**, which is exactly what
  Laravel Reverb needs (`wss://myapp.test/app`) so cookies and CORS work without
  a second domain.

Unlike [Herd](https://herd.laravel.com), which writes an nginx vhost, Yerd's
proxy is built into its own request path - there's nothing to configure and no
web server to reload.

## Whole-host proxies

Point a new `.test` host at a running service:

```sh
yerd proxy add reverb http://localhost:8080
```

Now `http://reverb.test/` reaches the service. Serve it over HTTPS the same way
you would a site - a proxy is secured on its own name:

```sh
yerd secure reverb
# https://reverb.test/  (trusted cert, HTTP redirects to HTTPS)
```

Remove it with `yerd proxy remove reverb`.

## Path rules (the Reverb case)

Attach a path to an existing site. Say `myapp` is a Laravel app and Reverb is
running on `:8080`:

```sh
yerd proxy add myapp /app http://127.0.0.1:8080
```

* `https://myapp.test/` and everything else → **PHP** (Laravel), unchanged.
* `https://myapp.test/app` (and `/app/...`) → **Reverb**, websockets included.

The rule inherits the site's TLS, so once `myapp` is secured the `/app` path is
too - your JS client connects to `wss://myapp.test/app` on the same origin. The
full path is passed through to the upstream unchanged (`/app/...` reaches
Reverb as `/app/...`), which is what Reverb expects.

Remove a rule with `yerd proxy remove myapp /app`.

## Upstreams and headers

The upstream is `http://host:port` or `https://host:port`. For an `https://`
upstream, Yerd verifies the certificate for a genuine public host but **skips
verification for a local host** (`localhost`, a loopback/private IP, or a `.test`
name) - self-signed dev backends are the norm there.

Yerd preserves the original `Host` header (many upstreams key vhosts on it) and
adds `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Real-IP`.
Websocket upgrades are tunnelled through. If the upstream is down, a request
returns **`502 Bad Gateway`** rather than hanging.

::: warning You can't proxy to Yerd itself
A target that points back into Yerd - a `.test` host, or `localhost` on the port
Yerd's own proxy is listening on - is rejected, because it would loop forever.
Point the target at the service's real port instead. In rootless mode Yerd binds
`8080`/`8443`, so a dev server on one of those ports will need to move.
:::

## Listing what's configured

```sh
yerd proxy list
```

shows every whole-host proxy and every per-site path rule. `yerd --json proxy
list` gives the same data as JSON for scripting or the desktop app.

For the full command surface, flags, and validation rules, see the
[Proxies CLI reference](../reference/cli/proxies).

---

---
url: 'https://yerd.app/guide/php-versions.md'
---
# PHP Versions

Yerd runs **any number of PHP versions side by side** and lets you pick which one each site uses. PHP isn't bundled, so the install stays small. The first time you ask for a version, Yerd downloads a prebuilt, statically-linked PHP build that Yerd publishes itself (signed and checksummed) and supervises one PHP-FPM pool per version behind the [reverse proxy](./sites).

## In the desktop app

The fastest way to manage PHP is the **PHP** page (under the **Environment** group) in the [desktop app](./desktop-app#php). It's a live view of every installed version and the controls to change them, with no commands to remember.

* A table of installed versions shows 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); progress streams live next to the Install button as the prebuilt static build downloads. An **Install a legacy version** toggle (off by default) swaps the picker over to the [legacy minors](#legacy-php-versions) (7.4 / 8.0 / 8.1) behind a warning block and a mandatory confirmation checkbox; when every current version is already installed the toggle starts on and locks there, since legacy is all that's left to add.
* **Refresh** re-checks for updates and **Update all** updates every version with one pending - [updates are notify-only](#updates-are-notify-only).
* Each row's `⋯` menu offers **Restart**, **Set default** (marks it with a star; disabled for legacy rows, which are tagged with a `legacy` badge), **Update** (when available), and **Uninstall**; **Restart all** restarts every running pool.
* A **Default settings** card edits the [global ini defaults](#tuning-php-settings) applied to every version; leave a field blank to use PHP's built-in default, and saving restarts running pools to apply.
* A **Per-version configuration** card lists your versions down the side, newest first; picking one shows everything scoped to it: the settings form (empty fields inherit the defaults; see [Per-version configuration](#per-version-configuration)), its [custom extensions](#custom-extensions), and a free-form ini-directive editor (e.g. `xdebug.mode = debug`). Each row badges how much that version has configured and marks unsaved edits, so switching versions never loses work. Saving restarts only that version's pool.

## From the command line

### Installing a version

```sh
yerd install php 8.5
```

Yerd detects your platform (`linux`/`macos`, `x86_64`/`aarch64`), fetches Yerd's signed `php.json` manifest, resolves the single published build for your platform and minor, downloads the CLI and FPM tarballs, verifies each against its published SHA-256, then atomically swaps them into place. The manifest is the source of truth for what's installable, so a new PHP patch becomes available as soon as Yerd's build pipeline publishes it.

Installs are **idempotent**: running it again replaces the directory with a fresh download of the current build. If the version isn't published for your platform, the install fails cleanly and writes nothing. The running daemon picks up a new version automatically, no restart required.

::: info A version is always a major.minor
A "PHP version" means a `major.minor` pair like `8.5`, never a full patch like `8.3.12`. Yerd installs and tracks the latest patch of the minor you ask for, and updates move you to a newer patch of that same minor. Input is `8.5` (or `php8.5`); major must be `5..=9`, minor `0..=99`.
:::

::: info Downloads are signed and hash-verified
The `php.json` manifest is signed with a dedicated minisign key whose public half is embedded in Yerd; the daemon verifies that signature before trusting the manifest, then verifies each downloaded tarball against the SHA-256 the manifest lists. Because PHP runs as you, this verification is on the install critical path, not just updates.
:::

### Legacy PHP versions

Yerd also serves three **out-of-support** minors - **7.4**, **8.0**, and **8.1** -
from a separate, independently-signed `php-legacy.json` manifest. It's the same
minisign key and the same per-tarball SHA-256 verification as `php.json`, just a
different listing.

These versions are past their upstream end of life and may contain **unpatched
security vulnerabilities**, so installing one requires an explicit opt-in:

```sh
yerd install php 7.4 --legacy
```

Running `yerd install php 7.4` without `--legacy` refuses and prints an
out-of-support warning instead of installing. In the desktop app, the Install
picker's **Install a legacy version** toggle replaces the version list with the
legacy minors and opens a warning block and a mandatory confirmation checkbox
("I understand and want to install this legacy version anyway.") before the
Install button is enabled.

A legacy version carries hard restrictions once installed:

* **Cannot be the global default.** `yerd use 7.4` is refused; the desktop app
  disables **Set default** for legacy rows.
* **No code coverage.** `phpcover`, `php7.4cover` / `php8.0cover` / `php8.1cover`,
  and `yerd coverage` all error rather than run - see [Code Coverage](./code-coverage).
* **No yerd-dumps capture.** The Dumps view flags legacy rows as unsupported -
  see [Laravel Dumps](./laravel-dumps).
* **No `pcov` or `yerd-dump` `.so` builds.** Neither extension is built for EOL
  PHP, which is why coverage and dumps don't work on legacy versions.

A legacy version **can** still be assigned to an individual site
(`yerd use my-app 7.4`), just not as the global default. See
[Per-site versions](#per-site-versions).

### Bundled extensions

Yerd's builds ship the **bulk** extension set, so a real-world Laravel app has
what it needs out of the box - highlights include **`intl`** (ICU, required by
Laravel's `Number` helper), **`sodium`**, **`mysqli`**, **`gd`**, **`imagick`**,
**`redis`**, **`opcache`**, and **`swoole`**. Database access is covered by the
**`pdo_mysql`**, **`pdo_pgsql`**, and **`pdo_sqlite`** PDO drivers (so
`PDO::getAvailableDrivers()` returns all three) alongside the native `mysqli`,
`pgsql`, and `sqlite3` extensions. Coverage is provided separately by `pcov` - see
[Code Coverage](./code-coverage).

The authoritative list for any install is `php -m` (via the
[`php` shim](#the-global-default)); the full set for the current builds is below.
It rarely changes between patch updates.

Entries marked *(core)* are part of every standard PHP build; the rest are the
extras Yerd's "bulk" build adds. Two extensions are **new in PHP 8.5** and absent
on 8.4, as noted.

| Extension | What it does |
| --- | --- |
| `apcu` | In-process shared-memory cache (APCu) for storing user data across a pool's requests. |
| `bcmath` | Arbitrary-precision decimal arithmetic for money and other exact-math needs. |
| `bz2` | bzip2 stream compression and decompression. |
| `calendar` | Conversions between calendar systems (Julian day count, Gregorian, Jewish, French). |
| `Core` | *(core)* The PHP engine itself: language constructs and built-in functions. |
| `ctype` | *(core)* Fast character-class checks such as `ctype_digit()` and `ctype_alpha()`. |
| `curl` | Network transfers via libcurl (HTTP/S, FTP, and more); the default backend for Guzzle. |
| `date` | *(core)* Date and time handling, including `DateTime` and timezone data. |
| `dba` | Key/value database abstraction over dbm-style engines (GDBM and friends). |
| `dom` | *(core)* Tree-based DOM API for reading and manipulating XML and HTML documents. |
| `event` | libevent bindings for event-driven, non-blocking I/O loops. |
| `exif` | Reads EXIF metadata (camera, orientation, GPS) embedded in image files. |
| `fileinfo` | *(core)* Detects a file's MIME type from its contents rather than its name. |
| `filter` | *(core)* Validates and sanitizes data with `filter_var()` (emails, URLs, ints, …). |
| `ftp` | Client-side FTP protocol support. |
| `gd` | Image creation and manipulation: resize, crop, draw, and convert common formats. |
| `gmp` | Arbitrary-precision integer arithmetic via GNU MP, faster than `bcmath` for big integers. |
| `hash` | *(core)* General hashing framework (`hash()`, HMAC) covering many algorithms. |
| `iconv` | *(core)* Character-set conversion between text encodings. |
| `imagick` | ImageMagick bindings for advanced image processing and a wide range of formats. |
| `imap` | Access to IMAP, POP3, and NNTP mailboxes. |
| `intl` | Unicode/ICU internationalization: number and date formatting, collation, transliteration - required by Laravel's `Number` helper. |
| `json` | *(core)* JSON encoding and decoding. |
| `lexbor` | **New in PHP 8.5.** The Lexbor HTML5 engine powering the new `\Dom\HTMLDocument` parser. |
| `libxml` | *(core)* The shared libxml2 foundation the other XML extensions build on. |
| `mbstring` | Multibyte-safe string functions for UTF-8 and other encodings. |
| `mysqli` | The improved, feature-complete MySQL/MariaDB driver. |
| `mysqlnd` | The native driver backend that `mysqli` and PDO's MySQL driver run on. |
| `openssl` | TLS, symmetric/asymmetric encryption, signatures, and X.509 certificate handling. |
| `opentelemetry` | Engine hooks that let OpenTelemetry auto-instrument code for tracing and metrics. |
| `pcntl` | Unix process control (fork, signals, `waitpid`) for CLI worker processes. |
| `pcre` | *(core)* Perl-compatible regular expressions, i.e. the `preg_*` functions. |
| `PDO` | *(core)* The database-access abstraction layer; the bundled drivers cover MySQL, PostgreSQL, and SQLite. |
| `pdo_mysql` | PDO driver for MySQL/MariaDB. |
| `pdo_pgsql` | PDO driver for PostgreSQL. |
| `pdo_sqlite` | PDO driver for SQLite. |
| `pgsql` | Native PostgreSQL client library (libpq-backed `pg_*` functions). |
| `Phar` | *(core)* PHP Archive support: bundle a whole application into one distributable file. |
| `posix` | POSIX system-call bindings (users, groups, process info) on Unix. |
| `protobuf` | Google Protocol Buffers runtime for compact, fast binary (de)serialization. |
| `random` | *(core)* The modern randomness API (`Randomizer` engines, `random_int()`). |
| `readline` | Interactive line editing and history for CLI and REPL programs. |
| `redis` | Client for the Redis / Valkey in-memory data store (phpredis). |
| `Reflection` | *(core)* Runtime introspection of classes, functions, and attributes. |
| `session` | *(core)* Server-side session state management. |
| `shmop` | Direct read/write access to shared-memory segments. |
| `SimpleXML` | *(core)* Simple object-oriented access to XML documents. |
| `soap` | SOAP client and server for XML web services. |
| `sockets` | Low-level BSD sockets API for building custom network protocols. |
| `sodium` | *(core)* Modern libsodium cryptography: authenticated encryption, signing, and hashing. |
| `SPL` | *(core)* Standard PHP Library: data-structure classes, iterators, and interfaces. |
| `sqlite3` | The self-contained, embedded SQLite database engine. |
| `standard` | *(core)* PHP's standard function library (strings, arrays, math, files, URLs, …). |
| `swoole` | Coroutine-based async runtime and high-performance server framework. |
| `sysvmsg` | System V message-queue inter-process communication. |
| `sysvsem` | System V semaphores for coordinating processes. |
| `sysvshm` | System V shared-memory inter-process communication. |
| `tokenizer` | *(core)* Tokenizes PHP source code; used by linters and static analysis tools. |
| `uri` | **New in PHP 8.5.** A built-in, spec-compliant URI parser (RFC 3986 and WHATWG). |
| `xml` | *(core)* Event-based (SAX/Expat) XML parsing. |
| `xmlreader` | *(core)* Pull-based streaming reader for large XML documents. |
| `xmlwriter` | *(core)* Streaming writer for generating XML. |
| `xsl` | XSLT 1.0 stylesheet transformations over the DOM. |
| `Zend OPcache` | Caches compiled PHP bytecode in shared memory so scripts aren't re-parsed each request (a Zend extension). |
| `zip` | Reading and writing ZIP archives. |
| `zlib` | gzip / deflate stream compression. |

Need something not in this set? Register your own with
[`yerd php ext`](#custom-extensions).

[Legacy versions](#legacy-php-versions) (7.4 / 8.0 / 8.1) ship a smaller, uniform
extension set built once across all three EOL minors, dropping a few extensions
that need PHP 8.0+ or a newer `swoole` than 7.4 can run.

| Extension | What it does |
| --- | --- |
| `apcu` | In-process shared-memory cache (APCu) for storing user data across a pool's requests. |
| `bcmath` | Arbitrary-precision decimal arithmetic for money and other exact-math needs. |
| `bz2` | bzip2 stream compression and decompression. |
| `calendar` | Conversions between calendar systems (Julian day count, Gregorian, Jewish, French). |
| `ctype` | Fast character-class checks such as `ctype_digit()` and `ctype_alpha()`. |
| `curl` | Network transfers via libcurl (HTTP/S, FTP, and more); the default backend for Guzzle. |
| `dba` | Key/value database abstraction over dbm-style engines (GDBM and friends). |
| `dom` | Tree-based DOM API for reading and manipulating XML and HTML documents. |
| `event` | libevent bindings for event-driven, non-blocking I/O loops. |
| `exif` | Reads EXIF metadata (camera, orientation, GPS) embedded in image files. |
| `fileinfo` | Detects a file's MIME type from its contents rather than its name. |
| `filter` | Validates and sanitizes data with `filter_var()` (emails, URLs, ints, …). |
| `ftp` | Client-side FTP protocol support. |
| `gd` | Image creation and manipulation: resize, crop, draw, and convert common formats. |
| `gmp` | Arbitrary-precision integer arithmetic via GNU MP, faster than `bcmath` for big integers. |
| `iconv` | Character-set conversion between text encodings. |
| `imagick` | ImageMagick bindings for advanced image processing and a wide range of formats. |
| `imap` | Access to IMAP, POP3, and NNTP mailboxes. |
| `intl` | Unicode/ICU internationalization: number and date formatting, collation, transliteration. |
| `mbregex` | Multibyte-aware regular expressions (the `mb_ereg*` functions). |
| `mbstring` | Multibyte-safe string functions for UTF-8 and other encodings. |
| `mysqli` | The improved, feature-complete MySQL/MariaDB driver. |
| `mysqlnd` | The native driver backend that `mysqli` and PDO's MySQL driver run on. |
| `opcache` | Caches compiled PHP bytecode in shared memory so scripts aren't re-parsed each request. |
| `openssl` | TLS, symmetric/asymmetric encryption, signatures, and X.509 certificate handling. |
| `pcntl` | Unix process control (fork, signals, `waitpid`) for CLI worker processes. |
| `pdo` | The database-access abstraction layer. |
| `pdo_mysql` | PDO driver for MySQL/MariaDB. |
| `pdo_pgsql` | PDO driver for PostgreSQL. |
| `pdo_sqlite` | PDO driver for SQLite. |
| `pgsql` | Native PostgreSQL client library (libpq-backed `pg_*` functions). |
| `phar` | PHP Archive support: bundle a whole application into one distributable file. |
| `posix` | POSIX system-call bindings (users, groups, process info) on Unix. |
| `protobuf` | Google Protocol Buffers runtime for compact, fast binary (de)serialization. |
| `readline` | Interactive line editing and history for CLI and REPL programs. |
| `redis` | Client for the Redis / Valkey in-memory data store (phpredis). |
| `session` | Server-side session state management. |
| `shmop` | Direct read/write access to shared-memory segments. |
| `simplexml` | Simple object-oriented access to XML documents. |
| `soap` | SOAP client and server for XML web services. |
| `sockets` | Low-level BSD sockets API for building custom network protocols. |
| `sodium` | Modern libsodium cryptography: authenticated encryption, signing, and hashing. |
| `sqlite3` | The self-contained, embedded SQLite database engine. |
| `sysvmsg` | System V message-queue inter-process communication. |
| `sysvsem` | System V semaphores for coordinating processes. |
| `sysvshm` | System V shared-memory inter-process communication. |
| `tokenizer` | Tokenizes PHP source code; used by linters and static analysis tools. |
| `xml` | Event-based (SAX/Expat) XML parsing. |
| `xmlreader` | Pull-based streaming reader for large XML documents. |
| `xmlwriter` | Streaming writer for generating XML. |
| `xsl` | XSLT 1.0 stylesheet transformations over the DOM. |
| `zip` | Reading and writing ZIP archives. |
| `zlib` | gzip / deflate stream compression. |

Dropped versus the stable builds:

* **`opentelemetry`** - requires PHP 8.0+, which breaks the 7.4 build outright.
* **`swoole`** - the pinned `swoole` build needs a newer PHP than 7.4 and would
  fragment across the three EOL minors, so it's dropped to keep one uniform
  legacy set.
* **`swoole-hook-mysql`** - depends on `swoole`.
* **`pcov` and `yerd-dump`** - the external `.so` partners from
  [`forjedio/yerd-php-ext`](https://github.com/forjedio/yerd-php-ext) aren't
  built for EOL PHP, which is why [coverage](./code-coverage) and
  [dumps](./laravel-dumps) don't work on legacy versions.

### Custom extensions

When you need an extension Yerd's builds don't ship (a PECL module like `scrypt`,
or your own compiled `.so`), register it with `yerd php ext`. Yerd loads it into
**both** the web (FPM) runtime and the CLI for that version, so `extension_loaded()`
returns `true` on a `.test` route and `php -m` lists it - the two used to diverge.

```sh
yerd php ext add 8.5 /opt/homebrew/lib/php/pecl/20250925/scrypt.so
yerd php ext list
yerd php ext remove 8.5 scrypt
```

* **Extensions are tied to a PHP version.** A native `.so` is compiled against one
  PHP *minor*, so you register it under the version it was built for (`8.5` above);
  it loads only for that version.
* **Every add is load-probed.** Before saving, Yerd actually loads the `.so` into
  that version's PHP and rejects it if it can't load - a wrong-version build, a
  missing dependency, or a Zend extension registered without `--zend` fails with a
  clear message instead of silently breaking your pools.
* **Zend extensions** (xdebug/opcache-style) use `--zend`:
  `yerd php ext add 8.5 /path/xdebug.so --zend`.
* **Naming.** The removal handle defaults to the `.so` filename (`scrypt` above);
  override it with `--name`.
* **Missing files** are handled gracefully: if a registered `.so` later disappears
  (e.g. Homebrew bumps its PECL directory on upgrade), Yerd skips it with a warning
  rather than failing to start the pool, and `yerd php ext list` marks it
  `(missing!)`.

Adding or removing an extension restarts that version's running FPM pool to apply
it. In the desktop app, the same registry lives in the **Extensions** section of
the **Per-version configuration** card on the **PHP** page: pick the version's
tab, then **Add…** to browse for a `.so`. An extension whose file has gone
missing is flagged, and its `⋯` menu can seed a matching ini directive. Registered
extensions are stored per version in the config file - see the
[Configuration Reference](../reference/configuration#php).

### How versions are stored

Each install lands under the per-user data directory:

```text
{data}/php/php-8.5/bin/php          # the CLI interpreter
{data}/php/php-8.5/sbin/php-fpm     # the FastCGI process manager
{data}/php/php-8.5/.yerd-version    # the exact patch installed, e.g. "8.5.6"
{data}/bin/php                      # the default-version CLI shim
{data}/bin/php8.5                   # a per-version CLI shim
```

The dir is named for the **major.minor** (`php-8.5`); `.yerd-version` records the exact patch (`8.5.6`). Update checks read that marker to decide whether a newer patch exists. The daemon discovers installed versions by walking this directory and finding each `sbin/php-fpm` at startup.

### The global default

Yerd has one **global default** version, used for the `php` shim at `{data}/bin/php` and as the fallback for any site that hasn't pinned its own. Set it with one argument:

```sh
yerd install php 8.5
yerd use 8.5
```

A fresh config defaults to **PHP 8.3**, but you'll usually set your own right after installing.

::: warning Legacy versions can't be the default
A [legacy version](#legacy-php-versions) (7.4 / 8.0 / 8.1) is ineligible as the
global default - `yerd use 7.4` is refused client-side, and the desktop app
disables **Set default** for legacy rows. It can still be pinned to an
individual site.
:::

::: tip Add the shim dir to your PATH
Put `{data}/bin` (Yerd prints the exact path) on your `PATH` so a bare `php` matches the version your sites run. The bare `php` shim resolves the current default at run time, so `yerd use` takes effect immediately with nothing to re-point.
:::

Alongside the default `php` shim, Yerd maintains a `php<version>` shim for each installed version (`php8.4`, `php8.3`, ...) so you can reach a specific version directly, plus `phpcover` / `php<version>cover` shims that run PHP with the pcov coverage driver enabled. See [Code Coverage](./code-coverage). Each shim runs the right PHP with that version's ini and any [custom extensions](#custom-extensions) you've registered.

### Per-site versions

Any site can pin its own version. Pass `yerd use` two arguments, a site name and a version:

```sh
yerd use my-app 8.3
```

Now `my-app.test` runs on 8.3 while every other site follows the global default.

| Site setting | Effective version |
|---|---|
| Pinned (`yerd use <site> 8.3`) | `8.3` |
| Not pinned | the global default |

Clearing a pin reverts the site to whatever the global default is at the time.

Check what each site resolves to with `yerd sites`, which lists every site with its kind, PHP version, HTTPS state, and document root. See [Sites](./sites) for parking and linking.

::: warning Pin a version you've installed
Pinning a site (or the default) to an uninstalled version means there's no FPM binary to start when a request arrives. Install it first (`yerd install php 8.3`), then pin. `yerd doctor` flags a pool that can't start.
:::

### Listing versions

```sh
yerd list php
```

This shows every installed version, marks the default, and flags any with a newer patch available. Update flags come from the **daemon's cache** by default, so no network call is made and the command is instant.

| Command | What you get |
|---|---|
| `yerd list php` | Installed versions, default, cached update flags (no network) |
| `yerd list php --check` | Same, but polls the distribution now to refresh update flags |
| `yerd list php --available` | Versions installable from the distribution, tagging installed ones |

`--available` takes precedence over `--check`. Add `--json` (a global flag) for machine-readable output.

### Updates are notify-only

Yerd checks for newer **patches** of the minors you have and tells you about them, but never installs on its own. The daemon periodically polls the distribution, compares each installed minor's latest patch against its `.yerd-version` marker, and on a newer patch logs:

```text
a newer PHP patch is available (run `yerd update php`)
```

It records this in the cache `yerd list php` reads. The poll is failure-tolerant: a network or platform failure is logged quietly and your cached state is left untouched.

Update on your terms:

```sh
yerd update php 8.5     # update just 8.5 to its latest patch
yerd update php         # update every installed version
```

An update is the same atomic install flow: it moves `8.5.4` → `8.5.6` and never jumps to a different minor. To move minors, run `yerd install php 8.6` and `yerd use 8.6` explicitly.

::: tip Nothing updates behind your back
Updates are strictly notify-only. The only automatic network call is the lightweight update check, which downloads nothing but a directory listing. Yerd downloads or swaps a PHP version only when you run `yerd update php`.
:::

### Tuning PHP settings

Yerd keeps a small set of **global PHP ini defaults** that are applied to *every*
installed version's FPM pool. Set and clear them with `set` / `unset`:

```sh
yerd set php memory_limit 512M
yerd set php upload_max_filesize 64M
yerd unset php memory_limit          # reset to PHP's built-in default
```

Only an allowlisted set of directives is accepted (e.g. `memory_limit`,
`max_execution_time`, `upload_max_filesize`, `post_max_size`, `display_errors`,
`error_reporting`), and the value is validated client-side before it's sent, so a
typo is a clean error rather than a broken pool. The configured values are echoed
back by `yerd list php` under a `settings:` block. See the [PHP CLI
reference](../reference/cli/php#global-php-ini-settings) for the full list and the
[Configuration Reference](../reference/configuration#php) for how they're stored
and rendered into FPM config.

### Per-version configuration

Every setting can also be pinned for a **single** installed version with the
`--only` flag - the override wins over the global default for that version only,
and applies to both its FPM pool and its CLI:

```sh
yerd set php memory_limit 1G --only 8.3   # only PHP 8.3 gets 1G
yerd unset php memory_limit --only 8.3    # 8.3 inherits the global value again
```

Beyond the allowlist, `yerd php ini` sets **free-form ini directives** per
version - typically the settings of a custom extension. The classic xdebug
setup is two commands:

```sh
yerd php ext add 8.3 /opt/php/xdebug.so --zend   # load the extension
yerd php ini set 8.3 xdebug.mode debug           # configure it
```

Directive names and values are shape-checked so they can never corrupt the
generated config, but Yerd doesn't second-guess their meaning - a directive PHP
doesn't recognise is simply ignored by PHP. A per-version change restarts only
that version's pool, and per-version configuration survives uninstalling and
reinstalling the version. In the desktop app the same lives in the
**Per-version configuration** card on the PHP page: pick a version from the list
to get the settings form (empty fields inherit the defaults), that version's
extensions, and a directive editor. A version that still has extensions
registered after being uninstalled stays in the list, so those registrations can
be removed. See the
[PHP CLI reference](../reference/cli/php#custom-ini-directives) for the rules
and the denylist of directives Yerd manages elsewhere.

### Command summary

| Command | What it does |
|---|---|
| `yerd install php <version>` | Download + install the latest patch of a minor. |
| `yerd use <version>` | Set the global default version (and the `php` shim). |
| `yerd use <site> <version>` | Pin one site to a version. |
| `yerd list php [--check]` | List installed versions; `--check` refreshes update flags. |
| `yerd list php --available` | List versions installable from the distribution. |
| `yerd update php [<version>]` | Update one (or all) versions to the latest patch. |
| `yerd uninstall php <version>` | Remove a version's files (blocked if a site uses it). |
| `yerd restart php [<version>]` | Restart one (or all) running FPM pools. |
| `yerd set php <setting> <value> [--only <version>]` | Set a global PHP ini default, or a per-version override with `--only`. |
| `yerd unset php <setting> [--only <version>]` | Reset a global setting to PHP's built-in value. With `--only`, remove one version's override so the global value applies again. |
| `yerd php ini set <version> <name> <value>` | Set a free-form ini directive (e.g. `xdebug.mode`) for one version. |
| `yerd php ini unset <version> <name>` | Remove a free-form ini directive. |
| `yerd php ini list` | Show per-version overrides and directives. |
| `yerd php ext add <version> <path> [--zend] [--name <name>]` | Register a custom extension (load-probed) for a version. |
| `yerd php ext remove <version> <name>` | Remove a registered extension. |
| `yerd php ext list` | List registered custom extensions, grouped by version. |

Add `--json` to any command for machine-readable output.

## Related

* [Sites](./sites) - parking, linking, and how a request reaches an FPM pool.
* [HTTPS & Certificates](./https) - trusted HTTPS per site.
* [Diagnostics](./diagnostics) - `yerd status` and `yerd doctor` for when a pool won't start.
* [CLI Reference](../reference/cli/) - every command and flag.
* [Configuration Reference](../reference/configuration) - where the default and per-site pins live on disk.
* [yerd-php crate](../developer/crates/yerd-php) - the supervisor, version resolution, and download internals.

---

---
url: 'https://yerd.app/guide/code-coverage.md'
---
# Code Coverage

Yerd bundles [**pcov**](https://github.com/krakjoe/pcov), a fast line-coverage
driver, with every PHP version it installs - so you can run your test suite with
coverage (PHPUnit, Pest, `artisan test --coverage`) without installing or
configuring an extension yourself.

The friendliest way in is the **`yerd coverage`** subcommand: it runs your
**default** PHP version with pcov enabled and forwards everything after the
`coverage` subcommand straight to PHP - the same coverage mechanism as the
`phpcover` shim, but discoverable from `yerd --help` without needing the shim
directory on your `PATH`.

Under the hood, coverage is exposed through dedicated **cover shims**: `phpcover`
for your default PHP version, and `php<version>cover` (for example `php8.4cover`)
for a specific one. They live in the same `{data}/bin` directory as the regular
`php` shim. `yerd coverage` runs the same coverage mechanism as `phpcover`
(default PHP + pcov); use a `php<version>cover` shim when you need to pin coverage
to a specific version.

::: info Zero overhead by default
The plain `php` and `php<version>` shims **never** load pcov, so normal CLI
scripts and your `.test` sites run with no coverage instrumentation. pcov is
loaded only when you invoke a `…cover` shim - coverage is strictly opt-in,
per command.
:::

## Running tests with coverage

Use `yerd coverage` (or a cover shim) anywhere you'd normally use `php`:

```sh
# Default PHP version, via the subcommand - args pass straight through to PHP
yerd coverage artisan test --coverage
yerd coverage vendor/bin/phpunit --coverage-text

# The same coverage mechanism, via the shim
phpcover artisan test --coverage

# Pin coverage to a specific PHP version with a versioned shim
php8.4cover vendor/bin/pest --coverage
```

::: tip `yerd coverage` is a passthrough
Everything after the `coverage` subcommand is handed verbatim to PHP, so flags
like `--coverage` belong to your test runner, not to `yerd`. Two small edges: a
leading `yerd coverage --help` prints `yerd`'s own help for the command (put
`--help` after your script to forward it, e.g. `yerd coverage artisan --help`),
and the global `--json` flag has no effect here - it, like every other flag, is
passed to PHP rather than producing a JSON response.
:::

Each cover shim points `PHPRC` at a pcov-enabled copy of Yerd's CLI ini, then
hands off to your script. Because `PHPRC` is an environment variable rather
than a CLI flag, it's inherited by any PHP process your script spawns in
turn - which is what makes `artisan test`'s child PHPUnit/Pest/paratest run
see a working coverage driver too, not just the top-level `artisan` process.

::: tip Add the shim dir to your PATH
The cover shims sit in the same `{data}/bin` directory as `php` (Yerd prints the
exact path). Once that's on your `PATH`, `phpcover` and `php<version>cover` are
available everywhere, right next to the version shims described in
[PHP Versions](./php-versions).
:::

## Automatic, per version

You don't install or enable anything. Whenever you install a PHP version, Yerd
fetches the matching pcov build for it in the background and (re)creates its cover
shim. The extension is downloaded from the
[`forjedio/yerd-php-ext`](https://github.com/forjedio/yerd-php-ext) releases,
verified by SHA-256, and stored alongside your PHP installs at
`{data}/php-ext/php-<version>/pcov.so` - beside the install, so a PHP **patch**
update never deletes it.

* **`phpcover`** always tracks your [global default](./php-versions#the-global-default)
  version, resolved at run time - change the default with `yerd use` and
  `phpcover` follows.
* **`php<version>cover`** is created for each installed version and removed when
  you uninstall that version.

::: info Needs a matching released build
Like the [dumps extension](./laravel-dumps), pcov is ABI-specific: one build per
PHP minor, per OS, per architecture. If a build for your exact PHP version and
platform hasn't been published yet, the cover shim reports that pcov isn't
installed for that version rather than running without coverage. The fetch is
best-effort and never blocks a PHP install.
:::

::: warning No coverage on legacy PHP
pcov isn't built for [legacy versions](./php-versions#legacy-php-versions) (7.4 /
8.0 / 8.1, PHP < 8.2). `phpcover`, `php7.4cover` / `php8.0cover` / `php8.1cover`,
and `yerd coverage` all **error** on a legacy version rather than run.
:::

::: warning Unix only
Cover shims are created on macOS and Linux only. They are not generated on other
platforms.
:::

## How it works

The `yerd` binary is a **multi-call** binary: before it parses any CLI arguments,
it checks the name it was invoked as. The `phpcover` and `php<version>cover`
entries in `{data}/bin` are symlinks back to `yerd` itself; when `yerd` sees one
of those names, it resolves the right PHP CLI binary plus that version's
`pcov.so`, writes a copy of Yerd's CLI ini with pcov's `extension`/
`pcov.enabled` directives appended, and `exec`s PHP with `PHPRC` pointing at
that copy. Invoked under any other name it falls through to the normal CLI, so
the clean `php`/`php<version>` shims are untouched.

`yerd coverage` reaches that **same** code path from the other direction: rather
than being keyed on the invoked name, the subcommand hands its forwarded
arguments to the identical cover-shim logic for the default version. So the two
front doors, subcommand and shim, share one implementation.

## See also

* [PHP Versions](./php-versions) - installing versions and the `php`/`php<version>` shims.
* [Laravel Dumps](./laravel-dumps) - the other extension served from `yerd-php-ext`.

---

---
url: 'https://yerd.app/guide/tooling.md'
---
# Tooling

Yerd can install the **developer tools** a typical PHP/Laravel/WordPress project
reaches for - [Composer](https://getcomposer.org), [Node.js](https://nodejs.org)
(with `npm`/`npx`), [Bun](https://bun.sh), the **Laravel installer**, and
**WP-CLI** - the same way it installs [PHP versions](./php-versions):
self-contained binaries fetched on demand (the Laravel installer and WP-CLI are
built via Composer) and dropped onto your `PATH`. No system package manager, no
global install, nothing to uninstall by hand. Already have one installed
elsewhere? Yerd [detects it](#external-tools) and, for most tools, uses it
instead.

| Tool | `id` | Provides | Source |
|---|---|---|---|
| Composer | `composer` | `composer` | getcomposer.org (phar) |
| Node.js | `node` | `node`, `npm`, `npx` | nodejs.org (latest LTS) |
| Bun | `bun` | `bun`, `bunx` | github.com/oven-sh/bun |
| Laravel installer | `laravel` | `laravel` | Composer (`laravel/installer`) |
| WP-CLI | `wp-cli` | `wp` | Composer (`wp-cli/wp-cli-bundle`) |

::: tip Why bundle these?
A fresh machine that has Yerd shouldn't also need Homebrew, `nvm`, or a global
Composer just to run a Laravel app with a Vite front-end. Yerd keeps these tools
in its own data directory, isolated from anything else on your system, and
removes them cleanly on uninstall.
:::

## In the desktop app

Open the **Tooling** page from the sidebar (under the **Developer** group). It
lists the developer tools Yerd manages and their install status:

* **Composer**, **Node**, **Bun**, the **Laravel installer**, and **WP-CLI**,
  each showing the commands it provides.
* Click **Install** to fetch the latest release; once installed you get
  **Update** (re-fetch the current latest) and **Uninstall**.
* A tool you've installed yourself shows an **External** badge and a *Managed by
  you* note. **Install** is still offered, so you can take Yerd's own copy as
  well - see [External tools](#external-tools) below.
* The Laravel installer and WP-CLI are built with Composer, so their **Install**
  button stays disabled until Yerd's own Composer is installed.
* Each tool is placed on your `PATH` alongside PHP and managed entirely by Yerd,
  so it won't collide with a system install.

## From the command line

```sh
yerd tools                      # list the tools and their install status
yerd install tool node          # download + install the latest Node LTS
yerd install tool bun
yerd install tool composer
yerd install tool laravel       # build the Laravel installer (needs Composer)
yerd install tool wp-cli        # build WP-CLI (needs Composer)
yerd uninstall tool bun         # remove a tool and its PATH commands
```

`yerd install tool <id>` is idempotent - run it again to update to the current
latest. See the [Tooling CLI reference](../reference/cli/tooling) for the exact
command surface.

::: tip Updating WP-CLI
Because Yerd's `wp-cli` is a Composer install rather than a phar, WP-CLI's own
`wp cli update` (its phar self-update subcommand) isn't applicable and will
error - use `yerd install tool wp-cli` (or **Update** on the Tooling page)
instead, the same way you wouldn't run `composer self-update` on Yerd's managed
Composer.
:::

## External tools

You don't have to let Yerd manage most of these tools. If you already have
`composer`, `node`, `bun`, or the `laravel` installer available on your `PATH` -
via Homebrew, `nvm`/`fnm`, a global `composer require`, etc. - Yerd **detects**
it and treats it as already available:

* On the **Tooling** page the tool shows an **External** badge (instead of a
  version) and a *Managed by you* note - it's yours to manage, not Yerd's. You
  can still press **Install** to take Yerd's own copy alongside it, which you'll
  need if you want Yerd to build the Laravel installer or WP-CLI.
* The [Laravel site wizard](./sites#create-a-new-laravel-site) and site scaffolding
  accept external Composer / Node / Bun / Laravel as satisfying their
  prerequisites, so you won't be asked to install a second copy. Externally
  installed Composer and the Laravel installer still run under the **Yerd PHP
  version you select**, so versions stay consistent.

A couple of things to know:

* **WP-CLI is the exception: an external `wp` doesn't count.** Yerd runs WP-CLI
  by executing its own build directly rather than by calling `wp` on your `PATH`,
  so it always needs its own copy and never reports one you installed yourself as
  *External*. Your `wp` keeps working exactly as before; the
  [WordPress site wizard](./sites#create-a-new-wordpress-site) will simply offer
  to install Yerd's WP-CLI as a prerequisite.
* **Managed tools win.** If a tool is both Yerd-installed and on your `PATH`, the
  Yerd-managed one takes precedence (its `{data}/bin` shim is earlier on `PATH`).
  That includes `composer`, so installing Yerd's copy changes which `composer`
  your other projects get.
* **Building the *managed* Laravel installer or WP-CLI needs Yerd's own
  Composer.** An external Composer is fine for *scaffolding*, but it can't build
  Yerd's managed `laravel`/`wp-cli` tools - so their **Install** stays disabled
  until you install Yerd's Composer. For the Laravel installer you can skip that
  entirely and keep using your external copy; WP-CLI has no such fallback, per
  the exception above.

::: tip How detection works
Because the daemon runs with a minimal environment, Yerd reads your login shell's
`PATH` to find tools your terminal can see (Homebrew, `fnm`, a global Composer
bin, …). It only looks **outside** its own `{data}/bin`, so a Yerd shim is never
mistaken for an external install.
:::

## How it works

The model mirrors [PHP versions](./php-versions) and [services](./services):

* **Self-contained binaries.** Each tool is a relocatable build - Node's tarball
  bundles `node` + `npm` + `npx`, Bun is a single binary, Composer is a phar run
  by Yerd's managed PHP. Nothing is compiled and nothing touches system paths.
* **Verified downloads.** Every artifact is checked against the publisher's
  `SHASUMS256.txt` (Node, Bun) or `composer.phar.sha256sum` (Composer) before it
  is installed.
* **Installed under Yerd's data dir.** Tools live in `{data}/tools/<id>/`
  (e.g. `~/Library/Application Support/io.yerd.Yerd/tools` on macOS), a sibling of
  your PHP installs - so a PHP update never disturbs them.
* **Exposed on `PATH`.** Their commands are symlinked into `{data}/bin`, the same
  directory that holds the `php`/`php<ver>` shims. Put that directory on your
  `PATH` once (see below) and `composer`, `node`, `npm`, `bun`, … just work.
* **Rootless.** Everything runs as your user, no elevation.

### Latest only

Yerd installs the **latest stable** release of each tool (the latest **LTS** for
Node). There is no per-project version picker - **Update** simply re-fetches the
current latest and replaces it in place. If you need to pin a specific Node
version per project, a system version manager like `nvm`/`fnm` is still the right
tool; Yerd's goal here is a good default that's always there.

## Put Yerd's bin directory on your PATH

The tool commands live in Yerd's `{data}/bin` directory. Installing your first
tool from the CLI **adds it to your shell automatically** - so usually there's
nothing to do. If you installed via the desktop app, or want to manage the entry
yourself, run it once:

```sh
yerd path install     # adds {data}/bin to your shell startup file
```

Open a new terminal afterwards (or `source` your shell file). Then:

```sh
which composer        # → …/io.yerd.Yerd/bin/composer
node --version
npm --version
bun --version
```

`yerd path install` writes a small, guarded block to your shell's startup file
(`.zshrc`, `.bashrc`/`.bash_profile`, or `config.fish`). `yerd path uninstall`
removes it; `yerd path print` shows the snippet without touching any file.

::: info Coexisting with Herd, Homebrew, or nvm
Yerd's `bin` directory is **prepended** to `PATH`, so its `node`/`composer` take
precedence over other copies on your machine. If you'd rather your existing
tools win, put their directories earlier in your shell file. Nothing Yerd
installs ever shadows a tool you didn't ask it to manage.
:::

## Composer needs PHP

Composer is a phar, so it runs under Yerd's managed PHP - `composer` resolves to
your [default PHP version](./php-versions). Install at least one PHP version
first (`yerd install php 8.4`); otherwise `composer` reports that no PHP is
available. Node and Bun are standalone and have no such dependency.

::: tip ext-intl and friends
Yerd's PHP builds ship the **bulk** extension set, including
`intl`, `sodium`, `mysqli`, and more - so Composer packages that require them
install without extra steps. See [PHP Versions](./php-versions) for the bundled
extension list.
:::

## Where things live

| Path | Contents |
|---|---|
| `{data}/tools/composer/composer.phar` | The Composer phar. |
| `{data}/tools/node/node-<ver>-<os>-<arch>/` | The unpacked Node distribution. |
| `{data}/tools/bun/bun-<os>-<arch>/bun` | The Bun binary. |
| `{data}/tools/laravel/bin/laravel` | The Laravel installer (built via Composer). |
| `{data}/tools/wp-cli/vendor/wp-cli/wp-cli/php/boot-fs.php` | WP-CLI (built via Composer). |
| `{data}/bin/{composer,node,npm,npx,bun,bunx,laravel,wp}` | The `PATH` shims. |

`{data}` is Yerd's per-user data directory (`yerd status` and
`yerd path print` both show the exact path for your platform).

## See also

* [Tooling CLI reference](../reference/cli/tooling) - every command and flag.
* [PHP Versions](./php-versions) - the version model these tools follow.
* [Services & Databases](./services) - the same install-on-demand approach for
  databases and caches.

---

---
url: 'https://yerd.app/guide/services.md'
---
# Services & Databases

Yerd installs and supervises local **database, cache, and search** engines as native,
per-user processes - the way [DBngin](https://dbngin.com) does, but folded into
the same [`yerdd` daemon](./daemon) that already runs your sites, PHP, HTTPS, and
DNS. No Docker, no containers, no VM. A single `yerd status` shows the whole
stack.

The five engines:

| Service | `id` | Kind | Default port |
|---|---|---|---|
| Redis (Valkey) | `redis` | Cache / key-value | 6379 |
| MySQL | `mysql` | SQL database | 3306 |
| MariaDB | `mariadb` | SQL database | 3306 |
| PostgreSQL | `postgres` | SQL database | 5432 |
| Meilisearch | `meilisearch` | Search index | 7700 |

::: info Redis is served by Valkey
The `redis` slot is filled by **Valkey**, the BSD-licensed fork, because recent
Redis releases are no longer cleanly redistributable. It is wire-compatible, so
your Redis clients work unchanged. Yerd shows it as `Redis (Valkey)`.
:::

::: tip Engine availability
All five engines are implemented end-to-end. Whether a specific engine/version
installs depends on whether a prebuilt build is published for your platform in
Yerd's hosted distribution - run `yerd service available` to see what you can
install right now. MySQL/MariaDB share port 3306, so only one can be enabled on it
at a time.
:::

## How it works

Service support follows the same model as [PHP versions](./php-versions):

* **Native processes, not Docker.** Prebuilt binaries are downloaded on demand
  from Yerd's own hosted distribution, then run as your user on loopback.
* **Supervised.** `yerdd` runs one process per enabled service, restarts it on
  crash with backoff, and reports health - the same supervision substrate the PHP
  pools use ([`yerd-supervise`](../developer/crates/yerd-supervise)).
* **Rootless.** Everything runs as your user with no elevation. See the
  [privilege model](./elevation).
* **Local-dev posture.** Engines bind to loopback only and accept passwordless
  connections from your user. This is convenient for local development and is not
  meant to be exposed to a network.

## In the desktop app

The [desktop app](./desktop-app) surfaces every engine on its **Services** page,
under the **Developer** group in the sidebar. Install a version, then Start /
Stop / Restart it inline - no terminal needed. The daemon auto-starts every
installed engine on boot, so what you install stays running across reboots.

Each installed engine's `⋯` menu offers:

* **Configuration** - copies a ready-made Laravel `.env` for that engine, with a
  database picker that pre-fills `DB_DATABASE` for the SQL engines.
* **Edit port** - change the loopback port (applies on next start).
* **View logs** - tail the service log.
* **Manage databases** - create, drop, back up, and restore databases (SQL
  engines only).
* **Change version** - upgrade in place, keeping your data.
* **Uninstall** - remove the engine.

## From the command line

### Managing services

```sh
yerd service available            # versions installable for your platform
yerd service install redis 8      # download, install, and start
yerd service install postgres 17-full  # PostGIS build (see below)
yerd services                     # list everything: version, state, port

yerd service start redis        # start it now
yerd service stop redis         # stop for this session (returns on next daemon start)
yerd service restart redis

yerd service set-port redis 6380   # change the loopback port (next start)
yerd service logs redis --lines 50 # tail the service log

yerd service change-version redis 8.1   # upgrade in place, keep data
yerd service uninstall redis 8          # remove binaries, keep data
yerd service uninstall redis 8 --purge  # remove binaries AND data
```

See the [Services CLI reference](../reference/cli/services) for every flag.

### Managing databases

For the SQL engines (`mysql`, `mariadb`, `postgres`), Yerd can create, drop, list,
back up, and restore databases without you reaching for a separate client. The
engine must be running.

```sh
yerd db create mysql my_app
yerd db list mysql
yerd db backup mysql my_app ./my_app.sql      # plain-SQL dump
yerd db restore mysql my_app ./my_app.sql     # replay into an existing db
yerd db drop mysql my_app
```

Database names are validated to a strict allowlist (letters, digits, and
underscores; must start with a letter or `_`; at most 63 characters) so the
generated SQL is injection-proof. Engine-internal databases are protected and
can't be dropped. `backup` writes to a temp file and atomically renames it, so a
failed dump never clobbers an existing one. See the [Databases CLI
reference](../reference/cli/db) for details.

## Configuration

Installed services are recorded in your [config file](../reference/configuration)
under per-service `[services.<id>]` tables, each carrying the pinned `version`,
the `port`, and an `enabled` flag (a record of the last start/stop intent):

```toml
[services.redis]
version = "8"
port = 6379
enabled = true
```

You normally don't hand-edit this - drive it through the CLI (or the
[desktop app](./desktop-app)), which keeps the config and the running processes in
sync.

### Auto-start on boot

The daemon auto-starts **every installed engine** when it starts (in the
background, so a slow database cold-boot never delays the proxy or DNS). The
`enabled` flag does **not** gate this - a service you `stop` returns on the next
daemon start. To keep an engine off for good, `uninstall` it.

::: tip MySQL and MariaDB share port 3306
Only one can listen on `3306` at a time. If both are installed, whichever binds
first wins and the other logs a non-fatal "port in use" and stays down. Run a
single SQL engine, or give one a different `port`.
:::

## PostgreSQL: base and PostGIS (`full`) builds

PostgreSQL ships in **two flavours**, and you choose which one you install by its
version label. `full` is the PostGIS variant, appended to the version as a
`<version>-full` label:

| Label | What you get | Compressed size | License |
|---|---|---|---|
| `17` | The lean base build. | ≈ 6.5 MB | 100% PostgreSQL License (permissive) |
| `17-full` | The base plus **PostGIS** and its geospatial stack. | ≈ 60-64 MB | GPL-encumbered (see below) |

```sh
yerd service install postgres 17        # lean base
yerd service install postgres 17-full   # PostGIS build
```

Both show up as distinct installable versions in `yerd service available` and in
the desktop app's version picker. The build is downloaded once per install and
cached.

### What each build bundles

Both builds ship the standard contrib extensions - `pg_stat_statements`,
`pg_trgm`, `citext`, `unaccent`, `hstore`, `ltree`, `btree_gin`, `btree_gist`,
`fuzzystrmatch`, `tablefunc`, `intarray`, `cube`, `earthdistance`,
`postgres_fdw`, `dblink`, `pageinspect`, `amcheck`, `pgstattuple`,
`pg_buffercache` - plus **`pgvector`** (Linux and macOS).

The **`full`** build adds the geospatial and crypto stack on top:

* **PostGIS** with raster and topology: `postgis`, `postgis_raster`,
  `postgis_topology`, `postgis_tiger_geocoder`, `address_standardizer`.
* `pgcrypto`, `uuid-ossp`, `sslinfo`, and `xml2`.

### Base and `full` share one datadir - switch between them freely

`17` and `17-full` are separate *installs* but **share a single data directory**
(Postgres datadirs are pinned to the major version, and the `full` variant maps to
the same major). So you can install the base build, create databases, then switch
with `yerd service change-version postgres 17-full` (or back) **without losing your
data** - the databases carry across the switch.

One caveat: PostGIS objects created while running `full` need the PostGIS `.so` to
be *used*. The base build still starts against the shared datadir and your regular
tables are fine, but queries that touch PostGIS types or functions only work while
`full` is running - so enable `full` before you start using PostGIS.

Uninstalling with `--purge` deletes the shared datadir, so `yerd service uninstall
postgres <label> --purge` removes the databases for **both** flavours of that major.

::: warning `full` is GPL-encumbered
The base build stays **100% PostgreSQL License** (permissive). The `full` build
bundles GPL/LGPL components - **PostGIS** is GPLv2 and **GEOS** is LGPL-2.1 (PROJ,
GDAL, json-c, and protobuf-c are permissive). Install `full` only if that
licensing suits your project. Each component's notice ships inside the downloaded
tarball (`LICENSE-postgis`, `LICENSE-geos`, `LICENSE-proj`, `LICENSE-gdal`, and
friends).
:::

Backup and restore are unchanged - both builds ship the same `pg_dump` /
`pg_restore` / `psql` tools, so [`yerd db backup` / `restore`](../reference/cli/db)
work identically. A dump that uses PostGIS objects only restores into a `full`
target, because those objects need the PostGIS `.so`.

## Windows and Redis licensing

[Windows service support is still on the roadmap](../developer/cross-platform)
alongside the rest of the Windows platform work. On macOS and Linux all four
engines run today (subject to a published build for your architecture).

## See also

* [Services CLI reference](../reference/cli/services) and [Databases CLI reference](../reference/cli/db)
* [PHP Versions](./php-versions) - the supervision model services share
* [Configuration Reference](../reference/configuration) - the `[services.<id>]` tables
* [yerd-services](../developer/crates/yerd-services) and [yerd-supervise](../developer/crates/yerd-supervise) - the crates behind this

---

---
url: 'https://yerd.app/guide/mail.md'
---
# Mail Capture

Yerd ships a built-in **mail-capture SMTP server** - a local sink that catches
every email your apps "send" and keeps it for you to inspect, Herd-style. Point
your app's mailer at it and password resets, order confirmations, and queued
notifications land in Yerd instead of a real inbox. Nothing is ever relayed:
**captured mail never leaves your machine**.

It's the local-dev counterpart to Mailpit / MailHog / Mailtrap, except there's
nothing to install or run - it's part of the [`yerdd` daemon](./daemon) that
already runs your sites, PHP, HTTPS, and DNS.

## In the desktop app

The [desktop app](./desktop-app) surfaces mail capture on its own **Mail** page,
under the **Developer** group in the sidebar. It's the richest way to drive
capture and read what's been caught.

* The page shows the current **capture status** and the **port** the SMTP
  listener is bound to.
* An **enable toggle** turns capture on or off, and a **port** field changes the
  listening port (both take effect on the next daemon restart).
* **Show Mails** pops out the separate **Mails** viewer window, which renders
  HTML bodies (including inline images) in a sandboxed frame so you can keep
  captured mail next to your editor and browser.
* A **Laravel configuration** card emits the `.env` mail keys (`MAIL_HOST`,
  `MAIL_PORT`, …) ready to paste into your app, with an editable From name and
  address.

Captured mail is tracked as **read or unread**. New messages count toward an
unread badge that shows in three places: a pill on the sidebar **Mail** item
(click it to open the viewer), an orange dot on the tray icon, and a **Mail (N)**
label in the tray menu. Clicking a message in the Mails viewer marks it read, and
unread messages are highlighted in the list - the message the viewer auto-selects
on open stays unread until you click it - so the badge always reflects what you
haven't looked at yet.

## From the command line

```sh
# Mail capture is already on (loopback SMTP on 127.0.0.1:2525).
# Point your app's mailer at it, send a mail, then:

yerd mail list          # newest-first table of captured emails
yerd mail show 000003   # one email's headers + body
yerd mail clear         # delete everything captured so far
```

## On by default

Mail capture is **enabled by default**. The daemon binds a tiny SMTP listener on
`127.0.0.1:2525` (the `DEFAULT_MAIL_PORT`) at startup - no setup, no elevation, no
`.test` resolution required. It speaks just enough SMTP for a dev mailer (`EHLO`,
`MAIL FROM`, `RCPT TO`, `DATA`, `QUIT`); there is **no AUTH and no TLS**, and every
recipient is accepted.

::: info Local only, never relayed
The server is a *sink*, not a relay. A captured message is written to disk and
surfaced for inspection - it is never forwarded to a real mail server, so you can
exercise your app's email flows with zero risk of a stray message reaching a real
person.
:::

::: tip Bind failure is non-fatal
If port `2525` is already in use (another capture tool, say), the daemon logs a
warning and runs with capture *not listening* - your sites are never taken down by
a busy mail port. `yerd status` reports whether the listener actually bound.
:::

## Pointing an app at Yerd

Configure your app's mailer to talk plain SMTP to `127.0.0.1:2525` with no
authentication and no encryption. For a Laravel app, that's a four-line change to
`.env`:

```ini
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_ENCRYPTION=null
# No MAIL_USERNAME / MAIL_PASSWORD - the capture server has no auth.
```

Send a mail (a password reset, `php artisan tinker` + `Mail::raw(...)`, a queued
job) and it's captured immediately. Any framework or language works the same way -
anything that can send SMTP to a loopback port with no auth and no TLS.

::: warning Don't point production at it
This is a development convenience with no authentication and no transport
security. It binds loopback only and is not meant to be reachable from a network.
Keep these settings to your local `.env`.
:::

## Reading captured mail from the CLI

Three subcommands cover the common loop. See the
[Mail CLI reference](../reference/cli/mail) for the precise output shapes.

```sh
yerd mail list
# ID      FROM                        SUBJECT
# 000003  Example <hi@example.com>    Password Reset
# 000002  shop@acme.test              Your order shipped
# 000001  no-reply@acme.test          Welcome
```

`yerd mail list` prints a newest-first table of `ID`, `FROM`, and `SUBJECT`. Pass
an id to `yerd mail show` to read one message:

```sh
yerd mail show 000003
# From:    Example <hi@example.com>
# To:      you@app.test
# Subject: Password Reset
#
# Your OTP is 416063.
```

`show` prints the headers and the **text body**. A message that carries only an
HTML body (no plain-text part) shows a short note pointing you at the GUI viewer,
which can render it. `yerd mail clear` deletes every captured email.

::: tip Machine-readable output
Like every `yerd` command, the mail commands accept the global `--json` flag for
scripting: `yerd mail list --json` emits the captured-email metadata as JSON, and
`yerd mail show <id> --json` emits the full decoded message (headers and both
bodies).
:::

## The viewer

The standalone **Mails** viewer window - opened from the [desktop app](./desktop-app)
with **Show Mails** - decodes each message for you: headers, the plain-text body,
and a rendered **HTML** body. From the GUI you can read, delete individual
messages, clear everything, open **file attachments**, and follow **http(s) /
mailto / tel** links in both HTML and plain-text bodies (they open in your OS
browser / handler).

The HTML body is sanitized with **DOMPurify** and rendered in a **Shadow DOM**
in the Mails window (so link clicks work reliably on macOS WKWebView). Openable
`http(s)` / `mailto` / `tel` links are stamped and opened via the OS browser /
handler. Inline images referenced by `cid:` are embedded as `data:` URLs.
Remote images and stylesheets (e.g. a logo served over `https://`) are **blocked
by default** so merely opening a message cannot phone home. The right sidebar
lists those URLs under **Remote content**; use **Load remote content** when you
want them. Non-inline attachments appear in a bar under the body and open with
the OS default app.

## Configuration

Mail-capture settings live in your [config file](../reference/configuration) under
a `[mail]` table:

```toml
[mail]
enabled = true
port = 2525
```

Both keys default (enabled, port `2525`), so a config written before mail capture
existed still works - and a default install emits no `[mail]` table at all. You
normally don't hand-edit this; drive it through the [desktop app](./desktop-app),
which keeps the config in sync.

::: warning Changes apply on the next daemon restart
Changing the port or toggling capture on/off is saved immediately but takes effect
on the **next daemon start/restart** - there's no hot rebind. Run
`yerd restart daemon` to apply a change right away.
:::

Captured mail is stored under the daemon's data directory at `<data>/mail`, one
`.eml` file per message plus an `index.json` metadata cache. The store keeps a
bounded number of recent messages (the oldest are evicted past the cap) and is
always available - already-captured mail stays listable and clearable even when
capture is turned off.

## See also

* [Mail CLI reference](../reference/cli/mail) - `list`, `show`, `clear` in detail
* [The Desktop App](./desktop-app) - where the Mail view and Mails viewer live
* [Configuration Reference](../reference/configuration) - the `[mail]` table
* [The Daemon](./daemon) - how `yerdd` binds the capture server
* Developer deep-dive: [yerd-mail](../developer/crates/yerd-mail)

---

---
url: 'https://yerd.app/guide/laravel-dumps.md'
---
# Laravel Dumps

Yerd can capture live **Laravel telemetry** - `dump()` / `dd()` output, database
queries, queue jobs, rendered views, incoming requests, log writes, cache events,
and outgoing HTTP calls - and stream it into a dedicated viewer in the
[desktop app](./desktop-app), Herd-style. You see what your app is doing without
sprinkling `dd()` everywhere or tailing log files.

Capture works through a native PHP extension (`yerd-dump`) that observes your app
at the engine level, so **your application needs no changes** - no
`composer require`, no service provider, no `auto_prepend_file`.

::: info Off by default
Dump capture is **disabled by default**. Nothing is downloaded, loaded, or
listening until you turn it on. See [Enabling it](#enabling-it) below.
:::

::: tip Requires a Laravel app (mostly)
Most categories - jobs, views, requests, logs, cache - are Laravel-specific.
Dumps and database queries are framework-agnostic (queries are observed at the
`PDO` level), so a plain PHP app still gets those. The richest experience is a
Laravel app served through Yerd as a `.test` site.
:::

## In the desktop app

The fastest way to use Dumps is from the [desktop app](./desktop-app). Open the
**Dumps** page under the **Developer** group in the side navigation.

* **Dump-server status** shows whether the loopback capture server is running.
* The **Enable interception** toggle turns capture on. The first enable
  downloads the extension and restarts your pools; after that it is instant.
* The **per-signal switches** - dumps/dd, queries, jobs, views, requests, logs,
  cache, and outgoing HTTP - are **disabled until interception is on**. Once it
  is, flip each signal independently to keep the viewer focused.
* The **port** (default `2304`) is shown and editable, and the page lists the
  **per-PHP-version extension presence** so you can see which installed PHP
  versions have a matching `yerd-dump` build.
* **Show Dumps** opens the standalone viewer window where captured events
  stream in, grouped by request.

## What you get

Captured events are grouped into categories, one per tab in the viewer:

| Category | What it captures |
|---|---|
| **Dumps** | `dump()`, `dd()`, `ddd()` calls (rendered HTML + plain-text fallback) |
| **Queries** | Eloquent / PDO database queries, with SQL, bindings, and timing |
| **Jobs** | Dispatched queue jobs and their outcome (processing / processed / failed) |
| **Views** | Rendered Blade views and their bound data keys |
| **Requests** | A summary of each incoming HTTP request (method, URI, status, duration) |
| **Logs** | Log writes, with level and context |
| **Cache** | Cache hits, misses, writes, and forgets |
| **HTTP** | Outgoing HTTP client calls (curl / Guzzle / PSR-18) |

Events are grouped **by request**, so you can see everything a single page load
or job did together.

## Enabling it

Turn capture on from the **Dumps** view in the desktop app (in the side
navigation). Enabling it does two things:

1. **Downloads the native extension.** Yerd fetches the matching `yerd-dump`
   extension for **each installed PHP version** from the
   [`forjedio/yerd-php-ext`](https://github.com/forjedio/yerd-php-ext) releases,
   verifies it by SHA-256, and stores it alongside your PHP installs at
   `{data}/php-ext/php-<version>/yerd-dump.so`.
2. **Restarts your PHP-FPM pools** so they load the extension.

After that, dumps flow into the viewer as you exercise your app.

::: info Needs a matching released build
The extension is ABI-specific: there is one build per PHP minor, per OS, per
architecture. If a build for your exact PHP version and platform hasn't been
published yet, Yerd quietly skips that version - capture simply won't work for it
until a matching `.so` ships. The Dumps view shows, per installed PHP version,
whether a matching extension is present.

The download is **best-effort**: a network or verification failure is logged and
leaves your sites running normally, just without capture.
:::

::: warning No dumps on legacy PHP
[Legacy PHP versions](./php-versions#legacy-php-versions) (7.4 / 8.0 / 8.1) never
capture dumps - the `yerd-dump` extension isn't built for out-of-support PHP. The
Dumps view flags legacy rows as **"Unsupported (no dumps)"** and shows a warning
banner when a legacy version is installed.
:::

::: tip Toggling is cheap after the first enable
The extension reads a small state file at the start of every request and
self-disables when capture is off, so turning capture (or an individual category)
on and off again does **not** restart PHP. Only the first enable - which has to
download the extension and load it - restarts your pools.
:::

## Per-category toggles

Each category can be turned on or off independently from the Dumps view. This is
useful when one category is noisy (lots of queries on a busy page) or when you
only care about one signal.

The **outgoing HTTP** category is **off by default** even when capture is enabled

* it carries a little extra overhead and is less commonly needed. The other seven
  categories are on by default. Toggling a category takes effect on the next
  request, with no restart.

## Persisting across requests

By default the viewer shows a **rolling window of the most recent requests** and
clears older ones as new requests arrive, so you're looking at what just
happened. Turn on **persist** to keep events accumulating across requests
instead, which is handy when you're watching a sequence of requests (a queue
worker chewing through jobs, say) and don't want earlier ones to disappear.

The viewer holds a bounded buffer of the most recent events, so very old events
are eventually evicted either way.

## The Dumps window

The desktop app gives Dumps its own space:

* **The Dumps view** lives in the main window (in the side navigation), where you
  enable capture, manage the per-category toggles and persist option, and browse
  captured events by tab.
* **A standalone Dumps window** can be popped out so you can keep dumps visible
  next to your editor and browser while the rest of the app stays out of the way.

You can filter by category (the tabs), clear the buffer, and remove individual
events.

## How it works

When capture is enabled, Yerd's [daemon](./daemon) runs a small TCP server bound
to loopback (`127.0.0.1`) on a configurable port (default **2304**). The
`yerd-dump` extension - loaded into each PHP-FPM pool - opens a connection per
request and streams one compact JSON frame per event. The daemon buffers those
frames in memory and serves them to the desktop app.

Everything stays on your machine: the server binds loopback only, and if the port
is already in use the daemon logs it and retries rather than failing - capture is
never allowed to take your sites down.

::: info No CLI commands
Dumps is driven entirely from the desktop app. There are no `yerd` CLI
subcommands for it. Its settings are stored in your
[config file](../reference/configuration) under a `[dumps]` table (`enabled`,
`port`, `persist`, and per-feature toggles), which the app keeps in sync.
:::

## See also

* [PHP Versions](./php-versions) - the FPM pools the extension loads into.
* [The Desktop App](./desktop-app) - where the Dumps view and window live.
* [Configuration Reference](../reference/configuration) - the `[dumps]` table on disk.

---

---
url: 'https://yerd.app/guide/ai-agents.md'
---
# AI Agents

Yerd ships an [MCP](https://modelcontextprotocol.io) server, so AI coding agents
— Claude Code, Cursor, VS Code Copilot, and anything else that speaks the
protocol — can drive your local environment directly: list and create sites, set
PHP versions, wire up proxies, create databases, and read the mail and dumps your
apps produce.

It is **off by default**. Nothing is exposed until you turn it on.

## Enable it

Open Yerd → **Settings** → **General** → **AI Agents (MCP)** and turn on
**Enable Yerd's MCP server**.

The switch writes `mcp_enabled` to your config; Yerd's daemon does not run a
server for it. Each agent session runs a short-lived `yerd mcp` process that
reads the setting and serves tools over its own stdin/stdout.

That means:

* **Turning it on** reaches agent sessions that are already running — their next
  tool call goes through. No restart needed.
* **Turning it off** applies to sessions started afterwards. A session already
  using Yerd keeps working until it restarts.

::: warning Not a security boundary
The toggle is a convenience control, not a sandbox. Any program running as your
user can already talk to Yerd's daemon through its socket — that is how the
`yerd` CLI works. Turning this off stops agents from *discovering* Yerd's tools;
it does not isolate Yerd from local software.
:::

## Register Yerd with your agent

You only do this once. The `yerd` binary must be on your `PATH` — on macOS use
Settings → General → **Terminal CLI** → Install to put it there.

For Claude Code:

```sh
claude mcp add --scope user yerd -- yerd mcp
```

For agents that use a JSON config file (Cursor, VS Code, and most others):

```json
{
  "mcpServers": {
    "yerd": {
      "command": "yerd",
      "args": ["mcp"]
    }
  }
}
```

The GUI card shows both, with a copy button, once the server is enabled.

To check it worked in Claude Code, run `/mcp` — `yerd` should be listed as
connected, with its tools available.

## What agents can do

| Area | Tools |
| --- | --- |
| Sites | `list_sites`, `create_site`, `link_site`, `park_directory`, `list_parked`, `set_site_php`, `set_site_secure` |
| Domains | `add_domain`, `remove_domain` |
| Proxies | `add_proxy`, `remove_proxy`, `add_proxy_rule`, `remove_proxy_rule`, `list_proxies` (upstreams must be local) |
| PHP | `list_php`, `list_available_php`, `install_php`, `set_default_php`, `set_php_setting` |
| Services | `list_services`, `list_databases`, `create_database` |
| Mail | `set_mail_enabled`, `list_mails`, `get_mail` |
| Dumps | `set_dumps_enabled`, `dumps_status`, `list_dumps` |
| Health | `status`, `diagnose`, `job_status` |

### What agents cannot do

There are **no destructive tools**. An agent can create and configure, but it
cannot drop a database, uninstall PHP or a service, unlink or unpark a site,
clear your captured mail or dumps, or share a site publicly through a tunnel.

**Nothing an agent can do sends your data off the machine.** Proxy upstreams are
restricted to this machine (`localhost`, `127.0.0.0/8`, `::1`), even though
`yerd proxy add` itself accepts any host. A proxy rule pointing a `.test` site at
a remote server would make your browser hand that server the site's cookies and
tokens, over an origin your system already trusts — so an agent may not create
one, for the same reason it may not open a tunnel.

Both limits exist because an agent acts on what it reads, and what it reads can
be wrong or hostile. Use `yerd` or the app for anything on these lists — as a
human, deliberately.

## Long-running work

`create_site` and `install_php` take far longer than a single call, so they start
a background job and return a `job_id` straight away. The agent then polls
`job_status` with that id — passing the `next_cursor` from each poll to get only
new log lines — until `state` reads `succeeded`, `failed`, or `cancelled`. Yerd
tells the agent this in the tool's own description, so it handles the flow
itself.

Jobs are held in memory. If the daemon restarts mid-job, the id is gone: the
agent is told as much and asked to verify the outcome directly (with
`list_sites` or `list_php`) rather than assuming it failed.

## Troubleshooting

**The server shows as connected but every tool says it is disabled.** The toggle
is off. Turn it on in Settings → General; the running session picks it up on its
next call.

**The server fails to start / shows red.** The agent could not run `yerd mcp` —
almost always `yerd` not being on the `PATH` the agent inherits. Install the
Terminal CLI (Settings → General), then restart the agent so it picks up the new
`PATH`.

**Tools report the daemon is not running.** Yerd itself is stopped. Open the Yerd
app (or run `yerdd`) and retry.

## See also

* [`yerd mcp`](../reference/cli/mcp) - the command reference and its stdio contract.
* [Mail Capture](./mail) and [Laravel Dumps](./laravel-dumps) - the features
  behind the mail and dump tools.
* [The Daemon](./daemon) - what agents are actually talking to.

---

---
url: 'https://yerd.app/guide/sharing.md'
---
# Sharing Sites

Yerd can **publish a local site to the public internet** over a secure HTTPS URL,
so you can share work in progress, test a webhook, or demo from your own machine
without deploying anything. It works through [Cloudflare
Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
(`cloudflared`): the connection is **outbound-only** - no inbound ports, no
router config, no `sudo` - which fits Yerd's rootless model.

Sharing is opt-in and per-site. A site is never reachable from the internet until
you explicitly share it.

There are two tiers, and you can use either:

* **Quick share** - one click gives you a random `https://<name>.trycloudflare.com`
  URL. No Cloudflare account, no config, nothing to set up. Best for a quick
  demo or a one-off webhook test.
* **Named tunnels** - a stable hostname on **your own** Cloudflare-managed domain
  (e.g. `app.example.com`), backed by a tunnel on your account. Best when you
  want a URL that doesn't change.

::: warning Anyone with the URL can reach your site
Sharing serves your local site as-is. While a tunnel is up, anyone who has the
URL can load it - there's no auth in front. Stop the tunnel when you're done.
Quick-tunnel URLs are unguessable but public; named hostnames are whatever you
choose.
:::

## Prerequisite: cloudflared

Sharing needs the `cloudflared` binary. If one is already on your `PATH` (version
2023.3.0 or newer), Yerd detects and uses it automatically - nothing to install.
Otherwise Yerd **downloads it on demand** (the official Apache-2.0 static build,
verified by checksum) and installs it under the daemon's data directory - it
isn't bundled, and it never touches your system unless you already had one. No
Cloudflare account is required for quick share.

```sh
yerd tunnel install
```

In the desktop app, the **Share** page offers an **Install cloudflared** button
the first time you visit. If Yerd is using a `cloudflared` it found on your
`PATH`, the badge is annotated `(system)` and a **Use Yerd's bundled version
instead** button lets you switch to the managed, auto-updating copy.

## Quick share

The fastest way to put a site online:

```sh
yerd tunnel share app        # -> https://calm-river-1234.trycloudflare.com
yerd tunnel status           # see live tunnels and their URLs
yerd tunnel stop app         # take it back offline
```

Yerd points `cloudflared` at the site's own loopback listener and rewrites the
`Host` header to the site's `.test` name, so the request routes through the same
proxy that serves the site locally - a secure (HTTPS) site is served over HTTPS,
a plain site over HTTP, transparently. You don't configure any of that.

Quick tunnels are **ephemeral**: the URL changes every time you start one, and
they're torn down when you stop them or the daemon exits. They carry Cloudflare's
quick-tunnel limits (around 200 concurrent requests, and no server-sent events),
so they're for development, not production traffic.

::: tip "Server IP address could not be found"?
That's your machine's DNS resolver, not Yerd - some ISP resolvers don't resolve
fresh `*.trycloudflare.com` names. Point your system DNS at `1.1.1.1` or
`8.8.8.8` and the URL resolves immediately.
:::

## Named tunnels

Named tunnels publish a site at a **stable hostname on a domain you already manage
in Cloudflare**. They need a one-time browser login to your Cloudflare account.

Yerd uses a single consolidated tunnel that serves every site you expose (one
process, one config), so you create the tunnel once and then just toggle which
sites are live.

### 1. Connect your Cloudflare account

```sh
yerd tunnel login
```

This opens your browser to authorize Yerd for one of your Cloudflare zones. The
account certificate is stored in the daemon's data directory and never leaves
your machine. After login, Yerd resolves and shows the **authorized domain**
(e.g. `example.com`) so you know which hostnames you can use.

### 2. Create a tunnel

```sh
yerd tunnel create my-tunnel
```

Yerd supports one named tunnel at a time; remove it before creating another.

### 3. Expose a site

Map a site to a public hostname on your authorized domain, then publish:

```sh
yerd tunnel set-host app app.example.com   # route DNS + record the mapping
yerd tunnel publish                        # bring the tunnel up for all exposed sites
yerd tunnel list                           # show the tunnel, exposed sites, and domain
```

`set-host` creates the proxied DNS record on your Cloudflare zone and remembers
the mapping. `publish` starts the consolidated tunnel; `unpublish` stops it.

To stop exposing a site:

```sh
yerd tunnel set-host app --clear           # remove the mapping
```

## In the desktop app

The [desktop app](./desktop-app) has a **Share** page under the **Integrations**
group in the sidebar (also reachable from the command palette). When any site is
shared, the sidebar item shows a count.

* The **Shared sites** card has a searchable site picker and a **Share** button
  for quick tunnels, plus a live table of active tunnels with copy-URL and stop
  controls.

* Each site's `⋯` menu on the [Sites page](./sites) also has a **Share
  publicly…** shortcut that jumps straight to sharing that site, without going
  to the Share page first:

* The **Named tunnels** card walks you through connecting your Cloudflare account,
  creating the tunnel, and choosing which sites to expose. Each site's hostname
  box is pre-filled with `{site}.{your-domain}`. Exposing a site brings the
  tunnel up automatically and removing the last one takes it back down, so you
  rarely touch the lifecycle yourself; a **Start/Restart** button is there to
  recover the tunnel if its `cloudflared` process dies.

## Removing a named tunnel

```sh
yerd tunnel delete my-tunnel
```

This stops the tunnel, deletes it from your Cloudflare account, removes its local
credentials, and clears the exposed-site mappings, leaving a clean slate. The
**DNS records** you created with `set-host`/`route` are *not* removed - delete
those in the Cloudflare dashboard if you no longer want them.

## How it stays safe

* `cloudflared` runs **unprivileged**, as the daemon user. Sharing never invokes
  the privileged helper and never opens a listening port - the tunnel dials out.
* The account certificate and per-tunnel credentials live in a daemon-owned `0700`
  directory; the desktop app never reads them.
* Nothing is shared until you ask, and quick tunnels are torn down on daemon
  shutdown.

## Command reference

See the [`yerd tunnel` CLI reference](../reference/cli/tunnel) for every command
and flag. The persisted mappings live in the `[tunnel]` section of the [config
file](../reference/configuration#tunnel).

---

---
url: 'https://yerd.app/guide/https.md'
---
# HTTPS & Certificates

Yerd gives every `.test` site a real, trusted HTTPS certificate with no manual
work - no OpenSSL, no `mkcert`, no copying `.pem` files around. You trust a
single local certificate authority **once** during setup, and from then on every
site you secure gets a fresh, browser-valid certificate the moment it's needed.

This page explains how that works, how to turn HTTPS on and off per site, and
the small amount of trust you grant during the one-time elevation step.

## The short version

```sh
# One-time: trust Yerd's local CA in your OS trust store (run via sudo).
sudo yerd elevate trust

# Per site: turn HTTPS on, then off.
yerd secure my-app      # -> https://my-app.test  (green padlock)
yerd unsecure my-app    # -> back to http://my-app.test only
```

After `elevate trust`, `https://my-app.test` loads with a valid certificate in
your browser - no warnings, no exceptions to click through.

## How automatic HTTPS works

Yerd's TLS lives in the `yerd-tls` crate, built entirely on pure-Rust libraries:

* **[rcgen](https://github.com/rustls/rcgen)** generates and signs certificates.
* **[rustls](https://github.com/rustls/rustls)** terminates TLS in the reverse
  proxy.

There is **no OpenSSL anywhere** in the stack, and no shelling out to `mkcert`.
Certificate issuance is a library call, not an external process.

There are two layers of certificates:

```mermaid
flowchart TD
    CA["Yerd Local CA<br/>(self-signed root, trusted once)"] -->|signs| Leaf["per-site leaf certificate<br/>(e.g. my-app.test)"]
    Leaf -->|served by| Proxy["rustls reverse proxy"]
    Proxy --> Browser["your browser (green padlock)"]
```

### 1. The local certificate authority

When the daemon (`yerdd`) starts for the first time, it generates a single local
CA - a self-signed root certificate named **"Yerd Local CA"** - and stores its
certificate and private key in the daemon's data directory. The key is locked
down to your user account (`0600`), and the public certificate is written
world-readable but not group/world-*writable* so the trust helper can refuse a
tampered file.

A few deliberate properties of this CA:

* It is an **ECDSA P-256** key (pinned explicitly, not left to a library
  default).
* It is marked as a CA with a **path-length constraint of 0**, so it can only
  sign leaf certificates - never intermediate CAs.
* Its validity window is roughly **10 years** from generation.

The CA exposes a stable **SHA-256 fingerprint** over its certificate DER. That
fingerprint is the security boundary used everywhere trust is installed or
checked - the filename on disk and any display value are just human-readable
tags.

::: info One CA, many sites
You never generate a CA per site. There is exactly one CA per machine, and every
site certificate is signed by it. That is why you only trust once.
:::

### 2. Per-site leaf certificates

Yerd does **not** pre-issue certificates for sites you haven't visited. Instead,
the proxy issues a leaf certificate **lazily, on the first HTTPS request** for a
host. The flow inside the daemon's cert store is:

1. A TLS handshake arrives with an SNI hostname (say `my-app.test`).
2. The store checks its in-memory cache. On a hit, it reuses the cached key.
3. On a **miss**, it asks the CA to issue a fresh leaf for that hostname,
   persists the leaf certificate and key as PEM files alongside the CA, parses
   them into a rustls signing key, caches it, and completes the handshake.

SNI hostnames are normalised first (trailing dot stripped, lower-cased), so
`my-app.test`, `MY-APP.TEST` and `my-app.test.` all resolve to the same cached
certificate.

Each leaf is a modern, SAN-only certificate:

* **No Common Name** - identity lives entirely in Subject Alternative Names, the
  way current browsers expect.
* **Extended Key Usage: `serverAuth`**, plus `digitalSignature` and
  `keyEncipherment` key usages.
* An **Authority Key Identifier** linking it back to the CA.
* A short validity window (a little over a year) with a small backdated start to
  tolerate clock skew.
* Its own **freshly generated private key** - leaf keys are never shared with
  the CA or with each other.

### Wildcard SANs

The issuance layer accepts **wildcard DNS names** such as `*.my-app.test` as
Subject Alternative Names, alongside the bare hostname. SAN entries are validated
as `IA5String` (ASCII) DNS names; non-ASCII names are rejected with a clear
error pointing at the offending entry. This is what lets a single certificate
cover a site and its sub-hosts where that's needed. A wildcard leaf is issued
when you register a wildcard domain for a site with
`yerd domain add <site> '*.<site>.test'`.

::: tip Why a leaf per host instead of one big cert
Issuing on demand keeps certificates scoped to exactly the hostnames you
actually use, and means adding a new site never requires re-trusting anything -
the new leaf is already signed by the CA you trusted on day one.
:::

## Trusting the CA (once)

A self-signed CA is not trusted by your OS or browsers until you add it to a
trust store. That single act is the one-time step:

```sh
sudo yerd elevate trust
```

This is the **only** part of HTTPS that needs root, and it's part of the broader
one-time setup. See [Elevation & Privileges](./elevation) for the full picture
of what runs privileged and why.

Under the hood, `yerd elevate trust` doesn't do the privileged work itself.
It asks the daemon for the CA certificate path, verifies that file is owned by
your user and not world-writable, then invokes the small, auditable
**`yerd-helper`** binary to install the CA into the system trust store. The
helper takes typed arguments, never shells out to a shell, never touches the
network, does exactly one thing, and exits.

How the CA lands in the system store depends on the platform:

| Platform | What `yerd-helper` does |
|---|---|
| macOS | `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain` (the same approach `mkcert` uses) |
| Debian / Ubuntu / Alpine | writes to `/usr/local/share/ca-certificates`, then runs `update-ca-certificates` |
| RHEL / Fedora / CentOS | writes to `/etc/pki/ca-trust/source/anchors`, then runs `update-ca-trust extract` |
| Arch | writes to `/etc/ca-certificates/trust-source/anchors`, then runs `trust extract-compat` |

Installation is **idempotent**. On macOS, `security` returns a benign non-zero
code when the certificate is already present; Yerd recognises that case (by
confirming the fingerprint really is in the System keychain) and treats it as
success. A genuine failure - a cancelled auth prompt, a locked keychain - still
surfaces as an error.

### Firefox and other NSS apps

Firefox (and some other tools) **do not use the OS trust store**. They keep
their own NSS certificate database per profile. Yerd handles this separately: it
can install the CA into every discovered NSS database - Firefox profiles plus
`~/.pki/nssdb` - using `certutil`.

This step is **best-effort**:

* If `certutil` is not on your `PATH`, Yerd logs it and carries on rather than
  failing the whole operation. (Install your distro's NSS tools - often
  `libnss3-tools` - to enable Firefox trust.)
* Per-profile results are tracked individually, so one missing database doesn't
  block the others.

::: warning Firefox still warns? Install certutil
If Chrome/Safari are green but Firefox shows a certificate warning, the NSS
install was almost certainly skipped because `certutil` wasn't available. Install
it and re-run the trust step.
:::

## PHP and the local CA

Your browser and shell `curl` trust `.test` HTTPS as soon as you run
`sudo yerd elevate trust`, because they read the OS trust store. The **bundled
PHP is different**: it verifies TLS against its own OpenSSL certificate bundle,
not the system keychain. Without help, a PHP HTTPS call to a secured `.test`
site fails even though the browser is happy:

```php
Http::get('https://site-b.test/api/example');
// cURL error 60: SSL certificate problem: unable to get local issuer certificate
```

Yerd fixes this automatically. On daemon start it writes a managed bundle,
`cacert.pem`, into its data directory - your host's public root certificates
**plus** the Yerd CA - and points the bundled PHP at it via `openssl.cafile` and
`curl.cainfo`, for both FPM (served apps) and the CLI (`artisan`, `tinker`,
`composer`). Laravel's `Http`/Guzzle, `file_get_contents('https://…')`, and curl
all then verify `.test` certificates like the browser does.

::: info Public HTTPS is never sacrificed
The managed bundle always includes your host's public roots, so PHP keeps
verifying real-internet HTTPS (Composer, external APIs). If Yerd can't find any
host roots, it deliberately leaves PHP's default trust store untouched rather
than risk breaking public HTTPS - and `yerd doctor` will flag it.
:::

If a PHP HTTPS call to a `.test` site still fails with `cURL error 60` after a
Yerd upgrade, the daemon most likely hasn't restarted yet (the bundle is written
at start-up). Run `yerd doctor` - it detects a missing or stale bundle and can
rebuild it:

```sh
yerd doctor        # reports "PHP doesn't trust the local CA" if wrong
yerd doctor fix    # rebuilds cacert.pem
```

For direct `php` calls in your shell, make sure Yerd's environment is wired up
with `yerd path install` (this exports `PHPRC` so the CLI reads Yerd's `php.ini`).

## Turning HTTPS on and off per site

HTTPS is a per-site toggle. Both commands take a site **name** (not a URL):

```sh
yerd secure my-app      # serve my-app over HTTPS
yerd unsecure my-app    # stop serving my-app over HTTPS
```

| Command | Effect |
|---|---|
| `yerd secure <site>` | Marks the site as HTTPS-enabled. (For a parked site this promotes it to an explicit linked entry so the flag has somewhere to live.) |
| `yerd unsecure <site>` | Clears the HTTPS flag; the site is served over plain HTTP only. |

Both are ordinary, **unprivileged** commands - they're thin CLI calls that the
daemon applies to its site configuration. You do not need `sudo` to secure or
unsecure a site; the only privileged step is trusting the CA, which you've
already done once.

You can see which sites are secured at a glance:

```sh
yerd sites
```

The site list reports each site's kind, PHP version, doc-root, and whether HTTPS
is on. For a full daemon snapshot - including whether the CA is trusted in your
system store - use:

```sh
yerd status
```

If `yerd status` reports the CA as not trusted, that's your cue to run
`sudo yerd elevate trust`. Yerd's diagnostics will point you there too:

```sh
yerd doctor
```

::: tip Add --json anywhere
Every command accepts `--json` for machine-readable output, handy if you're
scripting site setup or wiring Yerd into CI.
:::

## Removing trust

If you ever want to pull the CA back out of your trust stores, reverse the
elevation:

```sh
sudo yerd unelevate trust
```

This is idempotent too: if the CA's fingerprint isn't found in the system store,
there's simply nothing to remove and the command succeeds quietly.

## See also

* [Elevation & Privileges](./elevation) - the full one-time setup model and the
  `yerd-helper` privilege boundary.
* [Sites](./sites) - parking, linking, and managing the sites you secure.
* [DNS & .test Domains](./dns) - how `*.test` reaches the proxy in the first
  place.
* [CLI Reference](../reference/cli/) - every command and flag.
* Source: [`yerd-tls`](https://github.com/forjedio/yerd/tree/main/crates/yerd-tls)
  and [`yerd-helper`](https://github.com/forjedio/yerd/tree/main/bin/yerd-helper)
  on GitHub.

---

---
url: 'https://yerd.app/guide/dns.md'
---
# DNS & .test Domains

Open `http://blog.test` and something has to turn that name into an address your machine listens on. Yerd handles this with a small embedded DNS resolver that answers for one TLD (`.test` by default), plus a one-time change that points your OS at it.

## The short version

* The `yerdd` daemon runs an embedded DNS server. It answers `*.test` with `127.0.0.1` (`A`) and `::1` (`AAAA`).
* You tell your OS to send `.test` lookups there, once: `sudo yerd elevate resolver`.
* After that it's automatic. Park or link a project and `<name>.test` resolves to loopback, where Yerd's reverse proxy is waiting.

```mermaid
flowchart TD
    B1["browser"] -->|"blog.test?"| OS["OS resolver<br/>(.test routed to Yerd)"]
    OS --> DNS["yerdd embedded DNS"]
    DNS -->|answers| IP["A 127.0.0.1 / AAAA ::1"]
    B2["browser"] -->|HTTP/HTTPS| Proxy["yerdd reverse proxy on 127.0.0.1"]
```

::: tip Why `.test`?
`.test` is reserved (RFC 6761) and can never exist on the public internet, so routing it to your machine can't shadow a real site. The TLD is configurable; see [Configuration Reference](../reference/configuration).
:::

## The embedded resolver

The resolver lives in the `yerd-dns` crate, built on `hickory-dns`. It is authoritative for exactly one zone (your TLD) and nothing else: it never forwards, caches, or touches the network.

| Query | Wire response |
|---|---|
| `app.test`, `A` | `NOERROR`, `A 127.0.0.1` |
| `app.test`, `AAAA` | `NOERROR`, `AAAA ::1` |
| `app.test`, any other qtype (MX, TXT, …) | `NOERROR`, empty answer |
| `test` (bare TLD apex) | `NOERROR`, empty answer |
| malformed in-zone label (`.test`, `app..test`) | authoritative `NXDOMAIN` |
| outside the zone (`app.com`, `testify`) | `REFUSED`, `AA` bit cleared |

Worth knowing:

* Any subdomain depth resolves. `a.b.c.app.test` maps to loopback just like `app.test`, and matching is case-insensitive. Resolving a name to loopback is not the same as a site answering it: routing is the reverse proxy's job, and since v2 a site answers only the domains registered for it, so a name that resolves in DNS may still 404 at the proxy until you attach it with `yerd domain add`.
* Records carry a 60-second TTL (`ANSWER_TTL_SECS`), so resolvers don't cling to stale answers when your setup changes.
* Out-of-zone queries return `REFUSED` with the `AA` bit cleared. If your OS ever misroutes a non-`.test` query here, the cleared bit tells it to ask elsewhere instead of trusting a bogus answer.
* No `SOA` is emitted in the authority section of `NXDOMAIN`/`NODATA` replies.

::: info Read-only by design
The DNS server holds no logic about your sites. It says "that's loopback" for the whole zone; routing to the right project and PHP version happens later in the reverse proxy. See [Sites](./sites) and [The Daemon](./daemon).
:::

### How the daemon binds it

The daemon binds the resolver on `127.0.0.1` at [`dns_port`](../reference/configuration) from `yerd.toml`. The default is **1053** (`DEFAULT_DNS_PORT`): not the mDNS-contended `5353`, and not privileged `53`, so the unprivileged daemon can bind it.

UDP and TCP both bind on the same address. Set `dns_port = 0` and the kernel picks an ephemeral port, retrying until UDP and TCP match. A fixed port is better, though, since the resolver config your OS stores hard-codes `127.0.0.1:<port>` and a stable port keeps that file valid across restarts.

::: warning Keep the port stable
If `dns_port` changes (or you used `0`), the config written by `yerd elevate resolver` may point at a port nothing listens on. `yerd doctor` catches this by checking the config against the daemon's current DNS address. Restart Yerd so it binds the configured port, then re-run `sudo yerd elevate resolver`.
:::

::: warning A bind failure is non-fatal
If another process already holds `dns_port`, the daemon does **not** abort - it comes up degraded, with no `*.test` resolution, while the reverse proxy, PHP pools, and IPC server all still work normally. `yerd status` shows `dns       not resolving - couldn't bind port <port> (run yerd doctor)` in place of the bound address, and `yerd doctor` raises a `DnsPortUnbound` warning. Free the port, or change `dns_port` in Settings (Yerd ▸ General), then restart the daemon. See [Diagnostics](./diagnostics).
:::

## Pointing the OS at Yerd

Configuring the OS resolver needs root, so the auditable `yerd-helper` binary does it, once:

```sh
sudo yerd elevate resolver
```

This is one slice of the one-time setup. The full command also does CA trust and port capability:

```sh
sudo yerd elevate            # trust + resolver + ports, in one go
```

Daily use never touches root again. To undo it:

```sh
sudo yerd unelevate resolver
```

On macOS, undo is a **restore**: if a previous resolver was backed up when Yerd took over (see below), `unelevate resolver` puts it back and clears the saved backups; with no backup it removes Yerd's file. On Linux it removes every Yerd-owned resolver snippet, including artifacts from a previously active backend.

Install and uninstall are idempotent: re-installing an already-correct config changes nothing (and writes no backup), and uninstalling something absent succeeds quietly.

See [Elevation & Privileges](./elevation) for the privilege model and the [CLI Reference](../reference/cli/) for every flag.

### Per-platform mechanism

| Platform | Mechanism | File written | Reload |
|---|---|---|---|
| **macOS** | `resolver(5)` per-TLD file | `/etc/resolver/<tld>` | None (read at next query) |
| **Linux** (systemd-resolved) | drop-in config | `/etc/systemd/resolved.conf.d/yerd-<tld>.conf` | `systemctl reload-or-restart systemd-resolved` |
| **Linux** (NetworkManager) | dnsmasq plugin and per-domain route | `/etc/NetworkManager/conf.d/yerd-dnsmasq.conf`, `/etc/NetworkManager/dnsmasq.d/yerd-<tld>.conf` | `nmcli general reload conf dns-full` |
| **Linux** (other resolver) | refused | - | - |
| **Windows** | NRPT rule | - | *planned* |

#### macOS

Yerd writes a file named after the TLD (e.g. `/etc/resolver/test`) with two directives:

```text
nameserver 127.0.0.1
port 1053
```

macOS reads it at the next query, so there's nothing to reload.

If a file already exists there (a leftover from Valet, Herd, or older Yerd) and doesn't point at Yerd, the helper backs it up before overwriting. Backups land in `/Library/Application Support/io.yerd.Yerd/resolver-backups/` as `<tld>-<unix-seconds>.conf`, and `yerd doctor` reports the most recent. An already-correct file is left alone.

`sudo yerd unelevate resolver` reverses this: it restores the most recent backup over `/etc/resolver/<tld>`, then deletes the saved backups. The restore is guarded - the helper only writes back a backup that is root-owned, not a symlink, and parses as a valid resolver file - so a tampered or junk backup is skipped in favour of a plain removal.

::: tip The `port` line is load-bearing
A bare `nameserver 127.0.0.1` (what Valet/Herd leave) defaults to port `53`, where nothing of Yerd's listens. The `is_installed` probe requires both nameserver and port to match the live daemon, so a stale file reads as "not installed" and gets rewritten on the next elevate.
:::

#### Linux - systemd-resolved drop-in

On systemd-resolved systems Yerd writes `/etc/systemd/resolved.conf.d/yerd-<tld>.conf`:

```ini
[Resolve]
DNS=127.0.0.1:1053
Domains=~test
```

The `~` prefix is systemd's routing-only marker: use this server only for names under `test`, without making Yerd the global resolver. The helper then runs:

```sh
systemctl reload-or-restart systemd-resolved
```

Detection is conservative. Yerd treats systemd-resolved as in charge only if `/run/systemd/resolve` exists, or `/etc/resolv.conf` carries the `systemd-resolved` marker in its first few lines.

The resolved probe preserves its established shape-based contract: a well-formed route for the configured TLD counts as installed. The NetworkManager probe strictly verifies its TLD, address, and port snippets.

#### Linux - NetworkManager with dnsmasq

When resolved is absent and NetworkManager is detected, Yerd writes a `[main] dns=dnsmasq` override and a narrow rule such as `server=/test/127.0.0.1#1053`. The `dnsmasq` and `nmcli` executables must already be installed; Yerd does not install system packages. After the DNS-only reload, Yerd polls for up to five seconds until NetworkManager's local resolver answers a `.test` probe, while ordinary and VPN upstream DNS continue through NetworkManager.

If reload fails, the helper restores both previous snippets and attempts to reload the prior configuration. Unelevation removes both Yerd-owned files, restoring NetworkManager's prior DNS mode. Other resolver managers remain unsupported; Yerd never edits `/etc/resolv.conf` directly because it is commonly regenerated.

#### Windows - NRPT (planned)

Windows is on the [roadmap](./services). The plan routes `.test` via the Name Resolution Policy Table (NRPT), Windows' native per-suffix mechanism, alongside named-pipe IPC and the system certificate store. Not implemented today; on unsupported platforms the resolver operations return an `Unsupported` error.

## Verifying it works

`yerd status` shows the DNS address the daemon bound and whether the OS points at it:

```sh
yerd status
# …
# dns       127.0.0.1:1053
```

When resolution breaks, `yerd doctor` flags it and names the fix (usually `sudo yerd elevate resolver`):

```sh
yerd doctor
yerd doctor fix     # auto-repairs the safe ones
```

You can query the resolver directly. It's authoritative for the whole zone, so any `.test` name returns loopback:

```sh
# Ask Yerd's resolver on its port:
dig @127.0.0.1 -p 1053 anything.test A
#   anything.test.   60   IN   A   127.0.0.1

dig @127.0.0.1 -p 1053 anything.test AAAA
#   anything.test.   60   IN   AAAA   ::1
```

To confirm the OS routes `.test` (not just Yerd's port): on macOS, `dscacheutil -q host -a name app.test` returns `127.0.0.1`; on Linux with systemd-resolved, `resolvectl query app.test` shows the answer from `127.0.0.1:1053`.

## Related

* [HTTPS & Certificates](./https) - trusting the local CA so `.test` sites go green
* [Sites](./sites) - parking and linking projects onto `.test` names
* [Localhost Access](./localhost-access) - reaching sites when `.test` can't be routed
* [Elevation & Privileges](./elevation) - the one-time `sudo` and what it touches
* [The Daemon](./daemon) - how `yerdd` binds and supervises the resolver
* [Configuration Reference](../reference/configuration) - `dns_port` and the TLD
* Developer deep-dive: [yerd-dns](../developer/crates/yerd-dns) and [yerd-platform](../developer/crates/yerd-platform)

Source: [github.com/forjedio/yerd](https://github.com/forjedio/yerd).

---

---
url: 'https://yerd.app/guide/elevation.md'
---
# Elevation & Privileges

Yerd is rootless by design. The daemon (`yerdd`), the CLI (`yerd`), and the desktop app all run as your normal user. Only one step needs administrator rights: a one-time setup that wires Yerd into three OS subsystems your account can't touch on its own. Everything after that (parking sites, switching PHP, securing a site, restarting a pool) runs unprivileged.

## Why elevation is needed

Three things can't be done as an unprivileged user, on any OS:

1. **Trusting the local CA.** Yerd issues per-site certificates from a local CA. For the browser to show a padlock, that CA must go into the root-owned system trust store.
2. **Configuring the system resolver.** Routing `*.test` to Yerd's DNS responder means editing the OS resolver config under `/etc` (`/etc/resolver/<tld>` on macOS, or Yerd-owned systemd-resolved/NetworkManager snippets on Linux).
3. **Binding ports 80 and 443.** These are privileged ports; an unprivileged process can't bind them without help.

Herd and Valet require the same admin steps for the same reasons.

::: tip You don't have to elevate
Skip setup and Yerd still works: it falls back to [rootless ports `8080`/`8443`](#the-rootless-fallback), serving over `http://...:8080` (or you trust the CA yourself). Elevation buys the "just type the URL" experience, not basic functionality.
:::

## The one command

Run this once for the full experience. It's the only Yerd command that uses root:

```sh
sudo yerd elevate
```

With no subcommand, `elevate` does all three steps in order (trust, resolver, ports). Each runs independently, so a failure or skip in one doesn't abort the rest.

You can run one piece at a time:

```sh
sudo yerd elevate trust       # add the local CA to the system trust store
sudo yerd elevate resolver    # route *.test to yerd's DNS responder
sudo yerd elevate ports       # allow the daemon to serve on 80/443
```

Resolver elevation first checks the daemon's DNS health. If Yerd could not bind
its configured DNS port, the command stops before changing OS resolver files and
names the port to free (or change); restart Yerd after correcting it, then retry.

| Target | What it configures |
|---|---|
| `trust` | Adds Yerd's local CA to the OS system trust store. |
| `resolver` | Routes `*.<tld>` (e.g. `*.test`) queries to Yerd's DNS responder. |
| `ports` | Lets the daemon serve on the privileged ports 80/443. |

::: tip Or use the GUI
The desktop app's **Doctor** page mirrors this exactly - a **Fix** button per row
(CA trust, `.test` resolver, privileged ports) runs the same `yerd elevate`
helper under an OS prompt, and once a row is configured an **Unelevate** button
reverts it.
:::

Reverse any of it with `unelevate`, using the same targets:

```sh
sudo yerd unelevate           # revert everything elevate configured
sudo yerd unelevate trust     # remove the CA from the system trust store
sudo yerd unelevate resolver  # restore the prior resolver (macOS) / remove the route
```

::: tip Unelevate restores your previous resolver
On macOS, if `elevate resolver` replaced a pre-existing `/etc/resolver/<tld>` (a Valet/Herd leftover), it saved a backup. `unelevate resolver` **restores that backup** - returning DNS to its pre-Yerd state - and then clears the saved backups; with no backup it just removes Yerd's file. On Linux it removes all Yerd-owned systemd-resolved and NetworkManager snippets. `unelevate ports` is reversible on macOS only (see [Ports](#ports)).
:::

::: tip Removing yerd entirely
`sudo yerd uninstall` runs this same `unelevate` (all three targets) as part of a full removal, then deletes the daemon, config, data, and binaries. Run it **with `sudo`** so the trust/resolver/port changes are reversed - they can't be undone once the `yerd-helper` binary is gone. See the [Uninstall reference](../reference/cli/uninstall).
:::

::: info The helper only removes its own CA
`unelevate trust` (and the full uninstall) ask `yerd-helper` to remove a CA from the system trust store **by fingerprint**. Before deleting, the helper confirms the matched certificate is actually Yerd's (its Subject CN is `Yerd Local CA`) - so a stray or mistaken fingerprint can never make the privileged helper delete an unrelated trusted root. If it can't confirm ownership, it refuses and leaves the cert in place.
:::

::: warning Start the daemon first
`elevate` reads facts from your running daemon over the per-user socket (CA path and fingerprint, TLD, DNS address, rootless ports). If it isn't running you'll see `start the yerd daemon first, then re-run`. Start `yerdd` as your user, then re-run `sudo yerd elevate`.
:::

## What each target does, per OS

The mechanics differ by platform; the intent is identical.

### Trust

The CA cert is added to the system store, then the store is refreshed:

* **macOS:** added to `/Library/Keychains/System.keychain` as a trusted root (`security add-trusted-cert ... -r trustRoot`).
* **Linux:** copied into the distro's anchor directory and the store is rebuilt:
  * `/usr/local/share/ca-certificates` then `update-ca-certificates` (Debian/Ubuntu)
  * `/etc/pki/ca-trust/source/anchors` then `update-ca-trust extract` (RHEL/Fedora)
  * `/etc/ca-certificates/trust-source/anchors` then `trust extract-compat` (Arch)

`elevate trust` then also updates your **browsers**. On Linux (and for Firefox
on macOS), Chromium-family browsers - Brave, Chrome, Chromium, Edge - and
Firefox keep their **own** per-user certificate store (NSS) and ignore the
system store above, so the system-store step alone is not enough for them. Yerd
adds the CA to `~/.pki/nssdb` (shared by Chromium-family) and to each Firefox
profile, including Snap and Flatpak copies. This runs unprivileged as your user,
so the browser stores stay user-owned.

::: warning Browsers need `certutil`
Updating the browser stores requires `certutil`, which is **not installed by
default** on many distros. If Yerd reports it missing (and `yerd doctor` warns
`CaNotTrustedByBrowsers`), install it and re-run `sudo yerd elevate trust`:

* Debian/Ubuntu/Zorin: `sudo apt install libnss3-tools`
* Fedora: `sudo dnf install nss-tools`
* Arch: `sudo pacman -S nss`
* macOS (only needed for Firefox; Safari/Chrome/Brave use the keychain): `brew install nss`

A newly installed browser that has never been launched has no store yet; launch
it once, then re-run `sudo yerd elevate trust`.
:::

See [HTTPS & Certificates](./https) for how the CA and leaf certs are generated.

### Resolver

* **macOS:** writes `/etc/resolver/<tld>` pointing at Yerd's DNS address, picked up at the next query (no restart). An existing file is backed up first, and `unelevate resolver` restores that backup.
* **Linux:** prefers a `systemd-resolved` drop-in. When `/etc/resolv.conf` positively identifies NetworkManager as its generator, Yerd can instead enable NetworkManager's dnsmasq plugin and add a per-TLD forwarding rule; this requires `dnsmasq` and `nmcli`. Other resolver arrangements are skipped, and Yerd never edits `/etc/resolv.conf` directly.

See [DNS & .test Domains](./dns) for the resolution model.

### Ports

The platforms diverge most here.

* **Linux:** grants `cap_net_bind_service=+ep` on the `yerdd` binary (`setcap`). The unprivileged daemon can then bind 80/443 directly. Restart the daemon (as your user) for it to take effect.

  ::: warning setcap is reset by upgrades
  The capability lives on the binary file, so replacing that file (a package upgrade) clears it. The Linux packages re-apply it on every upgrade (the `.deb`'s post-install and the Arch package's `.install` scriptlet); other install methods need `sudo yerd elevate ports` again after upgrading. There's no clean reverse, so `sudo yerd unelevate ports` only prints the manual command (`sudo setcap -r <path-to-yerdd>`).
  :::

* **macOS:** no `setcap`. The helper installs a `pf` redirect (`rdr`) mapping `80 -> http_port` and `443 -> https_port`, the rootless ports the daemon already bound. The daemon keeps its high ports; pf forwards the privileged ones. A `LaunchDaemon` re-applies the redirect at boot. It's live immediately (no restart) and fully reversible via `sudo yerd unelevate ports`. The daemon also polls for the redirect every few seconds, so a secure site's `http://` → `https://` redirect drops the `:8443`-style port from the URL shortly after you elevate (and brings it back if you `unelevate`) - no restart needed for that either.

## The rootless fallback

If you never run `elevate ports` (or it can't apply), the daemon falls back to high ports. When binding the desired pair fails with a recoverable error (`PermissionDenied`, `AddrInUse`, or `AddrNotAvailable`), it drops any partial listener and retries on the fallback:

| Service | Privileged | Rootless fallback |
|---|---|---|
| HTTP | 80 | 8080 |
| HTTPS | 443 | 8443 |

So without elevation you can reach sites at `http://my-app.test:8080` - **if** the resolver is installed.

::: tip Can't install the resolver at all?
If you have no admin rights to route `.test`, those names won't resolve anywhere. Yerd still serves every site through plain `localhost` - open `http://localhost:8080/~my-app.test`, or just `http://localhost:8080/` and pick from the list. See [Localhost Access](./localhost-access) for the full story (the `/~` switch, the picker, the `X-Yerd-Site` API header, and the caveats).
:::

Run [`yerd doctor`](./diagnostics) to see which ports are live and what to do.

::: warning If even the fallback can't bind
Rare, but possible if something else already holds the rootless ports too: the daemon comes up with no web listener at all. `yerd status` reports "not serving" for both ports, and `yerd doctor` raises a hard `WebPortsUnbound` failure. In this state `sudo yerd elevate ports` **refuses** on macOS - a `pf` redirect needs a live bound port to point at, and there isn't one. Free a port, or change the fallback pair in Settings (Yerd ▸ General), then restart the daemon before elevating. See [Diagnostics](./diagnostics).
:::

::: info macOS port status
The macOS daemon always binds its high ports (pf does the 80/443 forwarding), so Yerd probes reachability rather than trusting that a config file exists. The probe also **confirms it reaches Yerd's own proxy** - it speaks HTTP to `127.0.0.1:80` and checks for the proxy's `Server: yerd` marker - so a redirect you've torn down (or a foreign web server squatting the port) is correctly reported as *not* redirected. If something that isn't Yerd holds 80/443, `doctor` raises a [`ForeignWebListener`](./diagnostics) warning.
:::

## The security model

Elevation is tiny and tightly bounded. Yerd splits into three binaries with different privilege:

```mermaid
flowchart LR
    CLI["yerd (CLI, your user)"] -->|IPC socket| D["yerdd (daemon, your user)"]
    Elev["sudo yerd elevate"] -->|"spawns, once per target"| H["yerd-helper (root, one-shot)"]
```

* **`yerdd`** owns all runtime state, the proxy, DNS, and PHP-FPM pools. Never runs as root.
* **`yerd`** is a thin client. Under `sudo yerd elevate` it runs as root only to orchestrate; it never does the privileged operation itself.
* **`yerd-helper`** is a strict one-shot binary. Each invocation does exactly one validated operation and exits with a `sysexits.h`-style code.

The desktop app is also just a daemon client and never runs as root; its "Fix" actions shell out to `sudo yerd elevate ...` like you would, and the matching **Unelevate** buttons shell out to `sudo yerd unelevate ...` (behind an in-app confirm and the OS prompt). See [Features](./desktop-app).

### What makes `yerd-helper` safe

The helper trusts no caller, not even the daemon:

* **Effective-UID gate.** Refuses to run unless its effective UID is 0 (Linux reads `/proc/self/status`; macOS shells out to `/usr/bin/id` by absolute path). If `/proc` is missing it reports "not root" rather than assuming privilege.
* **Frozen, typed argv contract.** The CLI hands it one typed operation (`install-ca`, `uninstall-ca`, `install-resolver`, `uninstall-resolver`, `setcap`, `install-port-redirect`, `uninstall-port-redirect`), nothing else.
* **Re-validation.** Every argument is re-parsed before any side effect: paths must be absolute and existing, the TLD goes through `yerd-core`'s `Tld` type, and `setcap` is refused on any binary whose basename isn't `yerdd`.
* **Fingerprint-pinned CA install.** The helper reads the PEM, requires exactly one `CERTIFICATE` block, and verifies its SHA-256 matches the fingerprint passed on argv. This blocks swapping in a different PEM.
* **Hardened subprocesses.** Any tool it runs (`security`, `pfctl`, `update-ca-certificates`, `systemctl`, ...) is spawned with `env_clear()` and a pinned `PATH` (`/usr/sbin:/usr/bin:/sbin:/bin`), with the working directory set to `/`. It never touches the network.
* **Atomic writes.** Files are written to a temp sibling, `fsync`'d, and `rename(2)`'d into place with the mode set at creation, so there's no create-then-chmod race.

On the orchestration side, `sudo yerd elevate` adds two guards:

* It derives the `yerd-helper` and `yerdd` paths from its own trusted `current_exe` siblings, never from anything the daemon says, so a forged daemon can't aim root's `setcap` at an arbitrary binary.
* Before trusting the daemon's CA path, it checks the path is owned by the invoking user (via `SUDO_UID`) and not group/world-writable.

::: tip Reading the source
See [`bin/yerd/src/elevate.rs`](https://github.com/forjedio/yerd/blob/main/bin/yerd/src/elevate.rs) and the helper under [`bin/yerd-helper/src`](https://github.com/forjedio/yerd/tree/main/bin/yerd-helper/src). For the developer breakdown see [yerd-helper (privileged)](../developer/binaries/yerd-helper) and the [Cross-Platform Model](../developer/cross-platform).
:::

## Reading the output

`elevate` narrates each step. A full run looks like:

```
==> trust: trusting the local CA in the system store
    ok
==> resolver: routing *.test → 127.0.0.1:1053
    ok
==> ports: granting cap_net_bind_service to yerdd
    ok
    restart the yerd daemon (as your user) for 80/443 to take effect.
```

Outcomes:

* **`ok`** - succeeded (operations are idempotent, so re-running is safe).
* **`skipped (unsupported on this host)`** - the target doesn't apply here (e.g. `resolver` on Linux without a positively detected supported manager). The run continues.
* **`failed: ...`** - a real error; that target's exit status is reported and the command exits non-zero, but the other targets still run.

## See also

* [HTTPS & Certificates](./https) - the local CA and per-site certificates
* [DNS & .test Domains](./dns) - how `*.test` resolution works
* [Diagnostics](./diagnostics) - `yerd doctor` and what it checks
* [CLI Reference](../reference/cli/) - full `elevate` / `unelevate` grammar
* [yerd-helper (privileged)](../developer/binaries/yerd-helper) - the helper internals

---

---
url: 'https://yerd.app/guide/localhost-access.md'
---
# Localhost Access

Yerd's "just type `app.test`" experience needs the OS resolver routed to its DNS (`sudo yerd elevate resolver`). On a locked-down machine where you **can't** do that, `*.test` names don't resolve at all - so normally you'd be stuck.

This page is the way out. Yerd serves **every** site through plain `http://localhost`, and lets you pick which one, so you can keep working without any admin rights.

## The short version

* `*.test` not resolving? Open **`http://localhost:8080/~app.test`** - Yerd pins that origin to `app.test` and you're in.
* No URL in mind? Open **`http://localhost:8080/`** and pick a site from the list.
* Pinned to the wrong site? Open **`http://localhost:8080/~`** to clear the pin and see the picker again.
* Scripting against it? Send **`X-Yerd-Site: app.test`** and skip the cookie dance.
* It's **HTTP-only** and **one site per browser at a time** (see [the caveats](#the-caveats)).

::: tip This is the fallback, not the default
If you can install the resolver, do - the `.test` experience is nicer. This page is for when you genuinely can't. (`8080` is the *rootless HTTP port*; it's the default but [configurable](../reference/configuration), so substitute your real port throughout.)
:::

## Why you'd need it

Reaching `app.test` takes two OS-level changes, both needing `sudo` once: routing `.test` to Yerd's DNS, and (optionally) binding ports 80/443. See [Elevation & Privileges](./elevation). If you can't run `sudo yerd elevate resolver` - a managed laptop, a CI box, a container - then:

* The browser can't resolve `app.test`, so the URL bar is a dead end.
* But the daemon's proxy **is** listening on `127.0.0.1:8080` (the [rootless port](./elevation#the-rootless-fallback)).
* A request to `http://localhost:8080` arrives with `Host: localhost`, which matches no site - so Yerd needs another way to know *which* site you mean.

That "another way" is the three mechanisms below.

## Three ways to reach a site

### 1. The `/~` switch URL (recommended)

Open:

```
http://localhost:8080/~app.test
```

Yerd recognises the `/~<domain>` prefix, **pins** the `localhost:8080` origin to `app.test` (with a cookie), and redirects you to `/`. From then on every `http://localhost:8080/...` request is served by `app.test` - including the app's own absolute links and assets (`/css/app.css`, `redirect('/dashboard')`), because the browser origin genuinely *is* `localhost:8080`.

To **switch** to another site, just open its `/~` URL (`http://localhost:8080/~blog.test`); the pin moves. A path after the domain is preserved through the redirect, so `…/~app.test/orders/42` lands you on `/orders/42` of `app.test`.

```mermaid
sequenceDiagram
    participant B as Browser
    participant P as yerdd proxy (127.0.0.1:8080)
    B->>P: GET /~app.test/orders/42
    P-->>B: 303 → /orders/42  (Set-Cookie: yerd-site=app)
    B->>P: GET /orders/42  (Cookie: yerd-site=app)
    P-->>B: 200  (served by app.test)
```

A **bare label** works too: `http://localhost:8080/~app` pins `app` just like `/~app.test`.

**Back to the picker:** open `http://localhost:8080/~` (no domain) to clear the pin and get redirected to `/`, which shows the picker again.

### 2. The site picker

Don't remember the name? Open the bare origin (or any path) in a browser:

```
http://localhost:8080/
```

With no site pinned yet, Yerd returns a small **picker page** listing your sites. Click one and Yerd pins it and forwards you to the path you originally requested. The picker is a normal browser page - it only appears for navigations (HTML requests), so it never interferes with assets or API calls.

### 3. The `X-Yerd-Site` header (for API clients)

Scripts and API clients shouldn't have to follow redirects and carry cookies. Send a header instead:

```sh
curl -H 'X-Yerd-Site: app.test' http://localhost:8080/api/orders
```

That request - and only that request - is served by `app.test`. No redirect, no cookie, no state. A bare label (`X-Yerd-Site: app`) and the dash-free alias `X-Yerdsite` both work.

## In the desktop app & CLI

You rarely type these URLs by hand. When the resolver isn't installed, Yerd surfaces the right links automatically:

* The **desktop app** "Open" buttons (Sites, Overview, and the create-site wizard) point at `http://localhost:8080/~<name>.test` instead of `https://<name>.test`, and their tooltips note the http-only caveat.
* **`yerd status`** prints a hint line: `reach sites at http://localhost:8080/~<name>.test`.

So the buttons just work; the mechanics above are for when you're driving it by hand or from a script.

## The caveats

::: warning HTTP-only
There's no TLS certificate for `localhost` (Yerd's certs are per-`.test`-site), so this path is plain `http://` only. The proxy won't redirect a secured site to HTTPS here.

Apps that **pin their own scheme or host** can still misbehave:

* `URL::forceScheme('https')` or forced-HTTPS middleware will bounce you to an `https://localhost` that isn't listening.
* A fixed `APP_URL=http://app.test` (used for URL generation, emails, etc.) or absolute URLs stored in a database (WordPress) will point away from `localhost`.

The fix is to point those at the localhost origin (e.g. `APP_URL=http://localhost:8080`) for the duration, or install the resolver.
:::

::: warning One site per browser at a time
The pin is a cookie on the `localhost` origin, so a browser serves **one** pinned site at a time. Switching is one click (another `/~` link or the picker); `http://localhost:8080/~` clears the pin outright and sends you back to the picker. Different sites simultaneously means different browsers/profiles - or installing the resolver. API clients using `X-Yerd-Site` aren't affected; each request stands alone.
:::

::: info Nothing serving?
If `yerd doctor` reports the daemon couldn't bind its web ports at all (another process is squatting them), there's no origin to reach and these links won't help - free the port or change Yerd's [configured port](../reference/configuration) first. See [Diagnostics](./diagnostics).
:::

## See also

* [DNS & .test Domains](./dns) - how `.test` resolution works when you *can* elevate
* [Elevation & Privileges](./elevation) - the one-time `sudo` setup and the rootless port fallback
* [HTTPS & Certificates](./https) - why there's no `localhost` cert
* [Diagnostics](./diagnostics) - `yerd doctor` and port status

---

---
url: 'https://yerd.app/guide/daemon.md'
---
# The Daemon

`yerdd` is an unprivileged, per-user background process that owns everything Yerd does at runtime: the reverse proxy that answers `.test` requests, the embedded DNS responder for `*.test`, and the supervised PHP-FPM pools. The `yerd` CLI and the desktop app are thin clients that talk to it over a local socket; they never reimplement its logic.

::: info One source of truth
The daemon owns the config and the live routing table. When you run `yerd link` or `yerd secure`, the CLI sends a request, the daemon validates it, persists it to `yerd.toml`, and swaps its in-memory router. So the CLI and GUI can't disagree. See [Sites](./sites) and the [IPC Protocol](../developer/ipc-protocol).
:::

For internal architecture (task wiring, shutdown channel, lock ordering) see [yerdd internals](../developer/binaries/yerdd).

## What the daemon owns

`yerdd serve` brings up and supervises:

| Subsystem | What it does |
|---|---|
| Reverse proxy | A `hyper` + `tokio-rustls` proxy on the HTTP/HTTPS ports, routing each `.test` host to its site and PHP pool. See [HTTPS & Certificates](./https). |
| DNS responder | A loopback-only resolver answering `*.test`. See [DNS & .test Domains](./dns). |
| PHP-FPM pools | One supervised pool per installed PHP version, started on demand. See [PHP Versions](./php-versions). |
| IPC server | A Unix-socket listener for the CLI and desktop app. See [the desktop app](./desktop-app). |
| Update checker | Polls for newer PHP patch releases every 12 hours, and for newer Yerd releases roughly every 4 hours (checked immediately if stale when the desktop app launches). Notify-only - it never installs anything. |
| Local CA | Loads (or on first run generates) the local certificate authority used to issue per-site certs. |

All of this runs as you, never as root. The only operations needing privilege (trusting the CA, configuring the system resolver, granting the port capability) are handled once by a separate audited helper. See [Elevation & Privileges](./elevation).

## Running the daemon

There's one command: `serve`, which runs in the foreground.

```sh
yerdd serve
```

Two flags:

| Flag | Effect |
|---|---|
| `-v`, `--verbose` | Increase verbosity. `-v` is debug, `-vv` is trace. Repeatable. |
| `-c`, `--config <PATH>` | Use a config file at a custom path instead of the default `yerd.toml`. |

```sh
# Debug logging and a custom config
yerdd serve -v --config ~/my-yerd.toml
```

Running `yerdd` with no subcommand equals `yerdd serve` with defaults.

::: tip You usually don't run yerdd by hand
On a typical install, let the app (or your OS service manager) keep it running (below). The bare `yerdd serve &` form is handy for a from-source run and for debugging, where it binds `8080`/`8443`.
:::

### The CLI does not auto-start it

The `yerd` CLI is a pure client. If the daemon isn't running, commands fail fast instead of silently launching it:

```text
daemon not running - start `yerdd`
```

Start `yerdd` (via your service manager or `yerdd serve &`) before using the CLI. `yerd doctor` also flags a stopped daemon. See [Diagnostics](./diagnostics).

## Autostart

How autostart is wired depends on your platform.

::: tip Starting the daemon from the app is bounded
When the desktop app starts the daemon - at login or via the tray's Start button - it bounds the underlying service call to 15 seconds. A wedged `launchctl` or `systemctl` call can't hang the app indefinitely; past that, the app reports a timeout instead of spinning forever.
:::

### Linux: systemd user service

Yerd uses a systemd `--user` unit named `yerd`. The app writes it to `~/.config/systemd/user/yerd.service` when you start the daemon or enable "Run daemon at login" - you don't install it by hand. It looks like:

```ini
[Unit]
Description=Yerd local PHP development daemon

[Service]
Type=simple
ExecStart=/usr/bin/yerdd serve
Restart=on-failure

[Install]
WantedBy=default.target
```

Enable and start it as your user (never with `sudo`):

```sh
systemctl --user daemon-reload      # only for a freshly-dropped unit
systemctl --user enable --now yerd
```

`Restart=on-failure` brings the daemon back after a crash, but not after a clean exit (e.g. a deliberate stop).

::: tip Keep it running after logout
A user service stops when your last session ends unless lingering is enabled:

```sh
loginctl enable-linger "$USER"
```

:::

::: info Binding 80/443 unprivileged
On a Linux package install (the `.deb`'s post-install, or the Arch package's `.install` scriptlet), the step grants `yerdd` the `cap_net_bind_service` capability so the unprivileged daemon can bind 80/443, and re-applies it on every upgrade (the package manager replaces the binary, wiping file capabilities). Without the capability, the daemon falls back to `8080`/`8443` and `yerd doctor` tells you. See [Elevation & Privileges](./elevation).
:::

### macOS

The app **bundles the daemon** and registers it as a background **`SMAppService`** agent, so it shows up as **Yerd** in System Settings → General → Login Items → Allow in the Background (attributed to the app, with its icon - not to the signing team). Manage it from **Settings → "Run the Yerd daemon in the background"** in the app; the tray menu's Start/Stop/Restart control the running process for the current session.

::: tip First-time approval
The first time the daemon registers, macOS may ask you to enable Yerd in Login Items. The app shows a banner with a button that takes you straight there. A LaunchAgent runs as your user, matching Yerd's rootless model.
:::

::: info Self-repair after an upgrade
An in-place or automated app upgrade replaces the whole bundle but doesn't by itself move launchd's registration - left alone, it would keep running the pre-upgrade `yerdd`. So on every launch the app compares its own version against the version that last registered the daemon:

* If the app version has advanced, it forces a fresh `SMAppService` registration pointing at the new bundle (unregister, then re-register), so launchd picks up the upgraded binary.
* If the registration is already current but launchd has nonetheless dropped the job - `SMAppService` still reports it `.enabled`, but a crash or a manual `bootout` left no live job for it - the app forces the same re-registration even though the version hasn't changed, since a plain kickstart can't recreate a job launchd has lost.
* If the running app is *older* than the version that registered the daemon, it refuses to reconfigure or unregister it, so a stale or downgraded app build can never regress a newer daemon.

Self-repair attempts and their outcomes are appended to `{cache}/yerd-gui-repair.log`, which the desktop app's diagnostics panel tails and includes in "Copy diagnostics" alongside the daemon's own logs. See [Diagnostics](./diagnostics).
:::

For a from-source / terminal run without the app, start the daemon directly:

```sh
yerdd serve &
```

## Lifecycle: start, stop, restart

Under systemd (Linux):

```sh
systemctl --user start yerd        # start
systemctl --user stop yerd         # stop
systemctl --user restart yerd      # restart
systemctl --user status yerd       # is it running?
```

Run by hand, the daemon shuts down gracefully on `Ctrl-C` (`SIGINT`) or `SIGTERM`: it broadcasts a shutdown to every subsystem, gives each a brief window to wind down, stops the PHP-FPM pools, releases its lock, and exits.

```sh
# Foreground: press Ctrl-C
# Backgrounded with `yerdd serve &`:
kill "$(pgrep -x yerdd)"           # sends SIGTERM
```

### Restarting via the CLI

To bounce the daemon without your service manager:

```sh
yerd restart daemon
```

This briefly interrupts all sites (and the command's own connection). The daemon does a graceful teardown then re-execs itself in place (same PID, same arguments), so it works the same whether or not it's supervised.

::: tip Reloading config vs. restarting
Everyday changes rarely need a full restart. Site, PHP-version, and HTTPS changes go through IPC and take effect immediately as the daemon re-scans parked roots and swaps its router live. Use `yerd restart daemon` when you change something read only at startup, such as `dns_port` (which must stay fixed so an installed resolver config keeps pointing at it). See the [Configuration Reference](../reference/configuration).
:::

## Single-instance protection

Only one `yerdd` runs per user. At startup it hardens its runtime directory to `0o700` and takes an exclusive advisory lock on `<runtime>/yerd.lock` (`flock`-style on Linux/macOS). The lock is held for the daemon's lifetime and released on exit.

A second instance fails immediately rather than racing for the socket:

```text
another yerdd is already running (lock held at …/yerd.lock)
```

That's exit code 75 (`EX_TEMPFAIL`). Other startup failures use sysexits-style codes:

| Code | Meaning | Cause |
|---|---|---|
| `0` | Success | Clean shutdown |
| `70` | `EX_SOFTWARE` | Generic failure (DNS/proxy/PHP/IPC) |
| `71` | `EX_OSERR` | Platform or TLS error |
| `74` | `EX_IOERR` | Filesystem I/O error |
| `75` | `EX_TEMPFAIL` | Another `yerdd` is already running |
| `78` | `EX_CONFIG` | Config or core-validation error |

::: tip "Already running" but nothing's serving?
An old process is still holding the lock. Check `pgrep -x yerdd`, stop it, then start fresh. The runtime directory also holds the IPC socket (`yerd.sock`), locked to your user as the access boundary.
:::

## Logging

`yerdd` uses `tracing` and writes to two sinks at once: a compact stream to stderr, and a durable daily-rolling file at `{cache}/yerdd.<date>.log` (see [Where the daemon keeps its files](#where-the-daemon-keeps-its-files)). The file sink is unconditional - it's written every run, regardless of how the daemon was started or whether anything is capturing stderr. Rotation keeps at most 3 days of files; older ones are pruned automatically. Verbosity maps to the `-v` flags and applies to both sinks:

| Flag | Level |
|---|---|
| (none) | `INFO` |
| `-v` | `DEBUG` |
| `-vv` | `TRACE` |

At the default level the DNS server's per-query logging is capped at `WARN`. Otherwise it would log every inbound lookup (including routine `NXDomain` results for non-`.test` names your OS forwards) and flood the log. Raising verbosity lifts that cap so you can watch DNS traffic.

Where stderr goes depends on how the daemon was started:

* Under systemd (Linux), stderr goes to the journal:

  ```sh
  journalctl --user -u yerd -f
  ```

* Run by hand, stderr prints to your terminal. Redirect for persistence:

  ```sh
  yerdd serve > ~/yerd.log 2>&1 &
  ```

::: tip The file log survives even when stderr doesn't
Under launchd or systemd, a start failure can leave nothing useful on stderr. `yerdd.<date>.log` is written regardless, so it's the place to look first - a crash or a startup error (a bad config, a runtime that fails to build) lands there even when nothing was capturing the process's stderr. If the cache directory can't be resolved or created, the daemon degrades to stderr-only rather than failing to start.
:::

::: info Diagnostics over raw logs
For a quick health picture, prefer `yerd status` (daemon, ports, DNS, CA trust, PHP pools with PID/RAM, load) or `yerd doctor` over reading logs. Both query the running daemon over IPC. See [Diagnostics](./diagnostics).
:::

## Where the daemon keeps its files

`yerdd` resolves a small set of per-user directories at startup (XDG-based on Linux, the equivalents on macOS):

| Directory | Holds |
|---|---|
| config | `yerd.toml` (the authoritative config) |
| data | The local CA (`ca.cert.pem`, `ca.key.pem`) and issued leaf certificates |
| state | Long-lived state |
| cache | Downloads, other regenerable files, and the rolling `yerdd.<date>.log` |
| runtime | The IPC socket (`yerd.sock`) and single-instance lock (`yerd.lock`) |

The runtime directory is security-sensitive: it's forced to `0o700` and the IPC socket is restricted to your user, since directory and socket permissions are the only access control on the socket. The CA private key is locked to its owner; the CA certificate is world-readable but never group/world-writable, so the trust helper accepts it.

::: warning Never run yerdd as root
Yerd is rootless by design. Running as root creates root-owned files in your config/data/runtime directories and breaks the privilege boundary. When a command needs privilege, Yerd elevates a tiny audited helper for that one step. See [Elevation & Privileges](./elevation).
:::

## See also

* [Getting Started](./getting-started) - install and first run
* [Diagnostics](./diagnostics) - `status` and `doctor`
* [Configuration Reference](../reference/configuration) - every `yerd.toml` key
* [CLI Reference](../reference/cli/) - the full `yerd` command surface
* [yerdd internals](../developer/binaries/yerdd) - startup wiring, shutdown channel, lock ordering
* [IPC Protocol](../developer/ipc-protocol) - how clients talk to the daemon
* Source: [`bin/yerdd` on GitHub](https://github.com/forjedio/yerd/tree/main/bin/yerdd)

---

---
url: 'https://yerd.app/guide/diagnostics.md'
---
# Diagnostics

Two commands cover almost everything:

* **`yerd status`** - a live daemon snapshot: ports, DNS, CA, PHP pools (PID and memory), and load.
* **`yerd doctor`** - runs every health check, sorts findings by severity, and prints the exact fix command for each. **`yerd doctor fix`** then auto-repairs the safe, unprivileged ones.

Both read from the daemon, which owns all runtime state. The CLI is a thin client, so `status`, `doctor`, and the desktop app never disagree about what's running.

## In the desktop app

The **Doctor** page (under the **System** group) mirrors the CLI's diagnostics in two panels. The **Health** list sorts every finding by severity - Healthy, Warning, or Problem - each with a copyable remedy command. **Run safe fixes** applies the safe one-click repairs (restarting a failed PHP-FPM pool), and **Re-check** re-runs diagnostics; on a healthy machine the list collapses to an "all clear" panel.

The same page carries an **Environment** panel for OS-level state, each row with a one-click action behind an OS prompt (the GUI never runs as root):

* **Local CA trusted** - whether HTTPS sites are trusted in the system store.
* **`.test` resolver installed** - whether the OS routes `*.test` to Yerd's DNS.
* **Privileged ports (80/443)** - whether the daemon can bind the standard ports.

Where a row isn't configured, **Fix (elevate)** runs the privileged action; once it *is* configured, **Revert** (Unelevate) undoes it, both behind an in-app confirm dialog and the OS prompt. Reverting the resolver restores your previous one on macOS; port revert is macOS-only.

See [Features](./desktop-app#doctor) for the rest of the GUI.

### When the daemon won't start

If the app fails to start the daemon, it shows a diagnostics panel with hints derived from the daemon's own logs plus the last few lines of the macOS self-repair trail (`yerd-gui-repair.log` - see [The Daemon](./daemon#autostart)). One case it recognizes: a running daemon whose config schema is newer than what the daemon build understands (an upgrade that didn't fully take effect) - the panel names it explicitly and suggests toggling the daemon's login item off then on in Settings to force re-registration, or removing any leftover old `Yerd.app` copies.

"Copy diagnostics" in that panel bundles the daemon log tail, the repair log tail, and the detected hints together, so a bug report carries everything in one paste.

## From the command line

::: tip
Add `--json` to either command for machine-readable output. Exit codes matter too: `yerd doctor` exits `1` on any hard failure, else `0`.
:::

### `yerd status`

A read-only snapshot, rendered as one block. No flags beyond the global `--json`.

```sh
yerd status
```

A healthy machine looks roughly like this:

```text
daemon    running (pid 4821, up 2h 13m, rss 6.2 MB)
version   2.0.2
tld       .test
http      80
https     443
dns       127.0.0.1:1053
ca        trusted: yes  (/Users/you/Library/Application Support/io.yerd.Yerd/ca/ca.cert.pem)
resolver  installed: yes
load      0.42 0.51 0.48
sites     3 parked, 1 linked, 2 secured

php
  8.5 (default)  running  pid 4830  /run/user/501/yerd/fpm-8.5.sock  rss 18.4 MB
  8.3            running  pid 4844  /run/user/501/yerd/fpm-8.3.sock  rss 17.1 MB
```

### What each line means

| Line | Notes |
|---|---|
| `daemon` | pid, uptime, RSS. The reverse proxy and DNS responder run inside the daemon, so one RSS figure covers all three. Omitted when it can't be read (non-Linux or transient failure). |
| `version` | The running daemon's version. Shows `unknown` for daemons that predate version reporting. |
| `tld` | The TLD served, e.g. `.test`. |
| `http` / `https` | The bound port. A privileged-port fallback shows `80 → 8080 (fallback)`; an active macOS redirect shows `80 → 8080 (redirected)`. Reachable on the requested port either way. When neither the privileged port nor its fallback could bind, the line instead reads `not serving - couldn't bind 8080 (run yerd doctor)` - the daemon is up but serving no sites. See `doctor`'s `WebPortsUnbound`. |
| `ports` (conflict) | Only shown when a **non-Yerd** process is holding 80/443. Yerd confirms the redirect actually reaches *its* proxy (via a `Server: yerd` marker), so a foreign web server or a stale `pf` rule is reported as a conflict rather than mistaken for a live redirect. Run `yerd doctor`. |
| `dns` | The address the embedded DNS responder is bound on, or `not resolving - couldn't bind port 1053 (run yerd doctor)` when something else already holds that port. This is a soft-fail: the daemon still runs (proxy, PHP pools, IPC), just without `.test` name resolution. See `doctor`'s `DnsPortUnbound`. |
| `ca` | `trusted: yes / no / unknown`, plus the CA cert path. `unknown` means the probe couldn't tell, and is not treated as untrusted. |
| `resolver` | Whether the OS resolver routes `*.<tld>` to Yerd. Tri-state (`yes` / `no` / `unknown`). |
| `load` | 1/5/15-minute load averages. Omitted where unavailable. |
| `sites` | Parked, linked, and secured (HTTPS) counts. |
| `php` | One line per installed version: state (`running` / `stopped` / `failed`), FPM master `pid`, listen socket, RSS, and `update→<patch>` when a newer patch exists. The default is marked `(default)`. |

::: info Why ports read "fallback"
Binding 80 and 443 needs elevation. Without it, the daemon falls back to rootless `8080`/`8443`. On macOS, `sudo yerd elevate ports` installs a packet-filter redirect so 80/443 still reach the rootless listener; `status` shows `(redirected)` and `doctor` treats it as satisfied. See [Elevation & Privileges](./elevation) and [HTTPS & Certificates](./https).
:::

### `yerd doctor`

Runs the full set of checks and prints each finding with a severity mark, an explanation, and the fix command where applicable.

```sh
yerd doctor
```

```text
⚠ Local CA not trusted
    HTTPS sites will show certificate warnings until the CA is trusted.
    → sudo yerd elevate trust
✗ PHP-FPM pool failed
    The PHP 8.5 FPM pool is not running.
    → fixed automatically by `yerd doctor fix`, or restart with `yerd use 8.5`
```

When nothing is wrong:

```text
✓ All checks passed
    Daemon, ports, DNS, CA, and PHP look healthy.
```

#### Severities

| Mark | Severity | Meaning |
|---|---|---|
| `✓` | `Ok` | Informational or healthy. Never affects the exit code. |
| `⚠` | `Warn` | A non-fatal problem worth addressing (e.g. CA not trusted). |
| `✗` | `Fail` | Breaks expected behaviour (e.g. no PHP, a dead pool). Any `Fail` exits `1`. |

#### What doctor checks

| Code | Severity | Meaning | Remedy |
|---|---|---|---|
| `DaemonDown` | `Fail` | The CLI couldn't reach the daemon over IPC. | `yerdd` |
| `WebPortsUnbound` | `Fail` | Neither the privileged web ports nor their rootless fallback could bind (something else holds both) - the daemon is up but serving no sites. Supersedes `PortFallback`. | Free the ports, or change the fallback ports in Settings (Yerd ▸ General), then restart the daemon |
| `PortFallback` | `Warn` | A privileged port (below 1024) fell back to rootless and isn't reachable on the requested port. | `sudo yerd elevate ports` |
| `ForeignWebListener` | `Warn` | A process **other than Yerd** is listening on 80/443 (confirmed via the proxy's `Server` marker, so Yerd is never mistaken for the squatter). Cross-platform. Supersedes `PortFallback` - elevation can't bind a port someone else owns. | Stop the other web server, then `sudo yerd elevate ports` |
| `DnsPortUnbound` | `Warn` | The DNS port (`dns_port`) is held by another process. The daemon still runs, just without `*.test` resolution - independent of the web-port checks above, so it surfaces even alongside `WebPortsUnbound`. | Free that port, or change it in Settings (Yerd ▸ General), then restart. Re-run `sudo yerd elevate resolver` if the port changed |
| `CaNotTrusted` | `Warn` | The local CA isn't in the system trust store, so HTTPS shows warnings. | `sudo yerd elevate trust` |
| `PhpCaNotTrusted` | `Warn` | The bundled PHP's CA bundle (`cacert.pem`) is missing or stale, so PHP HTTPS to `.test` fails with cURL error 60. **Auto-fixable.** | `yerd doctor fix` (rebuilds the bundle; restart Yerd if it persists) |
| `ResolverNotInstalled` | `Warn` | The OS resolver doesn't route `*.<tld>` to Yerd's DNS. | `sudo yerd elevate resolver` |
| `NoPhpInstalled` | `Fail` | No PHP versions installed. | `yerd install php <default>` |
| `DefaultPhpNotInstalled` | `Fail` | The default PHP version isn't installed (others are). | `yerd install php <default>` |
| `FpmPoolFailed` | `Fail` | A supervised FPM master died. **Auto-fixable.** | `yerd doctor fix`, or `yerd use <version>` |
| `PhpUpdateAvailable` | `Ok` | A newer patch exists (notify-only; Yerd never updates silently). | `yerd update php <version>` |
| `ResolverBackupSaved` | `Ok` | Installing the resolver replaced a pre-existing `/etc/resolver/<tld>` (e.g. a Valet/Herd leftover); a timestamped backup was saved. `sudo yerd unelevate resolver` restores it automatically. | *(none)* |
| `NoSites` | `Ok` | No sites configured yet. | `yerd park <dir>` or `yerd link <name> <dir>` |
| `DomainShadowed` | `Warn` | Two sites claim the same domain, so one was dropped from routing. Which site wins can depend on directory scan order, so it may change on restart (usually the result of a hand-edited config). | Make each site's domains unique with `yerd domain remove` or `yerd domain primary` |
| `AllGood` | `Ok` | Nothing else is wrong. | *(none)* |

::: tip No false alarms
Several probes are tri-state. CA trust and resolver installation are flagged only when the daemon is certain they're absent; an `unknown` result stays silent. Likewise, `NoPhpInstalled` suppresses `DefaultPhpNotInstalled`, an active macOS port redirect suppresses `PortFallback`, and a `ForeignWebListener` conflict also suppresses `PortFallback` (the foreign-process warning is the accurate, actionable finding - elevating won't help while another process owns the port).
:::

### `yerd doctor fix`

Performs the safe, unprivileged repairs, then re-diagnoses and lists whatever still needs you.

```sh
yerd doctor fix
```

```text
applied fixes:
  ✓ restarted PHP 8.5 FPM pool

still needs attention:
  ⚠ Local CA not trusted
      → sudo yerd elevate trust
```

If nothing was auto-fixable:

```text
no automatic fixes were applicable
```

#### Auto-fixes are safe-only

`doctor fix` only applies fast, idempotent, unprivileged repairs on its own: **restarting a failed PHP-FPM pool**, and **rebuilding the bundled PHP's CA bundle** (`cacert.pem`) when it's missing or stale. Everything privileged or consequential is left for you to run, surfaced under "still needs attention" with the exact command:

* Trusting the CA (`sudo yerd elevate trust`)
* Installing the DNS resolver (`sudo yerd elevate resolver`)
* Granting the port capability / redirect (`sudo yerd elevate ports`)
* Installing or updating PHP (`yerd install php …`, `yerd update php …`)

::: warning
`yerd doctor fix` will not run `sudo` for you. Privileged fixes always require you to run the suggested `sudo yerd elevate …` command yourself. See [Elevation & Privileges](./elevation).
:::

#### How fix works

```text
1. daemon builds a StatusReport
2. plan_auto_fixes(report)  ->  failed FPM pools become RestartFpm; a stale PHP CA bundle becomes RebuildPhpCaBundle
3. daemon performs each restart, recording success/failure  ->  "applied fixes"
4. daemon re-builds a fresh StatusReport and re-diagnoses
5. remaining Warn/Fail findings  ->  "still needs attention"
```

Step 4 re-diagnoses against the post-fix world, so a successfully restarted pool won't reappear; a failed restart shows `✗` under "applied fixes" and the finding persists. The exit code follows that remainder: `1` only if a `Fail` still stands.

### Putting it together

A typical troubleshooting loop:

```sh
yerd status          # what's the daemon doing now?
yerd doctor          # what's wrong and how do I fix it?
yerd doctor fix      # repair the safe stuff
sudo yerd elevate trust   # run any privileged command doctor surfaced
yerd doctor          # confirm everything is green
```

## Related

* [The Daemon](./daemon) - what `yerdd` supervises and how `status` is assembled.
* [Elevation & Privileges](./elevation) - the privileged fixes doctor surfaces.
* [PHP Versions](./php-versions) - installing, the default, and FPM pools.
* [HTTPS & Certificates](./https) and [DNS & .test Domains](./dns) - the CA-trust and resolver checks.
* [CLI Reference](../reference/cli/) - every command and flag.
* For the diagnosis logic, see the [yerd-doctor crate](../developer/crates/yerd-doctor) and its [source on GitHub](https://github.com/forjedio/yerd).

---

---
url: 'https://yerd.app/reference/cli.md'
---
# CLI Reference

The `yerd` command is a thin client that talks to the `yerdd` daemon over a local IPC socket. Almost every subcommand maps to exactly one daemon request: `yerd` validates your arguments locally, sends the request, and renders the daemon's reply as either a human-readable block or machine-readable JSON.

This reference documents every command, subcommand, positional argument, and flag exactly as the CLI defines them. If a flag isn't listed here, it doesn't exist.

::: tip
`yerd --help` and `yerd <command> --help` always print the authoritative, version-matched usage for your installed build. This reference mirrors that surface and explains what each command does behind the scenes.
:::

## Synopsis

```sh
yerd [--json] <COMMAND> [ARGS...]
```

### Global flags

| Flag | Description |
| --- | --- |
| `--json` | Emit machine-readable JSON instead of human-readable text. Available on every command except [`coverage`](./coverage), which forwards everything after it (including `--json`) to PHP. |
| `--help`, `-h` | Print help for the command. |
| `--version`, `-V` | Print the `yerd` version. |

`--json` is a global flag, so you can place it before or after the subcommand: `yerd --json status` and `yerd status --json` are equivalent. In JSON mode the entire daemon response is printed as pretty JSON; the process exit code still reflects success or failure (see [Exit codes](#exit-codes)). The one exception is [`coverage`](./coverage), which is a passthrough to PHP: anything after `coverage` - `--json` included - goes to PHP rather than to `yerd`.

::: info
`yerd` is the command-line front end. The daemon (`yerdd`) does the real work: running the proxy, DNS responder, PHP-FPM pools, and certificate authority. See [The Daemon](../../guide/daemon) for how it runs, and the [IPC Protocol](../../developer/ipc-protocol) for the request/response wire format.
:::

## Commands

| Group | Commands |
| --- | --- |
| [Sites](./sites) | `sites`, `park`, `unpark`, `link`, `unlink`, `root` |
| [Domains](./domains) | `domain list`, `domain add`, `domain remove`, `domain primary`, `domain reset` |
| [Proxies](./proxies) | `proxy add`, `proxy remove`, `proxy list` |
| [HTTPS](./https) | `secure`, `unsecure` |
| [PHP](./php) | `use`, `install php`, `uninstall php`, `update php`, `restart php`, `list php`, `list parked`, `set php`, `unset php`, `php ext add`/`remove`/`list`, [`coverage`](./coverage) |
| [Tooling](./tooling) | `tools`, `install tool`, `uninstall tool`, `path install`, `path uninstall`, `path print` |
| [Services](./services) | `services`, `service available`, `service install`, `service change-version`, `service uninstall`, `service start`, `service stop`, `service restart`, `service set-port`, `service logs` |
| [Databases](./db) | `db list`, `db create`, `db drop`, `db backup`, `db restore` |
| [Mail](./mail) | `mail list`, `mail show`, `mail clear` |
| [LAN sharing](./lan) | `lan enable`, `lan disable`, `lan status`, `remote-setup` |
| [Tunnel](./tunnel) | `tunnel install`, `tunnel share`, `tunnel stop`, `tunnel status`, `tunnel login`, `tunnel create`, `tunnel delete`, `tunnel list`, `tunnel route`, `tunnel set-host`, `tunnel publish`, `tunnel unpublish` |
| [Diagnostics](./diagnostics) | `ping`, `status`, `doctor`, `doctor fix` |
| [Elevation](./elevation) | `elevate`, `unelevate` |
| [Daemon control](./daemon) | `restart daemon` |
| [Self-Update](./update) | `update` (check/apply a Yerd self-update) |
| [Uninstall](./uninstall) | `uninstall` (full self-uninstall), `uninstall php`, `uninstall tool` |

## Exit codes

`yerd` returns a meaningful process exit code so it composes cleanly in scripts and CI:

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | The daemon returned an error response, or a `doctor` run had a `Fail`-severity finding. |
| `2` | Client-side usage error (bad site name, invalid domain, invalid PHP version, unknown/invalid PHP setting). |
| `69` | The daemon was unreachable (for non-`doctor` commands). |
| `74` | Other transport / I/O failure. |

For the `elevate`/`unelevate` path, additional codes can surface: `77` if not run as root, `69` if the daemon's facts can't be fetched, `74` if the helper/daemon sibling binaries can't be located, and `1` if any privileged step failed.

```sh
# Use the exit code in a script
if yerd doctor; then
  echo "yerd is healthy"
else
  echo "yerd reported problems (exit $?)"
fi
```

## JSON output

Pass `--json` to get the raw daemon response as pretty-printed JSON, ideal for scripting or for the [desktop app](../../guide/desktop-app) and other tooling:

```sh
yerd --json status
yerd --json list php --available
yerd --json sites
```

The exit code in JSON mode matches the human path exactly, including doctor's `Fail`-aware behaviour, so you can branch on the code and parse the body independently.

## See also

* [Sites](../../guide/sites): parking vs. linking
* [PHP Versions](../../guide/php-versions): installing, switching, and tuning PHP
* [Services & Databases](../../guide/services): native MySQL · MariaDB · Postgres · Redis
* [HTTPS & Certificates](../../guide/https): securing sites
* [Sharing Sites](../../guide/sharing): publishing a site over a public URL via Cloudflare Tunnel
* [Elevation & Privileges](../../guide/elevation): what `sudo yerd elevate` does
* [Configuration Reference](../configuration): config file keys and locations
* [IPC Protocol](../../developer/ipc-protocol): the request/response surface each command maps to
* Source: [`forjedio/yerd`](https://github.com/forjedio/yerd)

---

---
url: 'https://yerd.app/reference/cli/sites.md'
---
# Sites

A directory tree is served in one of two ways: **park** a parent directory so each child folder automatically becomes a `<child>.test` site, or **link** a single directory under an explicit name. See the [Sites guide](../../guide/sites) for the full model.

| Command | Description | Example |
| --- | --- | --- |
| `yerd sites` | List every parked or linked site. | `yerd sites` |
| `yerd park <PATH>` | Park a directory: each of its child directories becomes a `.test` site. | `yerd park ~/Sites` |
| `yerd unpark <PATH>` | Un-park a directory so its children stop being served. Linked sites are untouched. | `yerd unpark ~/Sites` |
| `yerd link` | Link the current directory, named after its folder. | `yerd link` |
| `yerd link <NAME>` | Link the current directory under an explicit name. | `yerd link blog` |
| `yerd link <PATH>` | Link a directory, named after its folder. | `yerd link ~/code/blog` |
| `yerd link <NAME> <PATH>` | Link a directory under an explicit name. | `yerd link blog ~/code/blog` |
| `yerd unlink <NAME>` | Remove a linked site by name. | `yerd unlink blog` |
| `yerd root <NAME> <PATH>` | Set the served directory (web root) for a site, relative to its folder. | `yerd root blog public` |
| `yerd root <NAME> --auto` | Reset a site to automatic web-root detection. | `yerd root blog --auto` |

```sh
# Park a folder of projects: every subdirectory is reachable at <name>.test
yerd park ~/Sites

# Link one project under a specific name (serves https://blog.test once secured)
yerd link blog ~/code/blog

# Link the current project, named after its folder
cd ~/code/blog && yerd link

# See everything yerd is serving
yerd sites
```

`yerd sites` prints a table with the columns `NAME`, `KIND` (`parked` or `linked`), `PHP`, `SECURE`, `SERVED`, and `DOCROOT`. `SERVED` is the web root relative to the document root (`/` means the project root itself is served). When there are no sites it prints `no sites`. A `DOMAIN` column appears only when at least one site has a customised primary domain or a shadowed apex; each cell holds the site's primary FQDN, or `apex shadowed by <site>` when another site claims its apex, or `-`. Use [`yerd domain list`](./domains) to see the full per-site domain set (including subdomains and wildcards).

::: details How site names are validated
`link`, `unlink`, `secure`, `unsecure`, and `root` validate the name client-side before connecting: a name must be a single valid DNS label. A bad name (e.g. `bad name` or `bad/name`) fails immediately with a usage error and exit code `2`, before any request reaches the daemon.

`link` accepts a single positional argument as either a name or a path: an argument containing a path separator (or `.`/`..`) is treated as a directory, and the site name is derived from its folder name (lowercased, with runs of invalid characters collapsed to a single `-`); a bare word is always treated as a name, even if a same-named subdirectory happens to exist. With no arguments at all, the current directory is linked and named after its own folder.
:::

::: tip Web root detection
Yerd auto-detects the directory each site is served from (e.g. `public/` for Laravel, the project root for WordPress). For a **parked** site it re-detects continuously as the project changes. For a **linked** site detection runs once, when the site is first linked; it isn't re-run automatically afterward. `yerd root <name> <path>` pins it explicitly for either kind. `yerd root <name> --auto` (or with no path) returns to auto-detection: for a linked site this re-runs the one-shot detection immediately and pins the fresh result; for a parked site it clears the pin and hands the site back to the continuous watched detection. The path must resolve to a directory inside the site's folder. See the [Sites guide](../../guide/sites#web-root-the-served-directory).
:::

::: warning About `unpark`
The daemon stores parked roots by their canonical path and matches `unpark` against that stored string **exactly**. `yerd` best-effort canonicalises the path you type (resolving symlinks and relative paths) so it matches. If the directory has been deleted from disk it can't be canonicalised, so pass the exact stored path instead. Run `yerd list parked` to see the canonical paths the daemon holds, including empty roots that produce no sites and therefore don't show up in `yerd sites`.
:::

---

---
url: 'https://yerd.app/reference/cli/domains.md'
---
# Domains

Every site answers on its `{name}.test` **apex** by default. The `yerd domain`
commands let a site carry **multiple** domains, use **subdomains** and
**wildcards**, and **change** which domain is primary - without renaming the
site.

| Command | Description | Example |
| --- | --- | --- |
| `yerd domain list` | List every site's effective domains (primary marked). | `yerd domain list` |
| `yerd domain list <SITE>` | List one site's domains. | `yerd domain list blog` |
| `yerd domain add <SITE> <FQDN>` | Add an exact host or a single-label wildcard. | `yerd domain add blog corp.test` |
| `yerd domain remove <SITE> <FQDN>` | Remove a domain (a site must keep one exact domain). | `yerd domain remove blog blog.test` |
| `yerd domain primary <SITE> <FQDN>` | Set the canonical domain (added if absent; must be exact). | `yerd domain primary blog corp.test` |
| `yerd domain reset <SITE>` | Reset a site to its default apex-only domain. | `yerd domain reset blog` |

```sh
# Give one app several apex domains (multi-tenant: all served from one project)
yerd domain add app acme.test
yerd domain add app globex.test

# A single-label wildcard: every foo.test subdomain (one level) routes to blog
yerd domain add blog '*.blog.test'

# Point a specific subdomain at a *different* site (exact beats wildcard)
yerd link api ~/code/api
yerd domain add api api.blog.test

# Move a site to a new primary domain and drop the old apex
yerd domain add blog corp.test
yerd domain primary blog corp.test
yerd domain remove blog blog.test
```

`domain list` marks each site's primary domain, and appends
`[apex shadowed by <site>]` to a site whose apex label is claimed by another
site - the same condition doctor reports as its `DomainShadowed` check. With
`--json`, each site is `{name, primary, domains, apex_shadowed_by}`.

## How resolution works

For an incoming host, yerd tries an **exact** domain match first, then a
**single-label wildcard** (the host with its leftmost label replaced by `*`).
Exact always wins.

* `*.blog.test` matches exactly one label - `api.blog.test`, not
  `x.api.blog.test`. To route a deeper level, register that wildcard too:
  `yerd domain add deep '*.api.blog.test'`.
* `blog.test` and `*.blog.test` can belong to **different** sites.
* A domain can only be claimed by one site; adding a domain another site already
  holds fails with an "already routes to" error.

::: warning Subdomains are now explicit
Earlier versions routed **every** subdomain of a site (`anything.blog.test`) to
that site automatically. That implicit catch-all has been **removed**: a site
answers only its apex until you add domains. If you relied on subdomains
(e.g. WordPress multisite in subdomain mode), re-enable them explicitly:

```sh
yerd domain add blog '*.blog.test'
```

:::

::: details Client-side validation
`domain add/remove/primary` validate the site name and the domain's shape
client-side (ASCII `[a-z0-9.*-]`, `*` only as the leftmost label) before
connecting - a malformed domain fails with a usage error and exit code `2`. The
daemon validates that the domain sits under the configured TLD.
:::

---

---
url: 'https://yerd.app/reference/cli/proxies.md'
---
# Proxies

A **reverse proxy** fronts an already-running service with a Yerd `.test`
address, so it gets the same DNS, HTTPS, and browser experience as a PHP site -
without Yerd running the service itself. Two shapes:

* A **whole-host proxy** maps a new host to a service: `reverb.test` → a Reverb,
  Node, Vite, or Docker service on some port.
* A **path rule** maps a path *on an existing site* to a service:
  `myapp.test/app` → a service, while every other path on `myapp.test` keeps
  being served by PHP. This is the same-origin setup Laravel Reverb wants
  (`wss://myapp.test/app`), so cookies and CORS just work.

`yerd proxy add`'s two forms are distinguished by argument count: two arguments
create a whole-host proxy, three attach a path rule to a site.

| Command | Description | Example |
| --- | --- | --- |
| `yerd proxy add <NAME> <URL>` | Create a whole-host proxy (`<NAME>.test` → `<URL>`). | `yerd proxy add reverb http://localhost:8080` |
| `yerd proxy add <SITE> <PREFIX> <URL>` | Add a path rule: requests under `<PREFIX>` on `<SITE>.test` proxy to `<URL>`. | `yerd proxy add myapp /app http://127.0.0.1:8080` |
| `yerd proxy remove <NAME>` | Remove a whole-host proxy. | `yerd proxy remove reverb` |
| `yerd proxy remove <SITE> <PREFIX>` | Remove a path rule from a site. | `yerd proxy remove myapp /app` |
| `yerd proxy list` | List every whole-host proxy and per-site path rule. | `yerd proxy list` |

```sh
# Whole-host: front a Reverb server on its own .test domain
yerd proxy add reverb http://localhost:8080
curl http://reverb.test/          # → the Reverb service

# Serve it over HTTPS - a proxy secures exactly like a site
yerd secure reverb
curl https://reverb.test/

# Path rule (the Reverb same-origin case): /app on an existing Laravel site
yerd proxy add myapp /app http://127.0.0.1:8080
# https://myapp.test/        → PHP (Laravel)
# https://myapp.test/app     → Reverb (websockets included)

# List, then remove
yerd proxy list
yerd proxy remove myapp /app
yerd proxy remove reverb
```

A path rule inherits its parent site's TLS: securing `myapp` (`yerd secure
myapp`) also secures its `/app` rule. A whole-host proxy is secured on its own
name (`yerd secure reverb` / `yerd unsecure reverb`), exactly like a site.

## Upstreams

The upstream `<URL>` is `http://host:port` or `https://host:port`. The port is
required for anything but the default (`80`/`443`). For an `https://` upstream,
Yerd verifies the certificate for a genuine public host, but **skips
verification for a local host** (`localhost`, a loopback/private IP, or a
`.test` name) - self-signed dev backends are the norm there.

The request path is passed to the upstream **unchanged** (an nginx
`proxy_pass` with no trailing path), so a path rule's prefix reaches the
upstream too: `myapp.test/app/foo` → `<URL>/app/foo`. Yerd preserves the
original `Host` header and adds the usual `X-Forwarded-For`,
`X-Forwarded-Proto`, `X-Forwarded-Host`, and `X-Real-IP` headers. Websocket
(`Connection: Upgrade`) traffic is tunnelled through, so Reverb/Vite HMR work.

If the upstream is down, a proxied request returns **`502 Bad Gateway`** rather
than hanging.

## How a request routes

For an incoming host, Yerd resolves it to a site or a whole-host proxy, then:

* a **whole-host proxy** forwards every request to its upstream (no PHP);
* a **site** with a matching **path rule** forwards that request to the rule's
  upstream; every other path is served by PHP as usual. Matching is
  longest-prefix with path boundaries, so `/app` matches `/app` and `/app/x`
  but **not** `/apple`.

If a whole-host proxy's name collides with a real site's apex, the site wins and
the proxy is dropped (surfaced by [`yerd doctor`](./diagnostics)).

::: details Client-side validation & guards
`proxy add` validates the upstream URL and, for a path rule, that the prefix
begins with `/`, before connecting - a malformed value fails with a usage error
(exit code `2`). The daemon rejects a target that would **loop back into Yerd**:
a `.test` host, or a loopback host on one of Yerd's own bound proxy ports. A
proxy name that collides with an existing site or proxy is rejected as
"already exists".
:::

## See also

* [HTTPS & Certificates](../../guide/https) - how `secure` mints a trusted cert.
* [Reverse Proxies](../../guide/proxies) - the guide-level walkthrough.
* [Domains](./domains) - give a proxy or site more `.test` names.

---

---
url: 'https://yerd.app/reference/cli/https.md'
---
# HTTPS

`secure` promotes a parked site to a linked entry and serves it over HTTPS using the local certificate authority; `unsecure` stops serving it over HTTPS. See [HTTPS & Certificates](../../guide/https).

| Command | Description | Example |
| --- | --- | --- |
| `yerd secure <NAME>` | Serve a site over HTTPS (promotes a parked site to a linked entry). | `yerd secure blog` |
| `yerd unsecure <NAME>` | Stop serving a site over HTTPS. | `yerd unsecure blog` |

```sh
yerd secure blog      # https://blog.test is now served with a trusted cert
yerd unsecure blog    # back to http only
```

::: tip
For the browser to trust the certificate, the local CA must be installed in your OS trust store. Run `sudo yerd elevate trust` once (see [Elevation](./elevation)).
:::

---

---
url: 'https://yerd.app/reference/cli/php.md'
---
# PHP

Yerd downloads prebuilt static PHP builds and runs an FPM pool per installed version. The [PHP Versions guide](../../guide/php-versions) covers this in depth.

## Choosing the version

The `use` command is overloaded by argument count:

| Command | Description | Example |
| --- | --- | --- |
| `yerd use <VERSION>` | Set the **global** default: the terminal `php` shim and the per-site fallback. | `yerd use 8.5` |
| `yerd use <SITE> <VERSION>` | Set the PHP version for a single named site. | `yerd use blog 8.3` |

```sh
yerd use 8.5          # global default for the `php` shim and new sites
yerd use blog 8.3     # pin one site to 8.3
```

After a successful global `yerd use <version>` (human output only), `yerd` prints a hint telling you which directory holds the managed `php` shim and warns if a different `php` is found earlier on your `PATH` and would shadow it.

::: warning `yerd use` refuses a legacy version as the default
`yerd use <VERSION>` is refused for an out-of-support [legacy version](../../guide/php-versions#legacy-php-versions)
(7.4 / 8.0 / 8.1) - legacy versions can't be the global default. `yerd use <SITE> <VERSION>`
still accepts one, pinning it to that site only.
:::

## Managing installed versions

| Command | Description | Example |
| --- | --- | --- |
| `yerd install php <VERSION> [--legacy]` | Install a PHP version (downloads a prebuilt static build). | `yerd install php 8.5` |
| `yerd uninstall php <VERSION>` | Uninstall a PHP version (removes its files; blocked if in use). | `yerd uninstall php 8.3` |
| `yerd update php [VERSION]` | Update a PHP version to the latest release. Omit the version to update every installed version. | `yerd update php` |
| `yerd restart php [VERSION]` | Restart a PHP FPM pool. Omit the version to restart every running pool. | `yerd restart php 8.5` |
| `yerd list php [--check] [--available]` | List installed PHP versions and the global default. | `yerd list php` |

```sh
yerd install php 8.5      # download + run an 8.5 FPM pool
yerd update php           # update all installed versions to latest
yerd update php 8.5       # update just 8.5
yerd restart php          # restart every running pool
yerd uninstall php 8.3    # remove 8.3 (refused if a site still uses it)
```

### The `--legacy` flag

`7.4`, `8.0`, and `8.1` are out-of-support [legacy versions](../../guide/php-versions#legacy-php-versions)
served from a separate manifest. Installing one requires the explicit `--legacy` flag:

```sh
yerd install php 7.4 --legacy
```

Without `--legacy`, `yerd install php 7.4` prints an out-of-support warning and
refuses to install. `--legacy` is a no-op (accepted but unnecessary) for a
supported version.

### `yerd list php` flags

| Flag | Description |
| --- | --- |
| `--check` | Poll the distribution now to refresh "update available" status. Without it, status is served from the daemon's cache (no network). |
| `--available` | List the versions installable from the distribution instead, tagging ones already installed. **Takes precedence over `--check`.** |

```sh
yerd list php                 # installed versions, from cache (no network)
yerd list php --check         # installed versions, freshly checking for updates
yerd list php --available     # everything installable, tagging what you have
```

Installed versions are printed one per line; the current default is marked `(default)`, and any version with a newer release shows `update available: <installed> -> <latest>`. If nothing is installed, `yerd list php` suggests `yerd install php <default>`.

`yerd list php --available` also prints a trailing **Legacy (out of support - no
coverage, no dumps, cannot be default)** section listing the installable
[legacy versions](../../guide/php-versions#legacy-php-versions), tagging any
already installed - the section is omitted when there are none.

## Global PHP ini settings

`set` and `unset` manage global PHP ini defaults that are applied to **every** installed version. `set` writes a value; `unset` resets a setting back to PHP's built-in default (the wire convention is an empty value).

| Command | Description | Example |
| --- | --- | --- |
| `yerd set php <SETTING> <VALUE> [--only <VERSION>]` | Set a PHP ini default. With `--only`, only that installed version is affected (a per-version override). | `yerd set php memory_limit 512M` |
| `yerd unset php <SETTING> [--only <VERSION>]` | Reset a setting to PHP's built-in value. With `--only`, only that version's override is removed (the global default applies again). | `yerd unset php memory_limit` |

```sh
yerd set php memory_limit 512M
yerd set php display_errors On
yerd unset php memory_limit
yerd set php memory_limit 1G --only 8.3    # only PHP 8.3 gets 1G
yerd unset php memory_limit --only 8.3     # 8.3 inherits the global value again
```

**Precedence:** a version's effective value is its `--only` override when set, else
the global value, else PHP's built-in default. Changing a per-version value
restarts **only** that version's pool; a global change restarts every running
pool. Per-version values survive uninstalling and reinstalling the version.

The setting name (and, for `set`, the value) is validated client-side before connecting, so a typo or an out-of-shape value is a clean usage error rather than a round-trip. The supported settings are:

| Setting | Shape |
| --- | --- |
| `memory_limit` | byte size (e.g. `512M`), or `-1` for unlimited |
| `max_execution_time` | integer |
| `max_input_time` | integer |
| `max_file_uploads` | integer |
| `upload_max_filesize` | byte size (e.g. `64M`) |
| `post_max_size` | byte size (e.g. `64M`) |
| `display_errors` | boolean flag (e.g. `On` / `Off`) |
| `error_reporting` | an `error_reporting` expression |

::: tip
The configured settings are echoed back by `yerd list php` under a `settings:` block, so you can confirm what's currently applied. See the [Configuration Reference](../configuration) for how these are stored and rendered into FPM config.
:::

## Custom extensions

`yerd php ext` registers extra PHP extensions (`.so`) that Yerd's builds don't
ship. A registered extension loads into **both** the FPM (web) runtime and the CLI
for its version. Native extensions are ABI-bound to a PHP minor, so each is
registered under one version.

| Command | Description | Example |
| --- | --- | --- |
| `yerd php ext add <VERSION> <PATH> [--zend] [--name <NAME>]` | Register an extension for a version. | `yerd php ext add 8.5 /opt/php/pecl/scrypt.so` |
| `yerd php ext remove <VERSION> <NAME>` | Remove a registered extension by name. | `yerd php ext remove 8.5 scrypt` |
| `yerd php ext list` | List registered extensions, grouped by version. | `yerd php ext list` |

```sh
yerd php ext add 8.5 /opt/homebrew/lib/php/pecl/20250925/scrypt.so
yerd php ext add 8.5 /opt/php/xdebug.so --zend --name xdebug
yerd php ext list
yerd php ext remove 8.5 scrypt
```

* `VERSION` is a `major.minor` (e.g. `8.5`) and must be installed.
* `PATH` must be an absolute path ending in `.so`, with no control characters,
  NUL, `"`, or `$` (spaces are allowed). It is validated client-side before
  connecting, so a bad path is a clean usage error rather than a round-trip.
* `--zend` loads it as a `zend_extension` (xdebug/opcache-style) rather than a
  plain `extension`.
* `--name` sets the removal/display handle; it defaults to the `.so` basename.

On `add`, the daemon **load-probes** the `.so` against that version's PHP and
rejects it if it can't load (wrong-version build, missing dependency, or a Zend
extension registered without `--zend`), so a bad extension is a clear error rather
than a broken pool. `add`/`remove` restart that version's running FPM pool.
`yerd php ext list` tags any extension whose `.so` is missing on disk with
`(missing!)`. See the [Configuration Reference](../configuration#php) for how the
registry is stored.

## Custom ini directives

`yerd php ini` sets free-form ini directives for **one** installed version - the
directives Yerd's typed allowlist doesn't cover, typically extension settings
like `xdebug.mode` or `opcache.jit_buffer_size`. They apply to that version's
FPM (web) pool and its CLI.

| Command | Description | Example |
| --- | --- | --- |
| `yerd php ini set <VERSION> <NAME> <VALUE>` | Set a directive for one installed version. | `yerd php ini set 8.3 xdebug.mode debug` |
| `yerd php ini unset <VERSION> <NAME>` | Remove a directive. | `yerd php ini unset 8.3 xdebug.mode` |
| `yerd php ini list` | List per-version overrides and directives (same output as `yerd list php`). | `yerd php ini list` |

```sh
yerd php ext add 8.3 /opt/php/xdebug.so --zend   # 1. load the extension
yerd php ini set 8.3 xdebug.mode debug           # 2. configure it
yerd php ini list
yerd php ini unset 8.3 xdebug.mode
```

Names and values are **shape-validated** (no control characters or the ini
metacharacters `[ ] = ; #`), but not semantically: a well-formed directive PHP
doesn't recognise is simply ignored by PHP. Directives Yerd manages through
typed paths are refused with a pointer to the right command: the eight
[allowlisted settings](#global-php-ini-settings) (use `yerd set php`,
optionally with `--only`), `extension`/`zend_extension` (use `yerd php ext`),
and `openssl.cafile`/`curl.cainfo` (Yerd manages the CA bundle).

In the FPM pool config a directive renders as `php_value[name] = value`
(FPM coerces boolean-valued directives); in the version's CLI ini it renders as
a plain `name = value` line. Setting or removing a directive restarts only that
version's pool, and directives survive uninstalling and reinstalling the
version.

---

---
url: 'https://yerd.app/reference/cli/coverage.md'
---
# Coverage

`yerd coverage` runs your **default** PHP version with the bundled
[pcov](../../guide/code-coverage) line-coverage driver enabled, then forwards
everything after the `coverage` subcommand verbatim to PHP. It is the discoverable
front door to the `phpcover` shim - the same coverage mechanism, but reachable
from `yerd --help` without the shim directory on your `PATH`.

Like `elevate`/`path`, it does **not** map to an IPC request: it `exec`s PHP
directly in your terminal (inheriting your stdin/stdout/stderr, arguments, and
exit code) rather than asking the daemon to do anything. (Attempting to route it
over IPC is an explicit usage error.)

```sh
yerd coverage [ARGS...]
```

| Command | Description |
| --- | --- |
| `yerd coverage [ARGS...]` | Run the default PHP version with pcov enabled, passing `ARGS` to PHP. |

```sh
yerd coverage artisan test --coverage         # Laravel / Pest / PHPUnit
yerd coverage vendor/bin/phpunit --coverage-text
yerd coverage -r 'var_dump(extension_loaded("pcov"));'   # prints bool(true)
```

The process exit code is PHP's own, so `yerd coverage` composes in CI exactly
like the interpreter it wraps.

## Pinning a version

`yerd coverage` always tracks your [global default](../../guide/php-versions#the-global-default)
version. To pin coverage to a specific version, use that version's cover shim
directly instead:

```sh
php8.4cover vendor/bin/pest --coverage
php8.5cover artisan test --coverage
```

## Passthrough behaviour

Everything after the `coverage` subcommand is handed straight to PHP, so flags
belong to your script or test runner, not to `yerd`:

* A **leading** `yerd coverage --help` (or `-h`) prints `yerd`'s own help for the
  command, because `--help` is `yerd`'s built-in flag. To forward `--help` to your
  script, put it after the script name: `yerd coverage artisan --help`.
* Every other flag - including `--version` and the global `--json` - is passed
  through to PHP. `yerd coverage` therefore produces PHP's output, never a JSON
  daemon response, and `--json` has no effect. This is the one command where the
  "`--json` on every command" note in the [overview](./) does not apply.

## Failure modes

* If the resolved default version has no published pcov build for your OS and
  architecture yet, `yerd coverage` reports that pcov isn't installed for that
  version rather than running without coverage. The background fetch is
  best-effort and never blocks a PHP install.
* **No legacy support.** pcov is not built for [legacy PHP versions](../../guide/php-versions#legacy-php-versions)
  (7.4 / 8.0 / 8.1, PHP < 8.2). `yerd coverage`, `phpcover`, and the versioned
  `php7.4cover` / `php8.0cover` / `php8.1cover` shims all error on a legacy
  version rather than run.
* **Unix only.** Coverage is available on macOS and Linux; it is not generated on
  other platforms.

## See also

* [Code Coverage guide](../../guide/code-coverage) - how pcov is bundled and how the cover shims work.
* [PHP](./php) - installing versions and setting the global default that `yerd coverage` tracks.

---

---
url: 'https://yerd.app/reference/cli/tooling.md'
---
# Tooling

Yerd installs developer tools - **Composer**, **Node.js** (`node`/`npm`/`npx`),
**Bun** (`bun`/`bunx`), the **Laravel installer** (`laravel`), and **WP-CLI**
(`wp`) - as self-contained binaries on your `PATH`. Each is identified by a
short `id`: `composer`, `node`, `bun`, `laravel`, or `wp-cli`. The
[Tooling guide](../../guide/tooling) covers the model in depth; this page is the
command reference.

::: info Latest only
Yerd installs the latest stable release of each tool (latest **LTS** for Node).
There is no per-version selection - installing again updates to the current
latest. Installing your first tool from the CLI **automatically adds** Yerd's bin
directory to your `PATH`; you can also manage it yourself with
[`yerd path install`](#path-setup). If the bin directory isn't on your `PATH`,
[`yerd doctor`](./diagnostics) flags it with the one-line fix.
:::

## Listing

| Command | Description |
| --- | --- |
| `yerd tools` | List every tool: install status, installed version, and the commands it provides. |

```sh
yerd tools
```

```text
TOOL      STATUS          COMMANDS       LOCATION
composer  2.10.1          composer       -
node      external        node,npm,npx   /opt/homebrew/bin/node
bun       not installed   bun,bunx       -
```

`LOCATION` is only populated for `external` tools - ones already on your
`PATH` from somewhere other than Yerd (Homebrew, `nvm`/`fnm`, a global
Composer, …). See the [Tooling guide](../../guide/tooling#external-tools) for
what that means and why there's no install/update action for them.

Add `--json` for machine-readable output.

## Installing & updating

| Command | Description | Example |
| --- | --- | --- |
| `yerd install tool <ID>` | Install the tool's latest version, then expose its commands on `PATH` - a **verified release download** for `node` / `bun` / `composer`, or a **Composer build** (`create-project`) for `laravel` / `wp-cli`. **Idempotent** - run again to update to the current latest. | `yerd install tool node` |
| `yerd uninstall tool <ID>` | Remove the tool's files and its `PATH` commands. | `yerd uninstall tool bun` |

```sh
yerd install tool composer    # PHP dependency manager (needs a PHP version)
yerd install tool node        # latest Node LTS - node, npm, npx
yerd install tool bun         # bun + bunx
yerd install tool laravel     # the laravel new installer (needs Composer)
yerd install tool wp-cli      # the wp command for WordPress (needs Composer)
yerd install tool node        # run again to update to the newest LTS
yerd uninstall tool bun       # remove bun and prune its shims
```

`<ID>` is one of `composer`, `node`, `bun`, `laravel`, or `wp-cli`. An unknown
id returns a `not_found` error.

::: warning Composer requires PHP
`composer` runs under Yerd's managed PHP, so install at least one
[PHP version](./php) first. Node and Bun are standalone. The Laravel installer
and WP-CLI are Composer packages, so they also need Yerd's own Composer
installed first.
:::

::: tip WP-CLI has no phar self-update
Yerd's `wp-cli` is a Composer install, so WP-CLI's own `wp cli update`
subcommand isn't applicable and will error - run `yerd install tool wp-cli`
again instead to update.
:::

## PATH setup

The tool commands live in Yerd's `{data}/bin` directory. Manage your shell's
`PATH` entry for it with `yerd path`:

| Command | Description |
| --- | --- |
| `yerd path install` | Add `{data}/bin` to your shell startup file (idempotent; covers zsh, bash, and fish). |
| `yerd path uninstall` | Remove the Yerd `PATH` block from your shell startup file. |
| `yerd path print` | Print the shell snippet without modifying any file (for `eval` / manual use). |

```sh
yerd path install     # then open a new terminal
```

## Exit codes

These commands follow the standard CLI [exit codes](./#exit-codes): `0` on
success, `1` on a daemon error (e.g. an unknown tool id, a failed download, or a
checksum mismatch), and `69` if the daemon is unreachable.

## See also

* [Tooling guide](../../guide/tooling) - the full model and where files live.
* [PHP reference](./php) - the version model these tools follow.
* [Services reference](./services) - the same install-on-demand approach.

---

---
url: 'https://yerd.app/reference/cli/services.md'
---
# Services

Yerd installs and supervises local database, cache, and search engines as native,
per-user processes - no Docker. Each engine is identified by a short `id`:
`redis`, `mysql`, `mariadb`, `postgres`, or `meilisearch`. The [Services & Databases
guide](../../guide/services) covers the model in depth; this page is the command
reference. For creating and managing the databases *inside* a SQL engine, see
[Databases](./db).

::: info Redis is Valkey
The `redis` slot is served by **Valkey** (the BSD-licensed, wire-compatible fork).
It is displayed as `Redis (Valkey)` and your clients are unaffected.
:::

## Listing

| Command | Description |
| --- | --- |
| `yerd services` | List every known service: installed version, run state (running / stopped / failed), port, and whether it hosts databases. |
| `yerd service available` | List the versions installable from Yerd's hosted distribution for your platform, tagging any already installed. |

```sh
yerd services             # what's installed and running
yerd service available    # what you could install
```

## Installing & versioning

| Command | Description | Example |
| --- | --- | --- |
| `yerd service install <SVC> <VERSION>` | Download and install a service build, then start and enable it. | `yerd service install redis 8` |
| `yerd service change-version <SVC> <VERSION>` | Switch an installed service to a different version (the data directory is kept). | `yerd service change-version postgres 16.2` |
| `yerd service uninstall <SVC> <VERSION> [--purge]` | Remove an installed version. Add `--purge` to also delete the engine's stored data (destructive). | `yerd service uninstall mysql 8.4 --purge` |

```sh
yerd service install redis 8           # install + start + enable
yerd service change-version redis 8.1  # upgrade in place, keep data
yerd service uninstall redis 8         # remove binaries, keep data
yerd service uninstall redis 8 --purge # remove binaries AND data
```

::: warning `--purge` deletes data
Without `--purge`, uninstalling keeps the data directory so a later reinstall
picks up where you left off. With `--purge` the engine's stored data is deleted -
there is no undo.
:::

::: info PostgreSQL has a `full` (PostGIS) variant
`postgres` publishes two builds per major: the lean base (`17`) and a PostGIS
build (`17-full`). Install either by its label, e.g.
`yerd service install postgres 17-full`. The two are separate installs that
**share one data directory** (pinned to the numeric major), so `change-version`
between them preserves your databases; see
[PostgreSQL: base and PostGIS builds](../../guide/services#postgresql-base-and-postgis-full-builds)
for the extension lists, the shared-datadir behaviour, and the GPL posture of
`full`.
:::

## Lifecycle

| Command | Description |
| --- | --- |
| `yerd service start <SVC>` | Start the service now. |
| `yerd service stop <SVC>` | Stop the service for the current session. Installed engines auto-start again on the next daemon start; `uninstall` to keep one off. |
| `yerd service restart <SVC>` | Restart the running service. |

```sh
yerd service start postgres
yerd service stop postgres
yerd service restart postgres
```

## Configuration

| Command | Description | Example |
| --- | --- | --- |
| `yerd service set-port <SVC> <PORT>` | Set the loopback port the service listens on. Applies on the next start/restart. | `yerd service set-port redis 6380` |
| `yerd service logs <SVC> [--lines <N>]` | Print the tail of the service's log. `--lines` defaults to 100. | `yerd service logs mysql --lines 200` |

```sh
yerd service set-port redis 6380
yerd service logs mysql              # last 100 lines
yerd service logs mysql --lines 50
```

Default ports: Redis `6379`, MySQL / MariaDB `3306` (they share the port, so only
one can be enabled on it at a time), PostgreSQL `5432`, Meilisearch `7700`.

## See also

* [Services & Databases guide](../../guide/services) - the supervision model and posture
* [Databases](./db) - creating, dropping, backing up databases inside a SQL engine
* [Configuration Reference](../configuration) - the `[services.<id>]` config tables
* [yerd-services](../../developer/crates/yerd-services) - the crate behind these commands

---

---
url: 'https://yerd.app/reference/cli/db.md'
---
# Databases

The `yerd db` commands manage the databases *inside* a running SQL service. They
apply to the SQL engines only - `mysql`, `mariadb`, and `postgres`. (Redis is a
cache and has no SQL databases.) To install, start, or stop the engines
themselves, see [Services](./services).

::: tip The engine must be running
Every `yerd db` command connects to a live server, so the target service must be
installed and started first (`yerd service start <svc>`). Database operations need
no elevation - they connect over the local socket / loopback as a passwordless
local-dev superuser.
:::

## Commands

| Command | Description |
| --- | --- |
| `yerd db list <SVC>` | List the databases in the service (system databases are filtered out). |
| `yerd db create <SVC> <NAME>` | Create a new database. |
| `yerd db drop <SVC> <NAME>` | Drop a database (irreversible). |
| `yerd db backup <SVC> <NAME> <FILE>` | Dump a database to a plain-SQL file. |
| `yerd db restore <SVC> <NAME> <FILE>` | Restore a database from a plain-SQL file. |

```sh
yerd db create mysql my_app
yerd db list mysql
yerd db backup mysql my_app ./my_app.sql
yerd db restore mysql my_app ./my_app.sql
yerd db drop mysql my_app
```

## Database names

`create` uses Yerd's portable naming policy. The daemon validates the name before
building SQL. A newly created name must:

* be non-empty and at most **63 characters** (the lowest limit across the engines);
* start with an ASCII letter or underscore (`_`);
* contain only letters, digits, and underscores.

For `drop`, `backup`, and `restore`, the name identifies a database that already
exists. Those operations accept engine-valid names exactly as listed, including
whitespace, punctuation, Unicode, quotes, backticks, periods, and leading hyphens.
Only empty names and names containing NUL are rejected. SQL identifiers are quoted
and escaped per engine, and backup/restore names are passed directly as one process
argument without a shell.

::: warning System databases are protected
Engine-internal databases (`mysql`, `information_schema`, `performance_schema`,
`sys`, `postgres`, `template0`, `template1`) are filtered from `db list` and
cannot be dropped or restored over.
:::

## Backup & restore

`backup` runs the engine's dump tool (`mysqldump`, `mariadb-dump`, or `pg_dump`)
and writes plain SQL. The output is streamed to a temporary file next to the
destination and atomically renamed into place, so a failed dump never truncates an
existing file. A relative `<FILE>` resolves against the current directory.

`restore` replays a plain-SQL file back into an existing database through the
engine's interactive client (`mysql`, `mariadb`, or `psql`) - so the target
database must already exist (`yerd db create` it first if needed).

```sh
# round-trip a database
yerd db create postgres shop
yerd db restore postgres shop ./shop.sql
yerd db backup postgres shop ./shop-$(date +%F).sql
```

## See also

* [Services](./services) - installing and supervising the engines
* [Services & Databases guide](../../guide/services) - the full model
* [yerd-services](../../developer/crates/yerd-services) - `database.rs`, the pure SQL-admin boundary

---

---
url: 'https://yerd.app/reference/cli/mail.md'
---
# Mail

The `yerd mail` commands inspect emails captured by Yerd's built-in mail-capture
SMTP server. The server runs inside the [`yerdd` daemon](../../guide/daemon),
enabled by default on `127.0.0.1:2525`; point an app's mailer at it and every
message it sends is stored locally for inspection. The [Mail Capture
guide](../../guide/mail) covers the model and how to wire an app up; this page is
the command reference.

::: info Captured mail is local-only
The capture server is a sink, not a relay - nothing is ever forwarded. Stored mail
stays listable and clearable even when capture is disabled, so these commands work
regardless of whether the listener is currently bound.
:::

## Commands

| Command | Description |
| --- | --- |
| `yerd mail list` | List captured emails (newest first). |
| `yerd mail show <ID>` | Show one captured email's headers and body. |
| `yerd mail clear` | Delete every captured email. |

```sh
yerd mail list
yerd mail show 000003
yerd mail clear
```

## `yerd mail list`

Prints a tab-separated table of every captured email, **newest first**, with three
columns: `ID`, `FROM`, and `SUBJECT`.

```sh
yerd mail list
# ID      FROM                        SUBJECT
# 000003  Example <hi@example.com>    Password Reset
# 000002  shop@acme.test              Your order shipped
# 000001  no-reply@acme.test          Welcome
```

* The `ID` is a zero-padded, monotonic counter (the on-disk `<id>.eml` stem). Ids
  are never reused - not even after `clear` - so an id always refers to the same
  message for as long as it's retained.
* A message with no subject is shown as `(no subject)`.
* Tabs, carriage returns, and newlines inside a header are flattened to spaces so a
  folded or multi-line header can't break the table.
* When nothing has been captured, the command prints `no captured emails`.

## `yerd mail show <ID>`

Shows one captured email by id. The `<ID>` is the value from the `ID` column of
`yerd mail list`.

```sh
yerd mail show 000003
# From:    Example <hi@example.com>
# To:      you@app.test
# Subject: Password Reset
#
# Your OTP is 416063.
```

Output is the `From:`, `To:`, and `Subject:` headers, a blank line, then the
message's decoded **text body**. The bodies are already MIME-decoded (charset and
transfer-encoding handled).

| Message content | What `show` prints |
| --- | --- |
| Has a plain-text body | The decoded text body. |
| HTML only (no text part) | `(HTML-only message - open it in the GUI viewer)` |
| Neither body | `(empty message)` |

::: tip HTML bodies render in the desktop app
The CLI deliberately doesn't dump raw HTML. To read an HTML-only message - with
inline images and all - open it in the **Mail** view of the [desktop
app](../../guide/desktop-app), which renders it in a sandboxed viewer.
:::

## `yerd mail clear`

Deletes **every** captured email and prints `ok`.

```sh
yerd mail clear
```

This removes all stored `.eml` files. The id counter is **not** reset, so a later
capture never reuses the id of a cleared message.

::: warning No per-message delete from the CLI
`yerd mail clear` is all-or-nothing. To remove individual messages, use the
**Mail** view in the [desktop app](../../guide/desktop-app).
:::

## JSON output

Every command accepts the global `--json` flag for machine-readable output:

```sh
yerd mail list --json          # {"type":"mails","mails":[ ... ]}
yerd mail show 000003 --json   # {"type":"mail","mail":{ ... }}
```

`yerd mail list --json` prints the IPC response envelope
`{"type":"mails","mails":[ ... ]}`, where each element of `mails` is one captured
email's metadata (`id`, `from`, `to`, `subject`, `date_epoch`, `read`). `yerd mail
show <id> --json` prints `{"type":"mail","mail":{ ... }}`, where `mail` is the full
decoded message, including all `headers`, both the `html_body` and `text_body`
(whichever the message carries), and `attachments` when the message has
non-inline file parts (omitted when empty). `date_epoch` is the message `Date:`
as Unix epoch seconds, or `0` when absent/unparseable.

## See also

* [Mail Capture guide](../../guide/mail) - what capture is and how to point an app at it
* [Configuration Reference](../configuration) - the `[mail]` table (`enabled`, `port`)
* [yerd-mail](../../developer/crates/yerd-mail) - the crate behind these commands

---

---
url: 'https://yerd.app/reference/cli/mcp.md'
---
# MCP

`yerd mcp` serves Yerd's tools to AI agents over the [Model Context
Protocol](https://modelcontextprotocol.io). The [AI Agents
guide](../../guide/ai-agents) covers enabling it and registering it with your
agent; this page is the command reference.

::: info You don't run this by hand
An agent spawns `yerd mcp` and talks to it over the pipe. Run it in a terminal
and it just sits there waiting for JSON-RPC on stdin - useful only for debugging.
:::

## Commands

| Command | Description |
| --- | --- |
| `yerd mcp` | Serve one MCP session on stdin/stdout until the client disconnects. |

Register it once, rather than running it:

```sh
claude mcp add --scope user yerd -- yerd mcp
```

## `yerd mcp`

Takes no arguments.

Speaks MCP over **stdio**: newline-delimited JSON-RPC 2.0 in on stdin, one
message per line out on stdout. Each tool call is forwarded to the
[`yerdd` daemon](../../guide/daemon) over the same IPC socket the rest of the CLI
uses, so an agent sees exactly the state `yerd` and the app see.

* **stdout carries the protocol only.** Every log line and diagnostic goes to
  stderr, so it never corrupts the stream.
* **Exit code is `0`** on a clean disconnect (EOF on stdin), which is the normal
  way a session ends when the agent shuts down.
* **The daemon does not have to be running** when the session starts. Tool calls
  made while it is down come back as failed tool results explaining that Yerd
  needs starting, rather than killing the session.

### Gating

Tools are served only when **AI Agents** is enabled in Yerd's General settings
(the `mcp_enabled` config key). The gate is read from the daemon, not from the
config file directly:

* **Enabled** - tools run.
* **Disabled** - the session still connects and lists its tools, and each call
  returns a failed result telling the agent to ask you to enable it. The
  handshake deliberately succeeds: a server that failed to start would look
  broken rather than switched off.
* **Unknown** (the daemon was unreachable at startup) - the session reports that
  it could not check, rather than claiming the feature is off.

While a session is not enabled it re-checks the setting on each tool call, so
turning the toggle on reaches a running agent immediately. Once a session is
serving, it stops checking - turning the toggle off does not interrupt work in
progress, and applies to sessions started afterwards.

### Protocol support

| Item | Value |
| --- | --- |
| Transport | stdio (newline-delimited JSON-RPC 2.0) |
| Protocol revisions | `2025-11-25` (offered), `2025-06-18`, `2025-03-26`, `2024-11-05` |
| Capabilities | `tools` |
| Methods | `initialize`, `ping`, `tools/list`, `tools/call` |

The client's requested revision is echoed back when Yerd supports it; otherwise
Yerd offers its newest and the client decides whether to proceed. Batched
(JSON array) requests are rejected - batching was removed from MCP in
`2025-06-18`, and no stdio client sends them.

## See also

* [AI Agents](../../guide/ai-agents) - enabling the server, the tool list, and troubleshooting.
* [Daemon control](./daemon) - the daemon each tool call is forwarded to.

---

---
url: 'https://yerd.app/reference/cli/lan.md'
---
# LAN sharing&#x20;

::: info Beta feature
LAN sharing is new and still settling. If you hit a problem, please
[report it on GitHub](https://github.com/forjedio/yerd/issues/new) - include your
OS, `yerd lan status` output, and what you expected.
:::

By default Yerd serves your `.test` sites only to the machine they run on -
every listener binds `127.0.0.1`. `yerd lan` opts into exposing them to **other
devices on your local network** (a phone, a tablet, another laptop) over the same
ports 80/443, and `yerd remote-setup` provisions a device so it trusts Yerd's CA
and resolves `.test`.

::: warning This exposes your dev sites to the network
LAN sharing binds the web proxy and DNS responder to `0.0.0.0`, so anything that
can route to your machine can reach your sites (subject to the peer filter and
your host firewall). It is opt-in and off by default. Turn it off with
`yerd lan disable` when you're done. Don't enable it on an untrusted network.
:::

## Commands

| Command | Description |
| --- | --- |
| `yerd lan enable` | Expose `.test` sites to the LAN, then restart the daemon to re-bind. |
| `yerd lan disable` | Return to loopback-only, then restart the daemon. |
| `yerd lan status` | Show configured-vs-effective state, the LAN IP, and the next step. |
| `yerd remote-setup` | Mint a one-time command to provision another device. |

## How it works

* **The web proxy and DNS responder bind `0.0.0.0`** while LAN mode is on. A
  peer filter drops any connection whose source address isn't private
  (RFC 1918 / link-local / loopback) - a blast-radius reducer, **not**
  authentication, so a host firewall is still recommended.
* **DNS answers split-horizon.** Your own machine keeps resolving `.test` to
  `127.0.0.1`; other LAN devices get your machine's LAN IP. IPv6 (`AAAA`) is not
  served in LAN mode.
* **Databases, mail capture, dumps, and the IPC socket stay loopback-only.** Only
  the web + DNS + the bootstrap endpoint leave loopback.
* Enabling or disabling **restarts the daemon** (a listen socket's bind address
  is fixed when it's opened), so the change is enforced, not merely saved.

## Privileged setup for ports 80/443

LAN devices expect the well-known ports. Binding them needs a one-time,
per-machine privileged step - the same mechanism as ordinary Yerd use:

* **macOS:** run `sudo yerd elevate ports` (if you haven't already) **and**
  `sudo yerd elevate lan`. The first installs the loopback redirect for on-host
  access; the second installs a `pf` redirect that carries inbound LAN 80/443 to
  Yerd on your LAN IP. Remove the LAN rule later with `sudo yerd unelevate lan`.
* **Linux:** run `sudo yerd elevate ports` once (it grants
  `cap_net_bind_service`, which covers the `0.0.0.0` bind). No separate LAN step.

`yerd lan status` tells you whether these are in place.

## Firewall

Yerd does not configure your firewall. Allow these from your LAN subnet only:

| Port | Protocol | Purpose |
| --- | --- | --- |
| 80, 443 | TCP | web proxy |
| 1053 | UDP + TCP | `.test` DNS responder (or your configured `dns_port`) |
| 7073 | TCP | remote-setup bootstrap (or your configured `lan_setup_port`) |

Example (`ufw`, replace the subnet):

```sh
sudo ufw allow from 192.168.1.0/24 to any port 80,443,7073 proto tcp
sudo ufw allow from 192.168.1.0/24 to any port 1053
```

::: info IPv6
Yerd binds only IPv4 (`0.0.0.0`) listeners, so there is nothing to reach over
IPv6 today. Note only that IPv4 firewall rules don't cover IPv6 in general.
:::

## Provisioning a device — `yerd remote-setup`

A remote device needs two things to use your `.test` sites: it must **trust
Yerd's CA** (for HTTPS) and **resolve `.test`** to your machine. `yerd
remote-setup` prints a command that does both. It only works while LAN mode is
up.

```sh
$ yerd remote-setup
Run this on the OTHER device (needs sudo, curl, and openssl):

  curl -fsS --retry 3 -o yerd-setup.sh 'http://192.168.1.42:7073/remote-setup?code=…' && [ "$(openssl dgst -sha256 -r yerd-setup.sh | cut -d' ' -f1)" = "<sha256>" ] && sudo bash yerd-setup.sh
```

It is a single line: download the self-contained installer, check its SHA-256
matches, then run it. The installer embeds Yerd's CA, so there is nothing else to
fetch.

::: danger The hash is the trust anchor - verify it
The installer is served over plain HTTP, so its integrity comes entirely from the
**SHA-256 printed on your screen**. The pasted command checks the download
against that hash and, on any mismatch, the `&&` chain stops before `sudo` runs.
The hash travels by your eyes, not the wire - that's what makes this safe. Do not
edit it out. The code is single-use and expires in 15 minutes.
:::

Supported devices: **macOS** and **Linux with dnsmasq or NetworkManager**. A
Linux box using **systemd-resolved alone** is not supported (it can't forward a
single domain to a custom port) - install dnsmasq or use NetworkManager. On
Linux the CA is installed into whichever trust anchor directory the distro
provides (Debian/Ubuntu, RHEL/Fedora or Arch) **and** into the desktop user's NSS
databases, so Firefox, Chromium and Brave trust it too (best-effort, when
`certutil` from `nss` / `libnss3-tools` is present).

**Windows devices are not supported.** Windows has no built-in way to forward a
single domain to a nameserver on a non-standard port - its NRPT rules
(`Add-DnsClientNrptRule`) take a server address but no port, and the `hosts`
file can't express a wildcard. Pointing a Windows box at Yerd needs a local DNS
proxy (such as Acrylic) configured by hand, so there is no bootstrap script for
it.

### Undoing it on a device

Yerd can't revert a device it doesn't control. On each provisioned device, run
the installer's uninstall mode to remove the CA (system store and browser NSS
databases) and the resolver entry:

```sh
sudo bash yerd-setup.sh uninstall
```

## Headless / always-on hosts

If you share from a machine you don't stay logged into, enable a persistent user
session so `yerdd` keeps running (Linux):

```sh
sudo loginctl enable-linger "$(whoami)"
```

See the [daemon guide](./daemon) for details.

## Turning it off

```sh
yerd lan disable
```

This restarts the daemon back onto loopback. On macOS the `pf` LAN redirect is
separate privileged state - `yerd lan status` flags it as residual until you run
`sudo yerd unelevate lan`. A full `yerd uninstall` removes it too.

---

---
url: 'https://yerd.app/reference/cli/tunnel.md'
---
# Tunnel

The `yerd tunnel` commands publish a local site to the public internet through
[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
(`cloudflared`). The connection is outbound-only - no inbound ports, no `sudo`.
The [Sharing Sites guide](../../guide/sharing) covers the model and the two tiers
(quick tunnels and named tunnels); this page is the command reference.

::: info cloudflared is detected on PATH, or downloaded on demand
The first share needs the `cloudflared` binary. Yerd looks for one already on
your `PATH` first and uses it if it's version 2023.3.0 or newer; otherwise
`yerd tunnel install` fetches the official static build (checksum-verified) into
the daemon's data directory - it is not bundled and never touches your system
unless you already had a compatible `cloudflared` installed. Quick share needs no
Cloudflare account; named tunnels need a one-time `yerd tunnel login`.
:::

## Commands

| Command | Description |
| --- | --- |
| `yerd tunnel install` | Download the `cloudflared` binary (required before sharing). |
| `yerd tunnel share <SITE>` | Share a site via a Quick Tunnel (random `*.trycloudflare.com` URL). |
| `yerd tunnel stop <SITE>` | Stop sharing a site. |
| `yerd tunnel status` | Show live tunnels and `cloudflared` install status. |
| `yerd tunnel login` | Log in to a Cloudflare account (opens a browser) for named tunnels. |
| `yerd tunnel create <NAME>` | Create a named tunnel on the logged-in account. |
| `yerd tunnel delete <NAME>` | Delete a named tunnel and forget it locally. |
| `yerd tunnel list` | List the named tunnel, exposed sites, and authorized domain. |
| `yerd tunnel route <TUNNEL> <HOSTNAME>` | Create the proxied DNS record for a hostname. |
| `yerd tunnel set-host <SITE> [HOSTNAME] [--clear]` | Set or clear a site's public hostname. |
| `yerd tunnel publish` | Start the named tunnel, exposing every site with a hostname set. |
| `yerd tunnel unpublish` | Stop the named tunnel (takes every named site offline). |

```sh
yerd tunnel install
yerd tunnel share app
yerd tunnel status
yerd tunnel stop app
```

## Quick tunnels

### `yerd tunnel install`

Downloads and installs `cloudflared`. Idempotent; safe to re-run. Needed once
before any share, unless a compatible `cloudflared` is already on `PATH` (see
above). Re-running it always switches Yerd back to the managed copy, even if a
`PATH` binary was previously in use.

### `yerd tunnel share <SITE>`

Publishes `<SITE>` (a site name like `app`, or its host `app.test`) at a random
`https://<name>.trycloudflare.com` URL and prints it. The URL is temporary - it
changes on the next share and is torn down on `stop` or daemon shutdown. Requires
`cloudflared` to be installed.

### `yerd tunnel stop <SITE>`

Tears down the site's tunnel. No-op if it isn't shared.

### `yerd tunnel status`

Lists live tunnels (site, kind, state, URL/hostname) and whether `cloudflared` is
installed and logged in, plus its version and source: `managed` (Yerd's own
download) or `system` (found on your `PATH`) in `--json` output.

## Named tunnels

Named tunnels serve a stable hostname on a domain you manage in Cloudflare. They
use one consolidated tunnel for every exposed site.

### `yerd tunnel login`

Opens a browser to authorize Yerd for a Cloudflare zone. The account certificate
is stored in the daemon's data directory. Run once per machine.

### `yerd tunnel create <NAME>`

Creates a named tunnel on the logged-in account and records it locally. Yerd
supports one named tunnel at a time; `delete` the existing one before creating a
differently-named tunnel.

### `yerd tunnel set-host <SITE> [HOSTNAME] [--clear]`

Maps `<SITE>` to a public `HOSTNAME` on your authorized domain: it creates the
proxied DNS record and records the mapping so the consolidated tunnel serves it.
`HOSTNAME` is **required unless** `--clear` is given - `--clear` removes the
site's mapping (and the two are mutually exclusive, so forgetting the hostname
can't silently clear it).

```sh
yerd tunnel set-host app app.example.com
yerd tunnel set-host app --clear
```

### `yerd tunnel publish` / `yerd tunnel unpublish`

`publish` (re)starts the consolidated named tunnel, serving every site that has a
hostname set. `unpublish` stops it, taking all named sites offline. Both require
login and a created tunnel.

### `yerd tunnel route <TUNNEL> <HOSTNAME>`

Creates the proxied CNAME routing `HOSTNAME` to `TUNNEL` on your Cloudflare zone.
`set-host` does this for you; `route` is the lower-level primitive.

### `yerd tunnel list`

Shows the recorded named tunnel, the per-site hostname mappings that are exposed,
and the **authorized domain** resolved from your account.

### `yerd tunnel delete <NAME>`

Deletes the named tunnel from your Cloudflare account and forgets it locally:
stops the process, removes the credentials, and clears the exposed-site mappings.
Only the one configured tunnel may be deleted. The DNS records created by
`set-host`/`route` remain on your account - remove them in the Cloudflare
dashboard if you no longer want them.

::: tip Desktop app
The desktop app's **Share** page (under **Integrations**) drives all of this with
a searchable site picker, a per-site expose toggle, and automatic start/stop. See
the [Sharing Sites guide](../../guide/sharing).
:::

---

---
url: 'https://yerd.app/reference/cli/diagnostics.md'
---
# Status & Diagnostics

| Command | Description | Example |
| --- | --- | --- |
| `yerd ping` | Check that the daemon is alive (prints `pong`). | `yerd ping` |
| `yerd status` | Show a snapshot of daemon, proxy, DNS, ports, CA, and PHP health. | `yerd status` |
| `yerd doctor` | Diagnose common problems and report findings. | `yerd doctor` |
| `yerd doctor fix` | Attempt safe, unprivileged repairs (e.g. restart a crashed FPM pool). | `yerd doctor fix` |

```sh
yerd ping            # pong, if the daemon is up
yerd status          # one-screen health snapshot
yerd doctor          # report problems and remedies
yerd doctor fix      # apply safe automatic fixes, then list what still needs you
```

`yerd status` reports the daemon PID, uptime and RSS, version, TLD, the bound HTTP/HTTPS ports (flagging rootless fallback or an active macOS pf redirect), the DNS responder address, CA trust state and path, resolver install state, load average, site counts, and a per-version PHP pool listing (state, PID, listen socket, RSS, available update).

`yerd doctor` prints each finding with a severity mark (`✓` ok, `⚠` warn, `✗` fail), a detail line, and a `→` remedy where one exists. `yerd doctor fix` first lists what it applied, then what still needs manual attention.

One such finding is `DomainShadowed` (a `Warn`): two sites claim the same domain, so one site's apex is shadowed by the other. The remedy is to `yerd domain remove` the duplicate or `yerd domain primary` the shadowed site onto a free domain.

::: info Exit codes for diagnostics
`yerd doctor` (and `yerd doctor fix`) exit `1` if any finding is `Fail` severity, otherwise `0`. A `Warn` alone does **not** fail the exit code. This holds in both human and `--json` modes, so doctor is safe to use in CI gates.

If the daemon is unreachable, `yerd doctor` is special-cased: instead of the generic "daemon unreachable" error, it surfaces a synthetic `Daemon not running` **Fail** finding and exits `1`, so a down daemon shows up as a doctor failure, consistently across `--json` and the exit code.
:::

See the [Diagnostics guide](../../guide/diagnostics) for an explanation of each check.

---

---
url: 'https://yerd.app/reference/cli/elevation.md'
---
# Elevation

`elevate` and `unelevate` perform one-shot OS-level privilege setup and must be run with `sudo`. Unlike every other command, they do **not** map to a single IPC request: the CLI fetches read-only facts from your running daemon, then spawns the audited `yerd-helper` for each privileged operation. (Attempting to route them over IPC is an explicit usage error.)

| Command | Description |
| --- | --- |
| `sudo yerd elevate [TARGET]` | Grant yerd OS-level privileges. No target = grant all. |
| `sudo yerd unelevate [TARGET]` | Revert what `elevate` configured. No target = revert all. |

## Targets

| Target | Description |
| --- | --- |
| `trust` | Trust the local CA in the OS system store. |
| `resolver` | Route `*.<tld>` queries to yerd's DNS responder. |
| `ports` | Allow the daemon to bind privileged ports 80/443. |
| `lan` | Reach 80/443 from **other devices** on the LAN (see [LAN sharing](./lan)). |

```sh
sudo yerd elevate            # grant all three, in order: trust -> resolver -> ports
sudo yerd elevate trust      # just trust the local CA
sudo yerd elevate resolver   # just route *.test to the yerd DNS responder
sudo yerd elevate ports      # just allow binding 80/443
sudo yerd elevate lan        # allow LAN devices to reach 80/443 (after `yerd lan enable`)
sudo yerd unelevate          # revert everything
sudo yerd unelevate trust    # just untrust the CA
sudo yerd unelevate lan      # remove the LAN redirect (macOS)
```

With no target, `elevate`/`unelevate` apply **only** the core three in the order `trust -> resolver -> ports`. `lan` is separate and opt-in - it is **not** part of the no-target "all", and you run it only after `yerd lan enable`, so `unelevate` with no target does not remove the LAN redirect. A full [`yerd uninstall`](./uninstall) does additionally tear down the LAN pf redirect and its state, so nothing is left behind after a complete uninstall.

::: warning Platform differences

* **Linux:** `ports` is a one-time `setcap cap_net_bind_service` grant on `yerdd`. After granting it, restart the daemon for 80/443 to take effect. There's no clean reverse operation, so `unelevate ports` only prints the manual `setcap -r` command rather than running it. Package upgrades reset `setcap`, so re-run `elevate ports` afterwards. `lan` reuses the same `setcap` grant (a wildcard bind needs the same capability), so on Linux `elevate lan` is equivalent to `elevate ports`.
* **macOS:** `ports` installs a `pf` redirect mapping 80 to the daemon's rootless HTTP port and 443 to its HTTPS port. It's live immediately (no daemon restart) and `unelevate ports` removes the redirect. `lan` installs a **separate** `pf` redirect (on your LAN IP) so other devices reach 80/443; it requires `ports` as a prerequisite for on-host access, and `unelevate lan` removes just the LAN rule.

On a host where a target isn't supported (for example `resolver` without systemd-resolved or NetworkManager), that step is **skipped**, not failed, and guidance is printed. NetworkManager support requires `dnsmasq` and `nmcli`.
:::

`sudo yerd uninstall` reverts all three of these (it runs the same `unelevate`) as part of removing yerd entirely - see [Uninstall](./uninstall). When removing a CA from the trust store, `yerd-helper` first confirms the matched certificate is Yerd's own (Subject CN `Yerd Local CA`) and refuses otherwise, so a mistaken fingerprint can't delete an unrelated trusted root.

The [Elevation & Privileges guide](../../guide/elevation) explains the security model and the `yerd-helper` boundary in detail.

---

---
url: 'https://yerd.app/reference/cli/daemon.md'
---
# Daemon control

| Command | Description | Example |
| --- | --- | --- |
| `yerd restart daemon` | Restart the daemon itself. | `yerd restart daemon` |

```sh
yerd restart daemon
```

::: warning
`yerd restart daemon` briefly interrupts all sites, and this command itself, since it's a client of the daemon it's restarting.
:::

There is no `yerd start`/`yerd stop` subcommand: the daemon's lifecycle is managed by your OS (and started on demand). See [The Daemon](../../guide/daemon) for how `yerdd` is launched and supervised, and the [yerdd binary page](../../developer/binaries/yerdd) for internals.

`yerd update --yes` (see [Self-Update](./update)) also restarts the daemon, as the final step of installing a new Yerd version - that restart goes through the same OS service mechanics as `restart daemon`, not a fresh `yerdd` process started from scratch.

---

---
url: 'https://yerd.app/reference/cli/update.md'
---
# Self-Update

The bare `yerd update` command (no subcommand) checks for, and optionally
installs, a newer version of Yerd itself. `yerd update php` is a different
command that updates an installed PHP version - see [PHP](./php).

| Command | Description |
| --- | --- |
| `yerd update` | Check for a newer Yerd on your configured channel and report it. Installs nothing. |
| `yerd update --yes` | Check, then download, verify, and install the update, and restart the daemon. |
| `yerd update --edge` / `--stable` | Check (or, with `--yes`, apply) against the edge or stable channel for this run. |
| `yerd update --edge --yes` / `--stable --yes` | Also persist the given channel as your saved default. |
| `yerd update --yes --force` | Allow a downgrade (e.g. moving from a newer pre-release back to stable). |

```sh
yerd update                    # check only, using your saved channel
yerd update --edge              # check against edge, without changing your saved channel
yerd update --yes               # check and install on your saved channel
yerd update --edge --yes        # switch to (and install from) the edge channel
```

## Channels

Yerd ships two release channels, persisted as `update_channel` in
[`yerd.toml`](../configuration) (`"stable"` by default):

* **`stable`** - the highest released version that isn't a pre-release.
* **`edge`** - the highest released version including pre-releases / release
  candidates.

`--edge`/`--stable` override the saved channel **for this invocation only**.
Add `--yes` and the override also becomes the new saved default - a
check-only run (no `--yes`) never touches your saved preference, but prints a
reminder that it's showing a channel other than the one it will use next time.

The stable channel never installs a **downgrade**: if you're running a
pre-release that is already newer than the latest stable, `yerd update --yes`
(without `--edge`) reports you're ahead of stable and stays put. `--force`
(which requires `--yes`) is the escape hatch for that case, though an
automated downgrade isn't implemented yet - it currently just says so.

## What `--yes` does

1. Persists the channel override, if `--edge`/`--stable` was given.
2. Asks the daemon to check the channel (`yerd_ipc::Request::CheckUpdate`). If
   nothing is available, it reports and exits `0` - no download happens.
3. Otherwise asks the daemon to download and verify the target release's
   artifact (`Request::StageUpdate`): the daemon fetches the platform-specific
   asset (macOS `.app.tar.gz`, Linux `.deb`/`.pkg.tar.zst`/`.rpm`), checks its
   SHA-256 against the release's `SHA256SUMS` manifest, and verifies a
   detached minisign signature (the `<artifact>.minisig` asset, with a legacy
   `<artifact>.sig` accepted as a fallback) against an embedded public key.
4. Re-verifies the signature a second time locally (closing the window
   between the daemon's verify and the install), then installs the artifact
   and restarts the daemon so it comes back up on the new version.

`--yes` is not compatible with `--json` - the apply path is interactive
progress output, not a single structured response.

::: warning Where Yerd must live
On macOS, self-update only works when Yerd is installed at
`/Applications/Yerd.app` and that location is writable by you. Installs
elsewhere (e.g. a dev build) are rejected with a clear error rather than
silently failing.
:::

## Platform support

| Platform | Install mechanism |
| --- | --- |
| macOS (Apple Silicon) | Extracts the `.app.tar.gz`, swaps it into `/Applications`, restarts the daemon via `launchctl kickstart -k`. |
| Linux (`.deb` build) | Reinstalls via `dpkg -i`, elevated with `pkexec` if needed; restarts the daemon via `systemctl --user restart` (or a stop/start fallback with no systemd user instance). |
| Linux (Arch `.pkg.tar.zst` build) | Reinstalls via `pacman -U`, same elevation and restart path as the `.deb` build. |
| Linux (Fedora `.rpm` build) | Reinstalls via `rpm -U --oldpackage`, same elevation and restart path as the `.deb` build. |
| Intel macOS, other platforms | No self-update artifact is published; `yerd update` reports nothing available. |

## See also

* [PHP](./php) - the unrelated `yerd update php [VERSION]` command.
* [Configuration Reference](../configuration) - the persisted `update_channel` key.
* [yerd-update](../../developer/crates/yerd-update) - the channel-resolution and artifact-selection/verification logic.
* [yerd-service-ctl](../../developer/crates/yerd-service-ctl) - the daemon restart step of the applier.
* [Daemon control](./daemon) - the separate `yerd restart daemon` command.

---

---
url: 'https://yerd.app/reference/cli/uninstall.md'
---
# Uninstall

`uninstall` has two shapes: remove a single **component**, or remove **yerd itself**.

| Command | Description |
| --- | --- |
| `yerd uninstall php <VERSION>` | Uninstall a PHP version (removes its files; blocked if a site uses it). See [PHP](./php). |
| `yerd uninstall tool <ID>` | Uninstall a dev tool (`composer`, `node`, `bun`). See [Tooling](./tooling). |
| `yerd uninstall` | **Full uninstall** - remove yerd entirely from this machine. |
| `yerd uninstall --yes`, `-y` | Full uninstall without the confirmation prompt (for scripts / the desktop app). |

The component forms (`php` / `tool`) are daemon-mediated and documented on their own pages. The rest of this page covers the **bare `yerd uninstall`** - the full self-uninstall.

## Full uninstall

`yerd uninstall` with no subcommand removes everything yerd put on the machine. It is **local** (it doesn't go through the daemon - it stops the daemon as part of the teardown) and it **prompts for confirmation** before touching anything.

```sh
sudo yerd uninstall          # recommended: also reverts the elevate system changes
yerd uninstall               # without root: removes everything except the elevate changes
yerd uninstall --yes         # skip the prompt (non-interactive)
```

It removes, in order:

1. **System changes from [`elevate`](./elevation)** - the CA in the system trust store, the DNS resolver entry, and (macOS) the `pf` port redirect. **Root only** - see [Run it with `sudo`](#run-it-with-sudo).
2. **The daemon** - stops and disables the per-user service (systemd `--user` / launchd) and reaps the running `yerdd` (which in turn stops its PHP-FPM pools and any managed services).
3. **The PATH entry** - removes the yerd block from your shell startup files (the same block [`yerd path`](./tooling) manages).
4. **Config, data, and cache** - the `yerd.toml` config, installed PHP versions, dev tools, downloads, the local CA, and the runtime socket directory.
5. **The binaries** - `yerd`, `yerdd`, and `yerd-helper`. A package install is left for your package manager instead (`sudo apt purge yerd` on Debian/Ubuntu, `sudo pacman -R yerd` on Arch, `sudo dnf remove yerd` on Fedora) - yerd never `rm`s package-managed files.

When something can't be removed automatically, it's listed at the end as a leftover to handle manually.

## Run it with `sudo`

The `elevate` changes (trust store, resolver, ports) need root to reverse - and they **can't be reversed after yerd is uninstalled**, because the `yerd-helper` binary is gone. So:

* **`sudo yerd uninstall`** reverts those system changes, then removes everything else (resolved for your real user, even under `sudo`).
* **`yerd uninstall`** (no root) prints a clear warning, lists the exact manual commands to undo the system changes later, and then removes everything else.

::: tip Undo elevation first, or just use sudo
If you started without root, the simplest path is to run `sudo yerd uninstall` so the trust/resolver/port changes are cleaned up automatically. Otherwise follow the printed manual steps (they include your TLD and the CA fingerprint so the leftover CA stays identifiable). See [Elevation & Privileges](../../guide/elevation).
:::

## Confirmation & non-interactive use

You'll be asked to confirm before anything is removed. Pass `--yes` (`-y`) to skip the prompt in scripts. With no TTY and no `--yes`, the command refuses rather than destroying anything silently.

## Platform support

Full uninstall is supported on **macOS** and **Linux**. The desktop app itself (the `.app` / `.deb` / `.pkg.tar.zst` / `.rpm`) is removed the usual way for your platform - drag to Trash on macOS, or `sudo apt purge yerd` (Debian/Ubuntu) / `sudo pacman -R yerd` (Arch) / `sudo dnf remove yerd` (Fedora) on Linux.

## See also

* [Elevation](./elevation) - the `elevate` / `unelevate` changes that the full uninstall reverts under `sudo`.
* [PHP](./php) and [Tooling](./tooling) - the component `uninstall php` / `uninstall tool` forms.
* [Getting Started → Uninstall](../../guide/getting-started#uninstall).

---

---
url: 'https://yerd.app/reference/configuration.md'
---
# Configuration Reference

Yerd stores all of its persistent state in a single TOML file: `yerd.toml`. This page documents where that file lives, every field in the schema, the defaults, how schema versioning and migration work, and how saves stay safe. Everything here is grounded in the [`yerd-config`](../developer/crates/yerd-config) crate.

::: tip You rarely edit this by hand
The daemon (`yerdd`) owns `yerd.toml`. Day to day you change it through the [CLI](./cli/) or the [desktop app](../guide/desktop-app), and the daemon rewrites the file atomically. Hand-editing works too - Yerd parses and re-validates the file on every load - but the CLI is the safer path.
:::

## Where the config file lives

The file is always named `yerd.toml` and sits in your per-OS, user-owned config directory:

| OS    | Config directory                          | Full path                                              |
| ----- | ----------------------------------------- | ------------------------------------------------------ |
| macOS | `~/Library/Application Support/io.yerd.Yerd` | `~/Library/Application Support/io.yerd.Yerd/yerd.toml` |
| Linux | `$XDG_CONFIG_HOME/yerd` (default `~/.config/yerd`) | `~/.config/yerd/yerd.toml`                       |

These paths come from [`yerd-platform`](../developer/crates/yerd-platform)'s directory resolver, which uses the `directories` crate with the qualifier `io` / `yerd` / `Yerd`. The directory is created on demand the first time the daemon saves; it is not guaranteed to exist before then.

The daemon resolves the path once at startup and falls back to `<config dir>/yerd.toml` unless an explicit path was passed on the `yerdd serve` command line. If the file is absent, the daemon starts from the built-in defaults and writes the file on the first change.

::: info Config vs. data vs. runtime
`yerd.toml` is the only file in the *config* directory. Certificates live in the *data* directory, logs in the *cache* directory, and the IPC socket in the *runtime* directory. See [Architecture](../developer/architecture) and [The Daemon](../guide/daemon) for the full layout.
:::

## Top-level schema

Every field below maps one-to-one to a field in `schema.rs`. The on-disk shape always begins with the `version` line, followed by the scalar keys, then the sub-tables.

| Key         | TOML type            | Meaning                                                            | Default        |
| ----------- | -------------------- | ----------------------------------------------------------------- | -------------- |
| `version`   | integer              | On-disk schema version. **Mandatory**; written as `18` by this release. | `n/a (required)` |
| `tld`       | string               | TLD served by Yerd's resolver.                                    | `"test"`       |
| `dns_port`  | integer (u16)        | Loopback port for the embedded `.test` DNS responder.             | `1053`         |
| `symlink_protection` | boolean     | Refuse to serve assets/scripts reached via a symlink resolving outside a site's document root. | `true` |
| `mcp_enabled` | boolean            | Serve Yerd's tools to local AI agents over MCP (`yerd mcp`).       | `false`        |
| `ports`     | table                | HTTP / HTTPS listen ports.                                        | `80` / `443`   |
| `php`       | table                | PHP defaults and global ini settings.                             | see below      |
| `parked`    | table                | Parked directory paths.                                           | empty          |
| `linked`    | array of tables      | Explicitly linked sites.                                          | empty          |
| `overrides` | array of tables      | Per-site overrides for **parked** sites.                          | empty          |
| `services`  | table                | Per-service `[services.<id>]` tables; every installed engine auto-starts on boot. | empty          |
| `mail`      | table                | Built-in mail-capture SMTP server.                                | on / `2525`    |
| `dumps`     | table                | Laravel ▸ Dumps telemetry settings.                               | off / `2304`   |
| `domains`   | table                | Per-site domain sets (primary, aliases, subdomains, wildcards).   | empty          |

::: warning Unknown keys are rejected
The parser uses `deny_unknown_fields` at every level. A typo'd or stray key (top-level, or inside `[ports]`, `[php]`, `[parked]`, `[mail]`, `[dumps]`, `[dumps.features]`, `[domains]`, a `[domains.linked.<name>]` / `[domains.parked."<docroot>"]` entry, `[proxy_rules]`, a `[[proxies]]` entry, a `[services.<id>]` table, a `[[linked]]` entry, an `[[overrides]]` entry, or a `[[php.extensions.<version>]]` entry) is a hard parse error - the daemon will refuse to load the file rather than silently ignore it.
:::

### `version`

The schema version. This key is **required** - a missing `version` is a hard error (`MissingVersion`), and a non-integer or negative value is rejected (`NonIntegerVersion`). The current schema version is `18`, and Yerd always writes `version = 18`. Older `version = 1` through `version = 17` files are migrated forward automatically on load. See [Schema versioning](#schema-versioning-and-migration) below.

### `tld`

The top-level domain Yerd's resolver answers for, without a leading dot. The default is `test`, giving you `myapp.test`. The value is validated by `yerd-core`: whitespace is rejected, and a trailing dot is silently stripped (`"test."` becomes `"test"`). See [DNS & .test Domains](../guide/dns).

### `dns_port`

The loopback UDP/TCP port the embedded `.test` DNS responder binds to. The default is `1053`. A fixed (non-ephemeral) port keeps the resolver configuration installed by `yerd elevate resolver` valid across daemon restarts. A value of `0` means "ephemeral" and is intended for development and tests only - it is not durable across restarts.

::: tip Port already in use?
If another process holds `dns_port`, the daemon fails to bind and tells you to change `dns_port` in `yerd.toml` or free the port.
:::

### `symlink_protection`

By default (`true`) the proxy refuses to serve a static asset - or resolve a script - reached through a symlink whose target resolves **outside** the requested site's own document root, answering with an explicit `403`. This is a safety guard: a symlink inside a site could otherwise point the server at arbitrary files elsewhere on the host.

Set it to `false` to allow those symlinks. The motivating case is a shared parent/child WordPress theme kept in its own directory beside your sites and symlinked into `wp-content/themes/`: with protection on, its assets 403; with protection off, they are served. The setting is global (all sites) and can be toggled from the desktop app under **Settings › Security**; the change takes effect immediately, without restarting the daemon.

::: warning Off trusts every in-tree symlink
While off, a symlink is followed wherever it resolves, not only within the parked folder. Combined with a public tunnel (`yerd-tunnel`), that can expose files beyond a site's root. Leave it on unless you specifically need a cross-directory symlink like the shared-theme layout above.
:::

### `mcp_enabled`

Whether `yerd mcp` serves Yerd's tools to local AI agents over the Model Context Protocol. Defaults to `false`: exposing Yerd to agents is an explicit opt-in, toggled from the desktop app under **Settings › General › AI Agents**.

The daemon runs no MCP server of its own - it stores this flag and reports it in its status. Each agent session runs a short-lived `yerd mcp` process that reads it, so turning it **on** reaches agent sessions already running (on their next tool call), while turning it **off** applies to sessions started afterwards. See the [AI Agents guide](../guide/ai-agents).

::: warning Not a security boundary
The flag gates tool *discovery*, not access. Any process running as your user can already talk to Yerd's daemon through its socket - that is how the `yerd` CLI works - so turning this off does not isolate Yerd from local software.
:::

### `[ports]`

The HTTP and HTTPS listen ports for the proxy, plus the rootless ports the daemon falls back to when it can't bind the privileged ones.

| Key              | TOML type     | Meaning                                                                          | Default |
| ---------------- | ------------- | --------------------------------------------------------------------------------- | ------- |
| `http`           | integer (u16) | HTTP listen port.                                                                | `80`    |
| `https`          | integer (u16) | HTTPS listen port.                                                               | `443`   |
| `fallback_http`  | integer (u16) | Rootless HTTP port the daemon drops to when `http` can't bind without elevation. | `8080`  |
| `fallback_https` | integer (u16) | Rootless HTTPS port the daemon drops to when `https` can't bind without elevation. | `8443`  |

The default is the IANA well-known pair `80 / 443`. Binding these privileged ports may require elevation on macOS and Linux - see [Elevation & Privileges](../guide/elevation). If you would rather avoid elevation, switch to the unprivileged fallback pair `8080 / 8443`:

```toml
[ports]
http = 8080
https = 8443
```

`fallback_http` and `fallback_https` are what the daemon binds instead of `http`/`https` when it starts in degraded mode - unable to acquire the privileged ports without elevation - so the proxy still comes up rather than failing to start. They're editable from the desktop app's Settings > Web ports card as well as by hand.

Validation rules (enforced by `Config::validate`): neither `http` nor `https` may be `0`, and they must differ (`HttpPortZero`, `HttpsPortZero`, `HttpHttpsPortsEqual`). Both fallback ports must be `>= 1024` - the fallback exists specifically to avoid needing elevation, so a privileged fallback is rejected (`FallbackPortPrivileged`) - and `fallback_http`/`fallback_https` must differ from each other (`FallbackPortsEqual`).

### `[php]`

PHP defaults applied across sites.

| Key                | TOML type | Meaning                                                      | Default |
| ------------------ | --------- | ------------------------------------------------------------ | ------- |
| `default`          | string    | Default PHP version for new sites (e.g. `"8.3"`).            | `"8.3"` |
| `settings`         | table     | Global PHP ini directives applied to every installed version's FPM pool. | empty   |
| `version_settings` | table     | Sparse per-version overrides of `settings`, keyed by PHP version. | empty   |
| `directives`       | table     | Free-form per-version ini directives, keyed by PHP version.  | empty   |
| `extensions`       | table     | Custom `.so` extensions to load, keyed by PHP version.       | empty   |

`default` is a `MAJOR.MINOR` version string validated by `yerd-core`'s `PhpVersion`; an out-of-range minor or a non-numeric value is rejected. See [PHP Versions](../guide/php-versions).

`[php.settings]` is a string-to-string map of PHP ini directives written into **every** installed version's FPM pool. An empty map means "use PHP's defaults" and the table is omitted from the file entirely. Only an allowlisted set of directives is accepted, and every value is validated as a security boundary (no control characters, none of the FPM/ini metacharacters `[ ] = ; #`, length ≤ 256 bytes). The supported directives are:

| Directive             | Value shape                                                   |
| --------------------- | ------------------------------------------------------------- |
| `memory_limit`        | byte size (`512M`); also accepts `-1` for unlimited           |
| `max_execution_time`  | non-negative integer                                          |
| `max_input_time`      | non-negative integer                                          |
| `max_file_uploads`    | non-negative integer                                          |
| `upload_max_filesize` | byte size (`64M`)                                             |
| `post_max_size`       | byte size (`64M`)                                             |
| `display_errors`      | boolean flag (`On` / `Off`, rendered as a `php_flag`)         |
| `error_reporting`     | integer or constant expression (e.g. `E_ALL & ~E_DEPRECATED`) |

```toml
[php.settings]
memory_limit = "512M"
max_execution_time = "300"
upload_max_filesize = "64M"
```

::: warning Setting an unsupported directive fails the load
An unknown directive name or a malformed value makes the whole config invalid (`InvalidPhpSetting`). Stick to the table above.
:::

`[php.version_settings."<version>"]` (schema v16) holds **per-version
overrides** of the same allowlisted settings, keyed by PHP version string. A
version's effective value is its override when present, else the global
`[php.settings]` value, else PHP's built-in default. Omitted entirely when no
overrides are set.

`[php.directives."<version>"]` (schema v18) holds **free-form ini directives**
per version - typically extension settings the allowlist doesn't cover
(`xdebug.mode`, `opcache.*`, …). Names must start with a letter or `_` and use
only letters, digits, `.`, `_`, `-`; values follow the same injection rules as
`[php.settings]` (no control characters or `[ ] = ; #`, ≤ 256 bytes).
Directives Yerd manages through typed paths are reserved: the eight allowlisted
settings, `extension` / `zend_extension`, and `openssl.cafile` / `curl.cainfo`.

```toml
[php.version_settings."8.3"]
memory_limit = "1G"

[php.directives."8.3"]
"xdebug.mode" = "debug"
```

::: tip These two tables load leniently
Unlike `[php.settings]`, a hand-edited invalid or reserved entry in
`version_settings` / `directives` never fails the load - it is silently
dropped while valid siblings survive, so a bad edit can't stop the daemon.
Setting values through the CLI/GUI still validates strictly. A malformed
*version key* (e.g. `"eight"`) is still a hard error.
:::

Manage these with [`yerd set php --only <version>` and `yerd php ini`](cli/php#custom-ini-directives) or the desktop app's **Per-version configuration** card.

`[php.extensions]` maps a **PHP version string** to an array of custom extensions to load into both that version's FPM pool and its CLI. It is written as an array-of-tables per version and omitted entirely when empty. Because a native `.so` is ABI-bound to a PHP minor, an entry only applies to the version it is keyed under.

| Field  | TOML type | Meaning                                                                 |
| ------ | --------- | ----------------------------------------------------------------------- |
| `name` | string    | Removal/display handle (defaults to the `.so` basename when added).     |
| `path` | string    | Absolute path to the `.so`. Validated as a security boundary: must be absolute, end in `.so`, and contain no control characters, NUL, `"`, or `$` (spaces are allowed - the rendered ini value is double-quoted, and `$` is rejected because PHP would interpolate `${VAR}` inside it). |
| `zend` | bool      | Load as a `zend_extension` rather than a plain `extension`.             |

```toml
[[php.extensions."8.5"]]
name = "scrypt"
path = "/opt/homebrew/lib/php/pecl/20250925/scrypt.so"
zend = false
```

Manage this with [`yerd php ext`](cli/php#custom-extensions) or the Extensions section of the desktop app's **Per-version configuration** card rather than editing by hand - the CLI/daemon **load-probe** each `.so` before saving. Names must be unique within a version; a duplicate or an invalid path makes the whole config invalid.

### `[parked]`

Directories you have "parked" - every immediate subdirectory becomes a site served under `<dirname>.<tld>`. See [Sites](../guide/sites).

| Key     | TOML type        | Meaning                              | Default |
| ------- | ---------------- | ------------------------------------ | ------- |
| `paths` | array of strings | Parked directory paths.              | `[]`    |

Paths are stored **verbatim** as UTF-8 strings and are **not canonicalised** by the config layer - `"/srv/foo"` and `"/srv/foo/"` are distinct entries. They are kept in sorted order with no duplicates. An empty-string path is rejected (`ParkedPathEmpty`).

```toml
[parked]
paths = ["/Users/you/Sites", "/Users/you/work"]
```

### `[[linked]]`

Explicitly registered sites, each as its own array-of-tables entry. Order is preserved on round-trip.

| Key             | TOML type | Meaning                                            |
| --------------- | --------- | -------------------------------------------------- |
| `name`          | string    | Site name (the subdomain under your TLD).          |
| `document_root` | string    | Path to the site's project directory.              |
| `web_subpath`   | string    | Served web root, relative to `document_root`. Optional. |
| `php`           | string    | PHP version for this site (e.g. `"8.3"`).          |
| `secure`        | boolean   | Whether HTTPS is enabled for this site.            |
| `kind`          | string    | `"linked"` or `"parked"`.                          |

`name`, `document_root`, `php`, `secure`, and `kind` are required per entry. `name`, `php`, and `kind` are validated by `yerd-core`; for example an invalid site name like `"FOO.BAR"` is rejected. Linked site names must be unique - a duplicate produces `DuplicateLinkedSite`.

`web_subpath` is the directory actually served, relative to `document_root` (e.g. `"public"` for Laravel; empty/absent means "serve the document root itself"). It is **optional and omitted from the file when empty**, so a site served from its project root has no `web_subpath` line. It must be a plain relative path - an absolute path or one containing `..` is rejected (`WebRootEscapes`) so a hand-edited value can never escape the project. Yerd normally sets this for you via framework detection; see [Web root](../guide/sites#web-root-the-served-directory).

```toml
[[linked]]
name = "api"
document_root = "/Users/you/projects/api"
web_subpath = "public"
php = "8.3"
secure = true
kind = "linked"
```

### `[[overrides]]`

Per-site overrides for **parked** sites, each its own array-of-tables entry. A parked site is otherwise derived purely from a directory listing, so it has nowhere to persist a custom PHP version or HTTPS flag. Rather than promoting it to a linked site (which would change its kind), the daemon records the override here and re-applies it during the directory scan, leaving the site parked.

| Key        | TOML type | Meaning                                                       |
| ---------- | --------- | ------------------------------------------------------------- |
| `path`     | string    | The parked site's document-root path. **Required.**          |
| `php`      | string    | Pinned PHP version. Omit to inherit the global default.       |
| `secure`   | boolean   | Pinned HTTPS flag. Omit to inherit (off).                     |
| `web_root` | string    | Pinned web root, relative to `path`. Omit to auto-detect.     |
| `front_controller` | boolean | Pinned front-controller mode. Omit to auto-derive from detection. |

`php`, `secure`, `web_root`, and `front_controller` are all optional - omitting a key means "inherit" (or, for `web_root`/`front_controller`, "auto-derive on every scan"). An entry may pin one, several, or (uselessly) none. The serialiser skips omitted keys, so a partial override stays tidy on disk. Like `web_subpath` on a linked site, `web_root` must be a plain relative path inside the project (`WebRootEscapes` otherwise). Setting `web_root` is what `yerd root <parked-site> <path>` does; setting `front_controller` is what `yerd front-controller <parked-site> on|off` does.

`front_controller = true` funnels every request through the site-root `index.php` (the right behaviour for a single-front-controller framework such as Laravel or Symfony); `false` executes a named `.php` under the served root directly (classic multi-page PHP). When omitted, the mode is auto-derived: a framework served from a subdirectory (non-empty `web_root`/`web_subpath`) defaults to front-controller mode, while WordPress (any layout) and plain root-served sites default to direct execution. The same key is accepted inside a `[[linked]]` entry.

::: warning Direct execution exposes every `.php` in the served root
With direct execution (the default for a plain root-served site), any real `.php` file under the served root is URL-executable - including a stray `phpinfo.php` or a leftover admin tool. If the site is exposed beyond loopback via a tunnel, those files are remotely reachable. Set `front_controller = true` (or point `web_root` at a clean public directory) to funnel everything through `index.php` instead.
:::

```toml
# Pin PHP, HTTPS, and the served web root for one parked site...
[[overrides]]
path = "/Users/you/Sites/blog"
php = "8.4"
secure = true
web_root = "public"

# ...and only HTTPS for another (PHP and web root inherit / auto-detect).
[[overrides]]
path = "/Users/you/Sites/wiki"
secure = false
```

::: warning `path` must match byte-for-byte
The `path` key is the parked site's document-root string, stored **byte-exact and never canonicalised** - it must match exactly the path the daemon's directory scan produces. Do not canonicalise, trim, or add a trailing slash by hand, or the override won't be applied. An empty `path` is rejected (`OverridePathEmpty`).
:::

### `[services.<id>]`

Installed services, one table per engine, keyed by its `id`
(`mysql`, `mariadb`, `postgres`, `redis`, or `meilisearch`). An unknown service id fails
validation (`UnknownService`). See [Services & Databases](../guide/services).

| Key       | TOML type      | Meaning                                            | Default |
| --------- | -------------- | -------------------------------------------------- | ------- |
| `version` | string         | Installed version this engine is pinned to.        | unset   |
| `port`    | integer (u16)  | Loopback port the engine listens on.               | unset   |
| `enabled` | boolean        | Record of the last start/stop intent (status only). | `true`  |

`version` and `port` are omitted from the wire when unset; `enabled` always carries a value.

::: tip
`enabled` no longer gates boot auto-start - the daemon auto-starts **every installed** engine regardless of this flag. A `stop` lasts only the current session; `uninstall` to keep an engine off. See [Services & Databases](../guide/services#auto-start-on-boot).
:::

```toml
[services.mysql]
version = "8.4"
port = 3306
enabled = true

[services.redis]
version = "8"
port = 6379
enabled = true
```

You normally manage these through the [`yerd service`](../reference/cli/services) commands rather than by hand.

### `[mail]`

The built-in mail-capture SMTP server - a Herd-style sink that accepts mail on a loopback port and stores it for inspection in the desktop app. **Capture is on by default.**

| Key       | TOML type     | Meaning                                                | Default |
| --------- | ------------- | ------------------------------------------------------ | ------- |
| `enabled` | boolean       | Whether the daemon starts the capture server on boot.  | `true`  |
| `port`    | integer (u16) | Loopback port the capture server binds on `127.0.0.1`. | `2525`  |

When enabled the daemon binds `port` on `127.0.0.1`; a busy port is non-fatal - the daemon logs and runs with capture not listening. Validation rejects `port = 0` (`MailPortZero`).

Because the section's default (enabled, port `2525`) is the common case, the serialiser **omits `[mail]` entirely when it matches the default** - so a default file has no `[mail]` table at all. The table is written only once a value differs from the default.

```toml
[mail]
enabled = true
port = 2525
```

### `[dumps]`

Telemetry settings for the Laravel ▸ Dumps feature. The dump server buffers per-request telemetry frames from the `yerd-php-ext` extension; this section is the durable source of truth (the daemon writes a runtime mirror the extension reads each request). **Disabled by default.**

| Key       | TOML type     | Meaning                                                              | Default |
| --------- | ------------- | ------------------------------------------------------------------- | ------- |
| `enabled` | boolean       | Whether dump interception is on (the "antenna").                    | `false` |
| `port`    | integer (u16) | Loopback port the dump server listens on / the extension connects to. | `2304`  |
| `persist` | boolean       | When `false`, the buffer is cleared on each new request (latest-request view); `true` accumulates across requests. | `false` |
| `features`| table         | Per-feature capture toggles (see below).                            | empty   |

Validation rejects `port = 0` (`DumpsPortZero`).

`[dumps.features]` is a map of feature name → bool. The keys are `dumps`, `queries`, `jobs`, `views`, `requests`, `logs`, and `cache`. **An absent key means "on"**, so the table only needs entries for features you have turned *off*. An empty map (every feature on) is omitted from the file, and so is the whole `[dumps]` table when it matches the default (disabled, port `2304`, no overrides).

```toml
[dumps]
enabled = true
port = 2304
persist = false

[dumps.features]
queries = false   # absent keys default to on; only the off ones need listing
```

### `[tunnel]`

Persisted state for [sharing sites](../guide/sharing) through Cloudflare Tunnel. Two maps, both **empty by default** - the whole `[tunnel]` table is omitted from the file until you create a named tunnel or expose a site. Quick-tunnel state is never persisted (it lives only in the running daemon).

| Sub-table        | Shape                     | Meaning                                                        |
| ---------------- | ------------------------- | ------------------------------------------------------------- |
| `[tunnel.named]` | map `name → uuid`         | The named tunnels created on your Cloudflare account.         |
| `[tunnel.sites]` | map `site → hostname`     | Per-site public hostnames exposed through the named tunnel.   |

Validation rejects empty keys/values (`TunnelEntryEmpty`), a `[tunnel.sites]` hostname that isn't a plausible DNS name (`TunnelHostnameInvalid`), and any key or UUID containing path- or YAML-unsafe characters (`TunnelKeyInvalid`). The account certificate and per-tunnel credentials are **not** stored here - they live in a daemon-owned `0700` directory, never in the config file.

```toml
[tunnel.named]
my-tunnel = "6ff42ae2-765d-4adf-8112-31c55c1551ef"

[tunnel.sites]
app = "app.example.com"
```

### `[groups]`

User-defined site groups for the desktop app's Sites view. Purely an organisational overlay - groups do not affect routing. Both fields are **empty by default**, so the whole `[groups]` table is omitted from the file until you create a group.

| Key       | TOML type        | Meaning                                                        |
| --------- | ----------------- | --------------------------------------------------------------- |
| `order`   | array of strings  | Group display names, in display order.                        |
| `members` | table (`site → group`) | Per-site group membership, keyed by site name.           |

Membership is keyed by **site name**, not document-root, so a group applies to parked and linked sites alike without touching either site's own record. A site absent from `members` is "Unallocated" - the GUI's synthetic bucket for ungrouped sites, which is never itself persisted here.

Validation rules (enforced by `Config::validate`): every name in `order` must be non-empty (`GroupNameEmpty`) and unique, ASCII-case-insensitively (`GroupDuplicate`); the name `Unallocated` is reserved in any casing and rejected (`GroupNameReserved`); and every `members` value must reference a group present in `order`, also folding case (`GroupMemberDangling`). Whether a keyed site still exists is not checked - parked sites are discovered from disk on each scan and have no config record to check against.

```toml
[groups]
order = ["Blog", "Shop"]

[groups.members]
api = "Blog"
```

### `[domains]`

Per-site domain customization: the primary (canonical) domain plus any additional aliases, subdomains, and wildcards a site answers for. **Empty by default** - the whole `[domains]` table is omitted until you customise a site with [`yerd domain`](./cli/domains). An uncustomised site answers only its default apex `<name>.<tld>`; subdomains do **not** resolve implicitly.

The table is split by site class, mirroring `[[overrides]]`:

| Key                | TOML type                 | Meaning                                                         |
| ------------------ | ------------------------- | --------------------------------------------------------------- |
| `[domains.linked]` | table (`name → delta`)    | Deltas for **linked** sites, keyed by site name.                |
| `[domains.parked]` | table (`docroot → delta`) | Deltas for **parked** sites, keyed by byte-exact document-root. |

Keying linked by name and parked by document-root matches `[[overrides]]`, so routing survives a directory rename and a parked site keeps its domains without a config record of its own.

Each entry is a **delta** over the default apex, with three optional fields:

| Field        | TOML type        | Meaning                                                              |
| ------------ | ---------------- | -------------------------------------------------------------------- |
| `added`      | array of strings | Extra domains the site answers for (exact or single-label wildcard). |
| `suppressed` | array of strings | Default domains to drop (only ever the apex).                        |
| `primary`    | string           | The canonical domain (must be exact, never a wildcard).              |

Values are stored as **sub-parts** - the part left of the TLD, exactly as the router matches - not full FQDNs. Under TLD `test`, `corp.test` is stored as `corp`, `*.blog.test` as `*.blog`, and the apex `blog.test` as `blog`. A leftmost `*` is a single-label wildcard (`*.blog` matches `api.blog.test`, never `x.api.blog.test`).

`Config::validate` enforces only structural rules (no duplicate `added`; `added` and `suppressed` disjoint; `primary` not a wildcard). TLD membership, cross-site uniqueness, and "keep at least one exact domain" are enforced by the daemon, which alone can see parked sites on disk.

```toml
[domains.linked.blog]
added = ["corp", "*.blog"]
suppressed = ["blog"]
primary = "corp"

[domains.parked."/Users/me/Sites/shop"]
added = ["shop-staging"]
```

### `[[proxies]]`

Whole-host reverse proxies - a `<name>.<tld>` host forwarded wholesale to a
running service, with no PHP or document root. **Empty by default** (the array
is omitted from the file) until you add one with [`yerd proxy`](./cli/proxies).
Order is preserved on round-trip.

| Field    | TOML type | Meaning                                                         |
| -------- | --------- | --------------------------------------------------------------- |
| `name`   | string    | The proxy's DNS label; it answers on `<name>.<tld>`.            |
| `target` | string    | The upstream URL, `http://host:port` or `https://host:port`.    |
| `secure` | bool      | Whether the proxy is served over HTTPS (toggled by `yerd secure`). |

```toml
[[proxies]]
name = "reverb"
target = "http://127.0.0.1:8080"
secure = true
```

### `[proxy_rules]`

Per-site path-prefix proxy rules - a path on an existing site forwarded to a
service while every other path is served by PHP. **Empty by default** (the whole
table is omitted) until you add a rule. Split by site class exactly like
`[domains]`: linked rules key by site name, parked rules by byte-exact
document-root, so routing survives a directory rename.

| Key                    | TOML type                       | Meaning                                       |
| ---------------------- | ------------------------------- | --------------------------------------------- |
| `[proxy_rules.linked]` | table (`name → array of rules`) | Rules for **linked** sites, keyed by name.    |
| `[proxy_rules.parked]` | table (`docroot → array`)       | Rules for **parked** sites, keyed by docroot. |

Each rule is a `{ prefix, target }` table. Removing a site's last rule drops its
key entirely, so the file round-trips byte-identically.

```toml
[[proxy_rules.linked.myapp]]
prefix = "/app"
target = "http://127.0.0.1:8080"
```

`Config::validate` enforces the structural rules it can see (proxy names unique
among proxies and against linked sites; a site's rule prefixes unique; no target
pointing at a `.<tld>` host). Collisions with parked sites and the
loopback-on-own-port loop guard are enforced by the daemon, which alone knows
the actively bound ports and sees parked sites on disk.

## Schema versioning and migration

Every config file **must** carry a top-level `version = N` key - it is the single trigger for forward migration. The current schema version is `18`.

When the daemon loads a file, it routes on the version it finds:

```text
found  > CURRENT (18)   →  error (UnsupportedVersion) - a newer Yerd wrote this file
found == CURRENT (18)   →  parse directly
found  < CURRENT (18)   →  walk forward migration steps, then parse
```

A file written by a *newer* Yerd than you are running is refused rather than misread. Older files are migrated forward in place, one version at a time, before the normal wire-deserialisation and validation run:

* **`v1 → v2`** is a bare version bump: v2 only **added** the optional `web_subpath` (`[[linked]]`) and `web_root` (`[[overrides]]`) keys, which default when absent, so a v1 file needs no structural rewrite.
* **`v2 → v3`** is the first *structural* migration: it rewrites the old `[services]` shape (a flat `enabled = ["redis", ...]` array of identifiers) into per-service `[services.<id>]` tables, carrying each previously-enabled id forward as an `enabled = true` instance.
* **`v3 → v4`** is a bare version bump: v4 only **added** the optional `[mail]` section, which defaults when absent, so a v3 file needs no structural rewrite. The bump exists so an *older* binary rejects a file using `[mail]` cleanly as `UnsupportedVersion` rather than failing on the unknown table.
* **`v4 → v5`** is likewise a bare version bump: v5 only **added** the optional `[dumps]` table, which defaults when absent. Same rationale - the bump lets an older binary refuse a `[dumps]`-bearing file cleanly instead of tripping `deny_unknown_fields`.
* **`v5 → v6`** is a bare version bump: v6 only **added** the top-level `update_channel` scalar (defaults to `"stable"` when absent).
* **`v6 → v7`** is a bare version bump: v7 only **added** the `[ports]` `fallback_http` / `fallback_https` keys (defaulting to `8080` / `8443`).
* **`v7 → v8`** is a bare version bump: v8 only **added** the optional `[tunnel]` table, which defaults to empty when absent. Same rationale - the bump lets an older binary refuse a `[tunnel]`-bearing file cleanly rather than tripping `deny_unknown_fields`.
* **`v8 → v9`** is a bare version bump: v9 only **added** the optional `[groups]` table, which defaults to empty when absent. Same rationale - the bump lets an older binary refuse a `[groups]`-bearing file cleanly rather than tripping `deny_unknown_fields`.
* **`v9 → v10`** is a bare version bump: v10 **added** the optional `[php.extensions]` registry and the `wp_auto_login` / `wp_auto_login_user` keys (inside `[[linked]]` and `[[overrides]]`, for one-click `WordPress` admin login), all of which default when absent. Same rationale - the bump lets an older binary refuse a file using them cleanly rather than tripping `deny_unknown_fields`.
* **`v10 → v11`** is a bare version bump: v11 only **added** the optional `[domains]` table (per-site domain sets), which defaults to empty when absent. Same rationale - the bump lets an older binary refuse a `[domains]`-bearing file cleanly rather than tripping `deny_unknown_fields`. No existing keys change, so a v10 file needs no structural rewrite.
* **`v11 → v12`** is a bare version bump: v12 only **added** the top-level `symlink_protection` scalar (defaults to `true` when absent).
* **`v12 → v13`** is a bare version bump: v13 only **added** the optional per-site `front_controller` key (inside `[[linked]]` and `[[overrides]]`), which defaults to auto when absent.
* **`v13 → v14`** is a bare version bump: v14 only **added** the optional `[[proxies]]` array and `[proxy_rules]` table (reverse proxies and per-site path rules), both of which default to empty when absent. Same rationale - the bump lets an older binary refuse a proxy-bearing file cleanly rather than tripping `deny_unknown_fields`.
* **`v14 → v15`** is the multi-instance services rework: v15 **added** the optional per-instance `site` field and the `"{type}:{site}"` wire ids (both additive), and made the `enabled` flag actually gate boot autostart. The migration marks every existing single-instance engine `enabled = true` so previously-installed engines keep starting with Yerd across the upgrade.
* **`v15 → v16`** is a bare version bump: v16 only **added** the optional `[php.version_settings]` table (per-version overrides of the global PHP settings), which defaults to empty when absent.
* **`v16 → v17`** is a bare version bump: v17 only **added** the top-level `mcp_enabled` scalar (defaults to `false` when absent).
* **`v17 → v18`** is a bare version bump: v18 only **added** the optional `[php.directives]` table (free-form per-version ini directives), which defaults to empty when absent.

The on-disk schema version is deliberately decoupled from the IPC protocol version; the two evolve independently.

::: warning Downgrades are refused, not misread
Because later versions changed shapes the parser checks strictly (keys *inside* `[[linked]]` / `[[overrides]]` in v2, and the whole `[services]` shape in v3), an older daemon reading a newer file would fail. The version routing turns that into a clean `UnsupportedVersion` error instead - there is no automatic backward migration, but it fails loudly rather than corrupting state. See [Config Schema History](../developer/config-schema-history#downgrading-in-practice) for the exact manual edits to hand-downgrade a file version by version.
:::

::: tip Forward-compatible by design
The parser tolerates older shapes: a v1 file written before `web_subpath`/`web_root` existed migrates to v2 and parses fine (the new fields default). New optional fields are added additively, so upgrades don't break your existing config.
:::

## Atomic saves

Saves are atomic. The daemon serialises the config, writes it to a temporary file in the same directory, then `rename`s it over `yerd.toml`. Because the temp file lives on the same filesystem as the destination, the rename is atomic on Unix - a reader never sees a half-written file, and a crash mid-save leaves the previous config intact. On failure the temp file is cleaned up automatically, so no orphan files are left behind.

On Unix the file is created with mode `0600` (owner read/write only): the daemon is the only intended writer. Intermediate parent directories are created as needed.

::: info Durability trade-off
Yerd does not `fsync` the file or its parent directory after a save. For a developer-only config file the portability cost outweighs the durability gain, so a loss under sudden power loss is accepted by design.
:::

## A complete annotated example

This is a valid `yerd.toml` covering the core fields (see the sections above for the newer optional tables - `update_channel`, `[tunnel]`, `[groups]`, `[php.extensions]`, `[domains]`, `[[proxies]]`, `[proxy_rules]`, `wp_auto_login` - omitted here for brevity):

```toml
# Schema version - mandatory, always written as 18 by this release.
version = 18

# TLD served by the resolver; sites resolve as <name>.test
tld = "test"

# Loopback port for the embedded .test DNS responder (default 1053).
dns_port = 1053

# Proxy listen ports. Defaults are 80 / 443 (may need elevation).
# Swap for the rootless 8080 / 8443 pair to avoid privileged binds.
[ports]
http = 80
https = 443

[php]
# Default PHP version applied to new sites.
default = "8.3"

# Global ini directives written into every installed version's FPM pool.
# Allowlisted directives only; values are validated as a security boundary.
[php.settings]
memory_limit = "512M"
upload_max_filesize = "64M"
post_max_size = "64M"

# Parked directories: each immediate subdirectory becomes a site.
# Paths are stored verbatim and are NOT canonicalised.
[parked]
paths = ["/Users/you/Sites"]

# Explicitly linked sites (order preserved). web_subpath is optional (the
# served web root relative to document_root; omitted when the root is served).
[[linked]]
name = "api"
document_root = "/Users/you/projects/api"
web_subpath = "public"
php = "8.3"
secure = true
kind = "linked"

# Per-site overrides for PARKED sites, keyed by exact document-root path.
# Omit php / secure / web_root to inherit / auto-detect. `path` must match the
# scan byte-for-byte.
[[overrides]]
path = "/Users/you/Sites/blog"
php = "8.4"
secure = true
web_root = "public"

# Installed services, one table per engine.
# Known ids: mysql, mariadb, postgres, redis, meilisearch. Usually managed via `yerd service`.
[services.redis]
version = "8"
port = 6379
enabled = true

# Built-in mail-capture SMTP server. ON by default - this table is written only
# when a value differs from the default (enabled, port 2525); a default config
# omits [mail] entirely. Shown here for completeness.
[mail]
enabled = true
port = 2525

# Laravel ▸ Dumps telemetry. OFF by default - omitted from a default file. When
# present, absent [dumps.features] keys default to ON, so only disabled features
# need listing.
[dumps]
enabled = true
port = 2304
persist = false

[dumps.features]
queries = false
```

## Related pages

* [Sites](../guide/sites) - parking and linking explained
* [PHP Versions](../guide/php-versions) - managing installed versions and per-site PHP
* [HTTPS & Certificates](../guide/https) - what `secure` turns on
* [DNS & .test Domains](../guide/dns) - how `tld` and `dns_port` are used
* [CLI Reference](./cli/) - the commands that edit this file for you
* [yerd-config crate](../developer/crates/yerd-config) - the implementation behind this schema

---

---
url: 'https://yerd.app/developer/architecture.md'
---
# Architecture

This page is the orientation map for contributors. It explains how the Yerd
workspace is organised, the one rule that everything else follows from, and the
boundaries you must respect when you add code. If you read one developer page
before opening the source, read this one.

For the matching per-component detail, see the [Crates Overview](./crates) and
the per-crate pages it links to, the [IPC Protocol](./ipc-protocol) reference,
and the [Cross-Platform Model](./cross-platform).

## The single organising rule

> **Pure logic lives in library crates. I/O and OS calls are pushed to the
> edges behind traits.**

Everything in the codebase is a consequence of this rule:

1. **Pure crates and pure modules do no I/O.** No filesystem, no network, no
   process spawning, no clock reads, no environment reads. They are
   unit-testable with in-memory fixtures and zero setup. `yerd-core` is the
   exemplar - it depends on no other `yerd-*` crate and is kept rigorously pure.
2. **Side effects go behind traits.** Anything that touches the OS is expressed
   as a trait - `TrustStore`, `ResolverInstaller`, `PortBinder`,
   `PortRedirector`, `Paths`, and the per-crate spawner/probe traits. Business
   logic depends on the trait; tests inject a fake; the real implementation
   lives in `yerd-platform` (or a crate's own `os`/`io` module) selected by
   `#[cfg(target_os = ...)]`.
3. **Binaries are thin.** `bin/yerdd`, `bin/yerd`, `bin/yerd-helper`, and the
   Tauri `src-tauri` layer wire crates together and own transports. They contain
   orchestration, not behaviour. Interesting logic belongs in a crate with
   tests.
4. **The IPC protocol is a stable contract.** Add fields and variants
   additively; never silently rename or reorder a variant or field; bump the
   protocol version on any breaking change.
5. **One source of truth.** The daemon (`yerdd`) owns runtime state. The CLI and
   the GUI are both `yerd-ipc` *clients* - neither reimplements daemon logic.

::: tip Why this matters
A side effect routed around a trait, or domain logic that creeps into a binary,
defeats the test strategy and the cross-platform strategy at once. If a task
seems to require breaking one of these boundaries, surface the conflict rather
than working around it.
:::

## Workspace layout

Yerd is a single Cargo workspace (`resolver = "2"`) plus a Tauri v2 + Vue 3
desktop app. The members are declared in the root
[`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml):

```
yerd/
├── crates/              library crates - all behaviour lives here
│   ├── yerd-core        pure domain types + host→site routing (bottom of the graph)
│   ├── yerd-ipc         request/response protocol + length-prefixed framing
│   ├── yerd-config      on-disk config: parse / migrate / serialize
│   ├── yerd-tls         pure-Rust local CA + per-site leaf certs (rustls/rcgen)
│   ├── yerd-platform    OS abstraction layer: the side-effect traits + per-OS impls
│   ├── yerd-dns         embedded *.test resolver (hickory)
│   ├── yerd-php         PHP-FPM pool supervision + release handling
│   ├── yerd-proxy       hand-rolled hyper + tokio-rustls reverse proxy
│   ├── yerd-supervise   generic process-supervision substrate (FPM + services)
│   ├── yerd-services    DB/cache engines (Redis/Valkey · MySQL · MariaDB · Postgres)
│   ├── yerd-mail        embedded SMTP sink (catch-all mailbox)
│   └── yerd-doctor      diagnostics + repair planning
├── bin/                 thin binaries - orchestration + transports only
│   ├── yerdd            the unprivileged per-user daemon (source of truth)
│   ├── yerd             the CLI (a yerd-ipc client)
│   └── yerd-helper      the privileged one-shot (the security boundary)
├── apps/
│   └── yerd-gui         Tauri v2 + Vue 3 desktop app (another yerd-ipc client)
└── xtask/               build automation (cargo xtask bump / version-check)
```

Shared dependency versions are pinned once in `[workspace.dependencies]` and
referenced with `dep.workspace = true`. Several are pinned with `=` for MSRV or
wire-stability reasons - read the comment next to a pin before bumping it. The
workspace MSRV is `1.77`; the GUI builds with a newer toolchain (Tauri v2 needs
edition2024, rustc ≥ 1.85).

See [Build Automation (xtask)](./xtask) for what `xtask` packages, and the
[Desktop App Internals](./gui) for the GUI side.

## The two-process model

In normal operation Yerd runs as an **unprivileged daemon** with **thin
clients**, and reaches for a separate **one-shot privileged helper** only for
the handful of operations that genuinely require root.

```mermaid
flowchart TD
    CLI["yerd (CLI)<br/>unprivileged client"]
    GUI["yerd-gui (Tauri)<br/>unprivileged client"]
    DAEMON["yerdd, the daemon<br/>UNPRIVILEGED, runs as your user<br/>owns runtime state: router,<br/>cert store, DNS, proxy, PHP-FPM"]
    HELPER["yerd-helper<br/>PRIVILEGED one-shot<br/>does one op, then exits"]

    CLI -->|"yerd-ipc"| DAEMON
    GUI -->|"yerd-ipc"| DAEMON
    DAEMON -->|"HelperInvocation<br/>(only when root is needed)"| HELPER
```

The clients reach the daemon over `yerd-ipc`: length-prefixed JSON over a
per-user socket or named pipe.

* **`yerdd`** runs as the user, unprivileged, and is the single source of truth
  for runtime state. It loads `yerd-config`, builds a `SiteRouter`, starts the
  DNS responder, reverse proxy, and PHP-FPM pools, owns the cert store, and
  serves the `yerd-ipc` server transport. It is thin orchestration - behaviour
  lives in the crates it wires together.
* **`yerd` (CLI)** and **`yerd-gui`** are both `yerd-ipc` clients. They connect
  to the daemon's per-user socket, send a typed `Request`, and render the
  `Response`. Neither holds authoritative state, so the CLI and the GUI can
  never disagree. (The GUI's `src-tauri` Cargo manifest depends on
  `yerd-ipc` with the `transport` feature and on `yerd-core` for domain types -
  nothing daemon-internal.)
* **`yerd-helper`** is the only privileged surface and therefore the security
  boundary. It takes strict typed arguments, never shells out, never accepts
  network input, performs exactly one operation, then exits. The daemon and GUI
  processes never run as root; when an operation needs root, code goes through
  `yerd-platform`, which returns a typed `HelperInvocation`, and a privileged
  caller (the daemon, or `yerd elevate` under `sudo`) owns the actual
  `Command::new(...)` that spawns the helper.

::: warning Privilege boundary
`yerd-platform`'s OS implementations never spawn the helper themselves - they
return `PlatformError::NeedsHelper` and hand back a typed `HelperInvocation`.
The privileged caller owns the spawn. The GUI process must never run as root.
See [Elevation & Privileges](../guide/elevation) and the
[yerd-helper](./binaries/yerd-helper) page.
:::

## One source of truth

The daemon owns state; clients are stateless views. This is rule 5 above, and it
is load-bearing: any feature that would let a client decide runtime truth (cache
authoritative state, mutate config without the daemon, reimplement routing) is a
boundary violation. Mutations flow as `yerd-ipc` requests to the daemon, which
applies them and broadcasts the new state. PHP updates are deliberately
**notify-only** - the daemon's periodic checker and `list` only *report* newer
patches; an install happens solely on an explicit update request.

## Daemon-hosted developer subsystems

Beyond serving sites, the daemon hosts two self-contained developer-tooling
subsystems. Both follow the rules above - the daemon owns the state, the GUI is a
stateless `yerd-ipc` view - and both keep their pure logic in a crate.

* **Mail capture.** A built-in SMTP sink (`crates/yerd-mail`) that the daemon
  binds on a loopback port when capture is enabled. Anything it receives is
  stored as a raw `.eml` on disk; there is **no relaying** - captured mail never
  leaves the box. The store is opened unconditionally (so already-captured mail
  stays listable even with capture off), and the SMTP listen is the only part
  gated on the enabled flag. Captured mail is surfaced over IPC (`ListMails` /
  `GetMail` / …) and rendered in the GUI's Mails viewer. As with the rest of the
  workspace, the crate splits a pure layer (the SMTP command state machine, MIME
  decoding, retention) from the I/O edge (the tokio TCP server and the disk
  store).

* **Laravel Dumps telemetry.** A live feed of per-request telemetry - `dump()`,
  Eloquent queries, jobs, views, cache, logs, outgoing HTTP - from running PHP
  apps. The data path is **native PHP extension → loopback TCP → ring buffer →
  IPC → GUI**: a native Zend extension emits newline-delimited JSON frames to a
  loopback dump server the daemon runs, which buffers them in a bounded
  in-memory ring and pages them to the GUI (`ListDumps` / `DumpsStatus`). The
  shared wire model lives in `crates/yerd-ipc` (`dump.rs`); the daemon treats
  each frame's `payload` as **opaque** JSON so the extension's per-category
  schema can evolve without daemon changes.

  The native extension is an **external dependency**: the `.so` is built and
  published by the separate [`forjedio/yerd-php-ext`](https://github.com/forjedio/yerd-php-ext)
  repository, and the daemon downloads + SHA-256-verifies the artifact matching
  each installed PHP version's host triple (against the release `manifest.json`),
  placing it beside - not inside - the PHP installs so a PHP patch update never
  removes it. The daemon then wires it into each FPM pool via
  `-d extension`; the extension self-disables (via a daemon-written state
  file) when dumps are off. Fetch/verify is best-effort - a failure leaves the
  site running with no dumps. See the [yerdd](./binaries/yerdd) page for the
  `dump_server` / `ext_install` modules.

## Dependency direction (downhill, no cycles)

Internal dependencies flow strictly downhill. `yerd-core` sits at the bottom and
depends on no other `yerd-*` crate; libraries never depend on binaries; the CLI
and GUI depend on `yerd-ipc` (with its `transport` feature), not on the daemon's
internals.

```mermaid
flowchart TD
    CORE["yerd-core (pure domain types, routing)"]
    IPC["yerd-ipc"]
    TLS["yerd-tls"]
    CONFIG["yerd-config"]
    DOCTOR["yerd-doctor"]
    PLATFORM["yerd-platform (OS traits + per-OS impls)"]
    PHP["yerd-php"]
    PROXY["yerd-proxy"]
    BINS["yerdd, yerd, yerd-helper, yerd-gui (binaries/app)"]

    IPC --> CORE
    TLS --> CORE
    CONFIG --> IPC
    DOCTOR --> IPC
    PLATFORM --> TLS
    PLATFORM --> CORE
    PHP --> PLATFORM
    PROXY --> PLATFORM
    BINS --> IPC
    BINS --> CONFIG
    BINS --> DOCTOR
    BINS --> PLATFORM
```

Arrows point from a crate to what it depends on, so everything below points up
toward `yerd-core`.

Reading the graph:

* `yerd-core` ◄── everything.
* `yerd-core` ◄── `yerd-ipc` ◄── `yerd-config`, `yerd-doctor`, the binaries, and
  the GUI.
* `yerd-tls` ◄── `yerd-platform` ◄── `yerd-php`, `yerd-proxy`, the binaries.
  `yerd-platform` also depends on `yerd-core` directly, for the pure
  web-root detector it feeds (`ProjectSignals` in, framework decision out).

Crates carry dependency-graph tests (for example `yerdd`'s
`tests/no_runtime_deps.rs` and `yerd-helper`'s `tests/no_runtime_deps.rs`) that
fail if a forbidden crate - or an OpenSSL/native-tls variant - leaks into the
runtime graph. TLS is **rustls + rcgen only, never OpenSSL**.

## The physical `pure/` vs `io/` split

Many crates split the organising rule into actual modules: a **pure** layer that
is sync and runtime-free, and an **I/O** layer that is the side-effecting edge.
This is not merely stylistic - it is what keeps the bulk of the logic unit
testable in-memory.

| Crate | Pure layer | I/O / OS edge |
|---|---|---|
| `yerd-core` | the whole crate (`host`, `router`, `site`, `php`, `tld`, `domain`, `php_settings`, `detect`) | - (no I/O at all) |
| `yerd-ipc` | default build: `frame`, `message`, `request`, `response` | `transport` module, gated behind the `transport` feature (the only part allowed `tokio`) |
| `yerd-platform` | `pure` module (decision logic, parsing, port planning) | `os` module (`#[cfg(target_os)]` impls), `helper`, `trust_store`, `resolver`, `port_binder`, `port_redirect`, `metrics`, `detect` (project-signal gathering) |
| `yerd-php` | `pure/` (`fpm_conf`, `supervisor`, `env_scrub`) | `io/` (`atomic_write`, `fastcgi_probe`), `traits.rs`, `real.rs` |
| `yerd-proxy` | `pure/` | `server.rs`, `tls.rs`, `forward/`, `traits.rs` |
| `yerd-config` | `parse`, `migrate`, `serialize`, `schema` | `io.rs` |
| `yerd-tls` | the whole crate - no I/O, no clock reads, no env reads (callers pass `Validity` timestamps) | - |
| `yerd-dns` | `answer.rs`, `responder.rs` | `server.rs` |

For example, `yerd-tls` documents its own purity contract at the crate root:

```rust
//! `yerd-tls` generates a self-signed CA, loads it back from PEM, computes its
//! SHA-256 fingerprint, and issues per-site leaf certs signed by it. It does
//! **no I/O**, **no clock reads**, and **no env reads** - callers pass
//! timestamps via [`Validity`]; persistence and trust-store install live in
//! `yerd-config` and `yerd-platform` respectively.
```

And `yerd-platform` exposes its OS traits at the crate root, with one thin impl
per OS:

```rust
//! The core traits live here - [`Paths`], [`TrustStore`], [`ResolverInstaller`],
//! [`PortBinder`], and [`PortRedirector`] - each with a single thin
//! implementation per OS selected by `#[cfg(target_os = ...)]`. macOS and Linux
//! ship in Phase 1;
//! Windows compiles against the [`os::unsupported`] stub that returns
//! [`PlatformError::Unsupported`] for every method.
```

::: info Cross-platform discipline
Per-OS code is selected with `#[cfg(target_os = ...)]`; exactly one of
`linux` / `macos` / `unsupported` is active per build. OS-specific *decisions*
(parsing `profiles.ini`, planning ports, matching PEM) live in pure helpers so
they stay unit-testable without the OS effect. When you change one OS path, make
the equivalent change - or a deliberate, commented no-op - in the others, or CI
on the other platform will break. Details on the
[Cross-Platform Model](./cross-platform) page.
:::

## Error handling

* **Libraries use `thiserror`** to define typed, structured error enums. Every
  library crate has an `error` module (`CoreError`, `IpcError`/`IpcErrorKind`,
  `TlsError`, `PlatformError`, …) exposing precise, matchable variants. Reasons
  are split into dedicated enums (for example
  `PlatformError::ResolverErrorReason`) so callers can branch on cause.
* **`anyhow` is allowed only at a binary's top level** - never in a library's
  runtime dependency graph. Library APIs return their typed errors; the binary
  wiring is free to collapse them with context at the very top.

## Async only at the I/O edge

Pure crates and pure modules are synchronous and runtime-free. Only the I/O
layers touch `tokio` and `async-trait`. Concretely, the crates that pull in
`tokio` are `yerd-dns`, `yerd-proxy`, `yerd-php`, and `yerd-ipc` (only via its
`transport` feature), plus the daemon and CLI binaries. `yerd-core`,
`yerd-tls`, `yerd-config`, `yerd-doctor`, and `yerd-platform`'s pure layer have
no async. The default `yerd-ipc` build is pure: the frame codec and message
types compile with no `tokio` at all, so a pure client can use them; the async
connect/read/write helper lives behind the `transport` feature.

```toml
# crates/yerd-ipc/Cargo.toml
[features]
default   = []
transport = ["dep:tokio"]
```

## The IPC stable-contract rule

`yerd-ipc` is a published contract between the daemon and its clients, so it
gets special discipline. The wire format is a length-prefixed JSON frame: a
4-byte big-endian `u32` length followed by that many bytes of UTF-8 JSON.
`Request` and `Response` are internally tagged on a `snake_case` `type` field.

Contract rules:

* Add variants and fields **additively**. Never rename or reorder a variant or
  field silently - `tests/wire_stability.rs` pins the exact JSON tags and shapes
  and will (and should) fail. Treat such a failure as a contract alarm, not a
  test to "fix".
* Expand the error code set rather than overloading a generic variant.
* Raise `PROTOCOL_VERSION` on any breaking change, and add a `Hello`/`Welcome`
  handshake before the first incompatible change. Until then, a client speaking
  a newer protocol against an older daemon surfaces as a decode error when an
  unknown `type` tag arrives.

```rust
/// The current IPC protocol version. Bump on any breaking change;
/// add a handshake before doing so.
pub const PROTOCOL_VERSION: u32 = 1;
```

The framing edges are pinned in `tests/frame_codec.rs` (partial reads, multiple
frames per buffer, oversized-length rejection, empty frames) and round-trips in
`tests/roundtrip.rs`. The privileged argv contract has its own analogue:
`yerd-helper`'s clap parse is cross-checked against
`yerd_platform::HelperInvocation::from_argv` in debug builds, firing `WireDrift`
if a clap upgrade silently changes argv normalisation.

Full message catalogue and framing details are on the
[IPC Protocol](./ipc-protocol) page.

## Hard rules, at a glance

These are enforced by lints (`[workspace.lints]`) or by tests, and apply
workspace-wide:

| Rule | Enforcement |
|---|---|
| No `unsafe` | `unsafe_code = "forbid"`, plus `#![forbid(unsafe_code)]` on crate roots |
| No `unwrap` / `expect` / `panic!` / `todo!` / `dbg!` / indexing-slicing outside tests | clippy `deny` lints (allowed explicitly at the top of test files) |
| `thiserror` in libraries; `anyhow` only at binary top level | convention; no `anyhow` in any library runtime graph |
| TLS is rustls + rcgen, never OpenSSL / native-tls | dependency-graph tests in several crates |
| Async only at the I/O edge | pure crates/modules carry no `tokio` |
| `yerd-helper` is the only privileged surface | typed argv, no shelling out, no network input, one op then exit |
| Document public items | `missing_docs = "warn"`, pedantic clippy on |

The definition of done for a change: pure logic has table-driven unit tests;
every side-effecting path is behind a trait and tested with a fake; wiring has an
integration test in the crate's `tests/`; and
`cargo fmt --all --check`, `cargo clippy --workspace --all-targets -- -D warnings`,
and `cargo test --workspace` all pass on **both** Linux and macOS. See
[Contributing](./contributing) and [Building from Source](./building).

## Where to go next

* [Crates Overview](./crates) - every crate, its responsibility, and its tests.
* [IPC Protocol](./ipc-protocol) - the full request/response catalogue and wire
  format.
* [Cross-Platform Model](./cross-platform) - the `#[cfg(target_os)]` strategy and
  per-OS adapters.
* Binaries: [yerdd (daemon)](./binaries/yerdd),
  [yerd (CLI)](./binaries/yerd), [yerd-helper (privileged)](./binaries/yerd-helper).
* [Desktop App Internals](./gui) and [Build Automation (xtask)](./xtask).

---

---
url: 'https://yerd.app/developer/crates.md'
---
# Crates Overview

Yerd is a single Cargo workspace. The `[workspace]` members in
[`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml) split into
three layers:

* **Library crates** (`crates/*`) hold all the logic. Most are *pure* - no I/O,
  no clock, no env, no async - and the few that touch the world push their side
  effects behind traits.
* **Binaries** (`bin/*`) wire those libraries together: the unprivileged daemon
  (`yerdd`), the CLI client (`yerd`), and the privileged one-shot (`yerd-helper`).
* **The desktop app** (`apps/yerd-gui`) and **build automation** (`xtask`) sit at
  the top.

This page is the index. Each entry links to its own detailed reference page.

::: info Workspace facts
All members share a single `version`, `edition = "2021"`, and `rust-version = "1.77"`
from `[workspace.package]` - except `yerd-gui`, which pins `rust-version = "1.85"`
because current Tauri v2 needs edition2024 (rustc ≥ 1.85). The workspace forbids
`unsafe_code` and denies `unwrap`/`expect`/`panic`/`todo`/`dbg!`/`indexing_slicing`
in non-test code via `[workspace.lints]`. `yerd-gui` opts out of the strict lint
set (it wraps macro-heavy generated Tauri code) but still bans
`unwrap`/`expect`/`panic` in its own bridge code.
:::

## The workspace at a glance

### Library crates

| Crate | Purpose | Pure? | Page |
|---|---|:---:|---|
| `yerd-core` | Pure domain types (`Site`, `PhpVersion`, `Tld`) and host→site routing. The foundation every other crate depends on. | pure | [yerd-core](./crates/yerd-core) |
| `yerd-ipc` | IPC protocol, framing, and codec between `yerdd` and its clients. Length-prefixed JSON frames. | pure (default) | [yerd-ipc](./crates/yerd-ipc) |
| `yerd-config` | Persisted, schema-versioned TOML configuration. Pure parse/validate/serialise plus a thin atomic load/save. | mostly pure | [yerd-config](./crates/yerd-config) |
| `yerd-tls` | Pure-Rust local CA and per-site leaf certificate issuance (`rcgen` + `ring`). No I/O, no clock. | pure | [yerd-tls](./crates/yerd-tls) |
| `yerd-dns` | Authoritative `*.test` DNS responder plus `hickory-server` wiring. | owns I/O | [yerd-dns](./crates/yerd-dns) |
| `yerd-proxy` | Hand-rolled HTTP/HTTPS reverse proxy on `hyper` + `tokio-rustls`; serves static files and forwards to PHP-FPM over FastCGI. | owns I/O (pure submodule) | [yerd-proxy](./crates/yerd-proxy) |
| `yerd-supervise` | Process-agnostic supervision substrate: trait seams, the pure restart/health state machine, and tokio impls. Shared by `yerd-php` and `yerd-services`. | owns I/O (pure submodule) | [yerd-supervise](./crates/yerd-supervise) |
| `yerd-php` | PHP-FPM pool supervision and version management; discovery, install, health-probing. | owns I/O (pure submodule) | [yerd-php](./crates/yerd-php) |
| `yerd-services` | Local database / cache supervision (Redis/Valkey, MySQL, MariaDB, Postgres), version management, and SQL database administration. | owns I/O (pure submodule) | [yerd-services](./crates/yerd-services) |
| `yerd-doctor` | Pure diagnosis and fix-planning for `yerd doctor`. Turns a `StatusReport` into findings and safe auto-fixes. | pure | [yerd-doctor](./crates/yerd-doctor) |
| `yerd-platform` | OS abstraction layer: paths, trust store, resolver installer, port binder/redirector, metrics - one impl per OS. | owns I/O (pure submodule) | [yerd-platform](./crates/yerd-platform) |
| `yerd-mail` | Built-in mail-capture SMTP sink plus its on-disk store. Accepts mail on a loopback port (Herd-style) and persists parsed messages for the GUI. Depends on `yerd-ipc` + `mail-parser`. | owns I/O | [yerd-mail](./crates/yerd-mail) |
| `yerd-mcp` | Model Context Protocol server logic: the curated tool catalog agents call, the sans-io JSON-RPC state machine, and tool-result rendering. Consumed by `yerd mcp`, which owns the stdio loop and the daemon exchange. Depends on `yerd-ipc` and `yerd-core`. | pure | [yerd-mcp](./crates/yerd-mcp) |
| `yerd-tunnel` | Cloudflare Tunnel support: pure `cloudflared` argv / `config.yml` generation and log parsing, plus a supervised `cloudflared` lifecycle. Powers public site sharing. Depends on `yerd-supervise`. | owns I/O (pure submodules) | [yerd-tunnel](./crates/yerd-tunnel) |
| `yerd-update` | Pure release-channel selection and version-decision logic for self-update: `select_target` (stable/edge resolution), artifact selection by platform, and checksum/minisign verification. | pure | [yerd-update](./crates/yerd-update) |
| `yerd-service-ctl` | Cross-platform start/stop/restart control for the `yerdd` daemon service (`launchctl`/`systemctl`), used by the self-update applier to restart onto a freshly-swapped binary. | owns I/O | [yerd-service-ctl](./crates/yerd-service-ctl) |

### Binaries

| Binary | Purpose | Page |
|---|---|---|
| `yerdd` | The unprivileged per-user daemon. Wires every library together; owns all runtime state and serves the proxy, DNS, PHP pools, and database/cache services. | [yerdd (daemon)](./binaries/yerdd) |
| `yerd` | The CLI - a thin `yerd-ipc` client that talks to `yerdd` over a per-user socket. | [yerd (CLI)](./binaries/yerd) |
| `yerd-helper` | The privileged one-shot. Validates a typed `HelperInvocation`, performs exactly one root operation (CA install, resolver install, `setcap`), and exits. | [yerd-helper (privileged)](./binaries/yerd-helper) |

### App and tooling

| Member | Purpose | Page |
|---|---|---|
| `yerd-gui` (`apps/yerd-gui`) | Tauri v2 + Vue 3 desktop/tray app - another thin `yerd-ipc` client of `yerdd`, like the CLI. | [Desktop App Internals](./gui) |
| `xtask` | Build automation invoked as `cargo xtask <cmd>`: `bump`, `version-check`. | [Build Automation (xtask)](./xtask) |

### Test-only infrastructure

| Member | Purpose | Page |
|---|---|---|
| `yerd-depcheck` | Shared `cargo metadata` dependency-graph assertions, pulled in via `[dev-dependencies]` only by six crates'/binaries' `tests/no_runtime_deps.rs` guards - never a runtime dependency of anything shipped. | [yerd-depcheck](./crates/yerd-depcheck) |

This member is deliberately excluded from the "library crates" table and the
dependency graph below: it is never reachable from any shipped binary's
`[dependencies]`, only from test targets via `[dev-dependencies]` - a
different kind of workspace member entirely, closer in spirit to `xtask`
(tooling that helps build/verify the workspace) than to a crate `yerdd`
assembles at runtime.

## Internal dependency graph

Dependencies run **downhill**: `yerd-core` is the bedrock at the bottom and has
zero internal dependencies; every arrow points down toward the things it relies
on. `yerd-tls` is the other leaf - it has no internal `yerd-*` dependencies at all.

Apps and tooling sit at the top, binaries in the middle, libraries below, with
`yerd-core` as the bedrock. `xtask` has no internal `yerd-*` deps, so it stands
alone. Arrows point from a crate to what it depends on.

```mermaid
flowchart TD
    gui["yerd-gui (app)"]
    xtask["xtask (no internal deps)"]
    yerd["yerd (CLI)"]
    yerdd["yerdd (depends on all fourteen libs)"]
    helper["yerd-helper"]

    ipc["yerd-ipc"]
    config["yerd-config"]
    dns["yerd-dns"]
    proxy["yerd-proxy"]
    php["yerd-php"]
    services["yerd-services"]
    supervise["yerd-supervise"]
    doctor["yerd-doctor"]
    tls["yerd-tls"]
    platform["yerd-platform"]
    mail["yerd-mail"]
    mcp["yerd-mcp"]
    tunnel["yerd-tunnel"]
    update["yerd-update"]
    servicectl["yerd-service-ctl"]
    core["yerd-core (pure, zero internal deps)"]

    gui --> core
    gui --> ipc
    gui --> platform
    gui --> update

    yerd --> core
    yerd --> ipc
    yerd --> platform
    yerd --> update
    yerd --> servicectl
    yerd --> mcp

    helper --> core
    helper --> platform

    yerdd --> core
    yerdd --> config
    yerdd --> ipc
    yerdd --> tls
    yerdd --> platform
    yerdd --> dns
    yerdd --> php
    yerdd --> services
    yerdd --> supervise
    yerdd --> proxy
    yerdd --> doctor
    yerdd --> mail
    yerdd --> tunnel
    yerdd --> update

    ipc --> core
    mcp --> ipc
    mcp --> core
    config --> core
    dns --> core
    proxy --> core
    doctor --> core
    doctor --> ipc
    mail --> ipc
    php --> core
    php --> platform
    php --> supervise
    services --> platform
    services --> supervise
    tunnel --> supervise
    platform --> tls
```

Read as a nested list of direct internal dependencies (each verified against the
crate's `Cargo.toml`):

* **`yerd-core`** → *(none)*
* **`yerd-tls`** → *(none - workspace leaf)*
* **`yerd-ipc`** → `yerd-core`
* **`yerd-config`** → `yerd-core`
* **`yerd-dns`** → `yerd-core`
* **`yerd-proxy`** → `yerd-core`
* **`yerd-doctor`** → `yerd-core`, `yerd-ipc`
* **`yerd-platform`** → `yerd-tls`
* **`yerd-supervise`** → *(none - workspace leaf)*
* **`yerd-php`** → `yerd-core`, `yerd-platform`, `yerd-supervise`
* **`yerd-services`** → `yerd-platform`, `yerd-supervise`
* **`yerd-mail`** → `yerd-ipc`
* **`yerd-mcp`** → `yerd-core`, `yerd-ipc`
* **`yerd-update`** → *(none - workspace leaf)*
* **`yerd-service-ctl`** → *(none - workspace leaf)*
* **`yerd-helper`** (bin) → `yerd-core`, `yerd-platform`
* **`yerd`** (bin) → `yerd-core`, `yerd-ipc` (`transport`), `yerd-platform`, `yerd-update`, `yerd-service-ctl`
* **`yerd-gui`** (app) → `yerd-core`, `yerd-ipc` (`transport`), `yerd-platform`, `yerd-update`
* **`yerdd`** (bin) → `yerd-core`, `yerd-config`, `yerd-ipc` (`transport`), `yerd-tls`, `yerd-platform`, `yerd-dns`, `yerd-supervise`, `yerd-php`, `yerd-services`, `yerd-proxy`, `yerd-doctor`, `yerd-mail`, `yerd-tunnel`, `yerd-update` - **all fourteen libraries**
* **`xtask`** → *(no internal deps; `anyhow` + `clap` only)*

::: tip The daemon is the assembly point
Only `yerdd` depends on every library. It is where the pure logic, the OS
adapters, and the network servers are stitched into one running process. The CLI,
the helper, and the GUI each pull in only the narrow slice they need. This is what
the README means by "the daemon owns state; the CLI and GUI are clients."
:::

## Pure vs. I/O-owning crates

Yerd's central design rule (from the README): **pure logic lives in library
crates; I/O and OS calls are pushed to the edges behind traits**, with one trait
implementation per OS. That makes the bulk of the codebase unit-testable in-memory
with fakes, and keeps behaviour identical across platforms.

### Fully pure

These crates do no I/O, no async, and read no clock or environment. Callers pass
in everything (timestamps, reports) explicitly.

* **`yerd-core`** - `#![forbid(unsafe_code)]`, no async, no internal deps. The
  crate header states it plainly: *"It is **pure**: no I/O, no async, no internal
  `yerd-*` dependencies. Side effects belong behind traits in `yerd-platform`."*
* **`yerd-tls`** - *"It does **no I/O**, **no clock reads**, and **no env reads** -
  callers pass timestamps via \[`Validity`]."* Persistence lives in `yerd-config`;
  trust-store install lives in `yerd-platform`.
* **`yerd-doctor`** - *"runtime-free and does no I/O."* `diagnose()` maps a
  `StatusReport` to findings; `plan_auto_fixes()` returns the safe unprivileged
  `FixAction`s. The daemon performs the actual I/O and re-runs `diagnose()`
  afterwards.
* **`yerd-ipc`** - the default build is pure: *"no sockets, no async, no I/O."*
  Only the optional `transport` feature pulls in `tokio` for the shared async
  read/write helpers (the daemon and CLI both enable it).
* **`yerd-update`** - *"This crate does **no I/O**: it operates on already-fetched
  release metadata and the running version."* `select_target` (channel
  resolution) and artifact selection/verification are all pure functions over
  in-memory data; fetching releases and downloading artifacts is the caller's
  job (`yerdd` and the applier).

### Pure with a thin I/O seam

* **`yerd-config`** - *"Every function except `Config::load` and `Config::save`
  is pure."* Parse, validate, serialise, and migrate are all pure; load/save are a
  thin atomic file seam. Schema is versioned (`CURRENT_VERSION = 5`), decoupled
  from the IPC `PROTOCOL_VERSION`.

### I/O-owning, with a pure submodule

These crates genuinely own runtime side effects, but isolate their decision logic
in a `pure` module that is unit-tested in-memory.

* **`yerd-platform`** - the OS abstraction layer. Core traits (`Paths`,
  `TrustStore`, `ResolverInstaller`, `PortBinder`, `PortRedirector`) each have one
  thin `#[cfg(target_os = ...)]` impl; decision logic that needs no OS interaction
  lives in `pure`. It is **unprivileged**: operations needing root return
  `PlatformError::NeedsHelper` carrying a typed `HelperInvocation` for `yerd-helper`
  to execute - the OS impls never spawn the helper themselves.
* **`yerd-proxy`** - owns the `hyper` + `tokio-rustls` servers (`pub mod server`,
  `forward`, `tls`, `backend`), with a `pub mod pure` for the routing/decision
  logic (including `try_files` static-file resolution) and `pub mod traits`
  (`BackendResolver`, `CertStore`) at the edges.
* **`yerd-supervise`** - the shared supervision substrate. Pure `supervisor`
  (state machine), `listen`, and `error`; tokio adapters (`TokioProcessSpawner`,
  `SystemClock`, `TokioChild`) and the trait *definitions* (`ProcessSpawner`,
  `Clock`, `HealthProbe`, `Downloader`) in `real`/`traits`.
* **`yerd-php`** - supervises PHP-FPM processes. Drives the `yerd-supervise` state
  machine under `SupervisorPolicy::fpm()`; provides the `FastCgiProbe` `HealthProbe`
  impl, with `pure` holding the FPM-config and release-resolution logic.
* **`yerd-services`** - supervises database / cache engines. Drives the same
  `yerd-supervise` machine under `SupervisorPolicy::database()`; pure `service`,
  `database`, `config_render`, and `release` modules, with I/O in `manager` and
  `health`.
* **`yerd-dns`** - runs the authoritative responder on `tokio` + `hickory-server`.
* **`yerd-service-ctl`** - shells out to `launchctl`/`systemctl` (and signals a
  pid directly as a fallback) to stop/start/restart the `yerdd` service. No
  `pure` submodule of its own - the crate is small enough that the OS-mechanics
  functions are the whole surface - but no `unsafe` either: process signalling
  goes through `nix`'s safe wrappers.

::: details Where the traits are implemented
The trait *definitions* live in the library crates (e.g. `yerd-supervise`'s
`ProcessSpawner`, `yerd-platform`'s `TrustStore`). The library also ships the
production impls (`TokioProcessSpawner`, the per-OS `TrustStore`). Tests substitute
in-memory fakes. The privileged half of `yerd-platform`'s work is executed out of
process by `yerd-helper`, which the daemon or `sudo yerd elevate` invokes.
:::

## Where to go next

* For the runtime picture - how `yerdd` boots, supervises, and serves - see
  [Architecture](./architecture) and [The Daemon](../guide/daemon).
* For the wire contract between client and daemon, see
  [IPC Protocol](./ipc-protocol) and [yerd-ipc](./crates/yerd-ipc).
* For the per-OS adapter model, see [Cross-Platform Model](./cross-platform) and
  [yerd-platform](./crates/yerd-platform).
* To build the workspace, see [Building from Source](./building).

---

---
url: 'https://yerd.app/developer/building.md'
---
# Building from Source

This page is the contributor reference for building, testing, and linting Yerd
from a fresh checkout. Every command, toolchain pin, and CI step below is taken
directly from the repository - [`rust-toolchain.toml`](https://github.com/forjedio/yerd/blob/main/rust-toolchain.toml),
the workspace [`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml),
[`.github/workflows/ci.yml`](https://github.com/forjedio/yerd/blob/main/.github/workflows/ci.yml),
and the GUI's [`apps/yerd-gui/README.md`](https://github.com/forjedio/yerd/blob/main/apps/yerd-gui/README.md).

For the user-facing "drop binaries on your `PATH`" recipe, see the
[Getting Started](../guide/getting-started) guide. This page goes deeper: the
*why* behind the toolchain, the exact gate CI enforces, and the dependency pins
you must not bump blindly.

## The toolchain

Yerd uses a two-tier toolchain story, and it is important to understand both
tiers before touching a manifest.

**The build/dev toolchain is pinned in [`rust-toolchain.toml`](https://github.com/forjedio/yerd/blob/main/rust-toolchain.toml):**

```toml
[toolchain]
channel = "1.96.0"
components = ["clippy", "rustfmt"]
```

When you run any `cargo` command inside the repo, `rustup` reads this file and
installs / selects `1.96.0` (with `clippy` and `rustfmt` available)
automatically. You do not need to choose a toolchain manually - that is the
whole point of the pin. CI verifies the active toolchain with
`rustup show active-toolchain` before doing anything else.

**Why 1.96 and not the claimed MSRV?** The workspace [`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml)
declares `rust-version = "1.77"` for the pure library crates, and that MSRV is
real - the library crates (`yerd-core`, `yerd-config`, `yerd-tls`, …) genuinely
compile on 1.77. But the workspace also contains the Tauri v2 GUI crate
(`apps/yerd-gui/src-tauri`). Current Tauri v2 (`tauri-utils`, its plugins) pulls
`toml 1.x` / `serde_spanned 1.x`, which require **edition2024**, which in turn
requires **rustc ≥ 1.85**. The GUI simply cannot build on 1.77. Because
`cargo build --workspace` and the CI gate compile *everything* (including the
GUI crate), the build toolchain has to be new enough for the GUI - hence the
1.96 pin.

::: info Two numbers, two meanings

* **1.77** - the MSRV advertised in the library crate manifests. It is the floor
  the *pure* crates promise to keep working on. Do not raise it casually; it is a
  compatibility commitment.
* **1.96** - the toolchain you actually build and test with. It is bumped only
  when something (like Tauri) forces it.

Edition is `2021` for the workspace package; the edition2024 requirement comes
only from transitive GUI dependencies, not from Yerd's own code.
:::

## Prerequisites

### Rust

Install Rust via [`rustup`](https://rustup.rs). On first `cargo` invocation in
the repo, `rustup` honours `rust-toolchain.toml` and pulls `1.96.0` plus
`clippy` and `rustfmt`. Nothing else to configure.

### Linux system `-dev` packages (for the GUI crate)

The GUI crate links GTK / WebKit / the system tray, so building or even
`clippy`/`test`-ing the *whole workspace* on Linux needs the Tauri `-dev`
headers. The runtime libraries alone are not enough - you need the development
headers. This is exactly what CI installs on its Ubuntu runner:

```sh
sudo apt-get install -y --no-install-recommends \
  libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev \
  libjavascriptcoregtk-4.1-dev libayatana-appindicator3-dev \
  libdbus-1-dev libxdo-dev librsvg2-dev
```

The GUI README additionally lists `build-essential` and `pkg-config` for a clean
host. `libdbus-1-dev` is needed by `tauri-plugin-single-instance` and the
appindicator tray; `libxdo-dev` by the tray input layer.

::: tip Library-only builds skip all of this
If you only care about the CLI and daemon, you don't need GTK/WebKit at all -
just build the binaries you want (see [Building only the binaries](#building-only-the-binaries-no-gui)).
On macOS the GUI uses system frameworks, so there are **no** extra packages to
install for the full workspace.
:::

### Node 22 + npm (for the frontend and docs)

The desktop app's frontend and this documentation site are built with Node. CI
uses **Node 22** with `npm`. Install Node 22 (any version manager - `nvm`,
`fnm`, `volta` - works; the GUI README notes the dev host uses `fnm`).

## Building

Build the entire workspace - all library crates, all binaries, and the GUI Rust
bridge - with:

```sh
cargo build --workspace
```

For optimised binaries, add `--release`. Release builds strip symbols
(`[profile.release] strip = "symbols"` in the workspace manifest) to keep the
packaged `.deb` small; a debug `yerdd` is ~139 MB. The trade-off is that shipped
panic backtraces lose symbol names - acceptable given the project's
no-panic/no-unwrap rule (see [Lints and conventions](#lints-and-conventions)).

### Building only the binaries (no GUI)

If you don't want to install the GTK/WebKit toolchain, build just the three
binaries. This is the from-source path from the [README](https://github.com/forjedio/yerd/blob/main/README.md):

```sh
cargo build --release -p yerd -p yerdd -p yerd-helper
install -Dm755 target/release/{yerd,yerdd,yerd-helper} -t ~/.local/bin
yerdd serve &                # rootless; runs on 8080/8443 out of the box
```

The three binaries map to the three-process privilege model: the
[`yerdd`](./binaries/yerdd) daemon, the [`yerd`](./binaries/yerd) CLI, and the
privileged one-shot [`yerd-helper`](./binaries/yerd-helper). See
[Elevation & Privileges](../guide/elevation) for why they are separate.

## Running a from-source build with a production Yerd installed

Most contributors keep the released Yerd app installed for day-to-day work and
want to test a from-source build without losing that setup. The catch: the
installed app runs the daemon as a **per-user service**, and the daemon is a
*singleton* - it takes an exclusive instance lock on its runtime directory and
owns the IPC socket the GUI and CLI connect to. Start a second `yerdd` against
the same runtime dir and it exits immediately:

```text
another yerdd is already running (lock held at /tmp/yerd-501/yerd.lock)
```

So there are two workflows: **take over** the production paths (stop production,
run your build in its place) or **isolate** your build onto a separate set of
paths (Linux only). Pick based on your platform and what you're testing.

### Step 1 - stop the production daemon and GUI

First quit the desktop app from the tray / menu-bar icon - it's a daemon
*client*, so quitting it doesn't stop the daemon, but it stops the app from
issuing requests while you work.

Then stop the daemon service itself. The service label is `dev.yerd.daemon` on
macOS (a GUI-scoped `LaunchAgent`) and the `yerd` systemd **user** unit on Linux:

```sh
# macOS
launchctl kill SIGTERM "gui/$(id -u)/dev.yerd.daemon"

# Linux
systemctl --user stop yerd
```

Confirm nothing is listening before you continue - `yerd ping` should now fail:

```sh
yerd ping   # expect a connection error once the daemon is down
```

### Step 2 - rebuild

Rebuild whatever you changed. For daemon/CLI work the binaries are enough (no
GTK/WebKit needed):

```sh
cargo build -p yerdd -p yerd
```

### Step 3 - run your build in the foreground

Run the daemon you just built directly from the workspace. `serve` is the
default subcommand, and `-v` turns up logging so you can watch it come up:

```sh
cargo run -p yerdd -- -v
```

On a rootless host it binds the fallback ports (`http=8080`, `https=8443`) and
prints the socket, DNS, and mail-capture bindings as it starts. Drive it with
your freshly built CLI in another shell:

```sh
cargo run -p yerd -- ping
cargo run -p yerd -- status
```

To exercise the desktop app against your dev daemon, start the daemon first,
then run the GUI in dev mode (see [The frontend](#the-frontend-apps-yerd-gui)):

```sh
cd apps/yerd-gui && npm run tauri dev
```

### Pointing at a different config file

`yerdd` takes `--config` (`-c`) to override **just** the `yerd.toml` location,
which is handy for testing config changes without touching your real one:

```sh
cargo run -p yerdd -- --config ~/yerd-dev.toml -v
```

::: warning `--config` does not isolate the instance
`--config` swaps only the config *file*. The data, state, cache, and - crucially

* the **runtime socket** still resolve to the normal platform directories, so a
  daemon started this way still collides with the instance lock above. Use it
  *after* stopping the production daemon, not alongside it. For a fully parallel
  instance, isolate the directories instead (next section, Linux only).
  :::

### Fully isolating a parallel instance (Linux)

On Linux the directory layout comes from the XDG base-directory variables, so
you can point an entire dev instance at a scratch tree - separate config, data,
state, cache, **and** socket - and run it *alongside* the production daemon
without stopping anything:

```sh
export XDG_CONFIG_HOME=/tmp/yerd-dev/config
export XDG_DATA_HOME=/tmp/yerd-dev/data
export XDG_STATE_HOME=/tmp/yerd-dev/state
export XDG_CACHE_HOME=/tmp/yerd-dev/cache
export XDG_RUNTIME_DIR=/tmp/yerd-dev/run   # different socket → no lock clash
cargo run -p yerdd -- -v
```

Any `yerd` CLI (or `npm run tauri dev` GUI) launched with the *same* environment
resolves the same scratch socket and talks to your dev daemon; a shell without
those variables still reaches production. Tear the instance down by deleting
`/tmp/yerd-dev`.

::: warning macOS has no equivalent override
On macOS the config/data/state/cache paths are fixed to
`~/Library/Application Support/io.yerd.Yerd` and the socket to `/tmp/yerd-$UID`,
with **no** environment override (the daemon and GUI must agree on a single,
discoverable socket path). A from-source daemon therefore shares production's
directories and socket. On macOS you must **stop the production daemon first**
(Step 1) and accept that your build reads and writes the same state - you can't
run two isolated instances side by side.
:::

### Step 4 - restore production

When you're done, stop your foreground daemon (`Ctrl-C`), then bring the service
back and relaunch the app:

```sh
# macOS
launchctl kickstart -k "gui/$(id -u)/dev.yerd.daemon"

# Linux
systemctl --user start yerd
```

## Running tests

```sh
cargo test --workspace
```

This runs every crate's unit and integration tests. The test suite is large and
fast by design: pure logic lives in the library crates and is exercised against
in-memory fakes, while real filesystem / network / process / OS calls sit behind
traits (`ProcessSpawner`, `TrustStore`, `ResolverInstaller`, `PortBinder`,
`Clock`, …) with one implementation per OS. This is what lets the same behaviour
tests run identically on macOS and Linux. The [Cross-Platform Model](./cross-platform)
page covers the trait boundary in detail.

::: warning macOS-only latent test bugs
The trait-fake design means most tests pass on either OS regardless of which
host you're on - which can *hide* a bug that only the real per-OS implementation
would surface. When you change OS-specific code under `yerd-platform`, run the
suite on the affected platform, not just your own. CI runs the full gate on both
`ubuntu-22.04` and `macos-14` (Apple Silicon) for exactly this reason.
:::

## The CI gate (run this before pushing)

CI enforces one gate, and it is identical to what you should run locally. From
[`.github/workflows/ci.yml`](https://github.com/forjedio/yerd/blob/main/.github/workflows/ci.yml),
the `rust` job runs these three commands on both Linux and macOS:

```sh
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

Run all three before opening a PR - they are the exact bar your PR must clear.

| Step | Command | Notes |
|---|---|---|
| Format | `cargo fmt --all --check` | CI runs this on Linux only, but formatting is platform-independent, so checking locally on either OS is sufficient. |
| Lint | `cargo clippy --workspace --all-targets -- -D warnings` | `--all-targets` covers tests/benches/examples too. **Any** warning fails the build (`-D warnings`). |
| Test | `cargo test --workspace` | Full workspace, both OSes in CI. |

::: tip One-liner

```sh
cargo fmt --all --check && \
cargo clippy --workspace --all-targets -- -D warnings && \
cargo test --workspace
```

:::

A second CI job, `frontend`, runs the GUI's JS tests and production build (see
below). The `concurrency` config cancels older in-progress runs when you push
again to the same ref, so only your latest push is graded.

## The frontend (`apps/yerd-gui`)

The desktop app's frontend is **Vue 3 (`<script setup>`) + TypeScript +
Tailwind**, bundled by Vite, tested with Vitest, and type-checked with `vue-tsc`.
All commands run from `apps/yerd-gui`. CI's `frontend` job mirrors this:

```sh
npm ci         # reproducible install from package-lock.json (CI uses this, not `npm install`)
npm run test   # vitest run - frontend unit/component tests
npm run build  # vue-tsc --noEmit && vite build - type-check + production bundle
```

::: info `npm ci` vs `npm install`
CI uses `npm ci` for a clean, lockfile-exact, reproducible install. For local
day-to-day work the GUI README uses `npm install` (or `npm run dev` for the Vite
dev server). Both are fine locally; CI requires `npm ci`.
:::

The available `package.json` scripts:

| Script | Command | Purpose |
|---|---|---|
| `npm run dev` | `vite` | Vite dev server (frontend only, no Rust bridge). |
| `npm run tauri dev` | `tauri` | Full app: webview + Rust bridge. Start `cargo run -p yerdd` first - the GUI is a daemon client. |
| `npm run build` | `vue-tsc --noEmit && vite build` | Type-check, then the production Vite build. |
| `npm run test` | `vitest run` | Run the frontend test suite once. |
| `npm run test:watch` | `vitest` | Vitest in watch mode. |
| `npm run typecheck` | `vue-tsc --noEmit` | Type-check only. |
| `npm run preview` | `vite preview` | Preview a built bundle. |

The Rust side of the bridge is part of the workspace, so its unit tests run under
`cargo test --workspace` (or in isolation via `cargo test -p yerd-gui`, which
needs the Linux `-dev` packages). The bridge is deliberately thin: each Tauri
command maps to a single IPC `Request` to the daemon. See
[Desktop App Internals](./gui) and the [IPC Protocol](./ipc-protocol) page.

## The `=` dependency pins (do not bump blindly)

The workspace manifest contains several **exact** version pins (`=x.y.z`) plus a
long comment block explaining each one. They exist for two distinct reasons -
**MSRV protection** and **wire-stability tripwires** - and bumping one without
understanding its category can break fresh checkouts or silently weaken a safety
net. Always read the comment in [`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml)
before touching a pin.

### MSRV-driven pins

Several transitive dependencies have introduced edition2024 requirements in newer
releases. Even though the build toolchain is 1.96, these pins keep the *resolved*
dependency graph buildable and the library MSRV story honest. The manifest pins
`time = "=0.3.36"` (newer pulls `time-core 0.1.8` → edition2024) and `clap`,
`tempfile`, etc. to specific versions. Some pins live in `Cargo.lock` rather than
the manifest (the lockfile is the source of truth), applied via
`cargo update -p <crate> --precise <ver>`:

| Crate | Pinned to | Why |
|---|---|---|
| `time` | `=0.3.36` (manifest) | `0.3.37+` pulls `time-core 0.1.8`, which needs edition2024. |
| `indexmap` | `2.13.0` (lockfile) | `2.14+` requires edition2024. |
| `idna_adapter` | `1.0.0` (lockfile) | `1.2+` needs rustc 1.86; pulled transitively via `hickory-proto`'s `idna`. Without it, fresh checkouts fail to even parse the manifest under older cargo. |
| `jobserver` | `0.1.32` (lockfile) | `0.1.34+` pulls a `getrandom 0.3 → wasi 0.14 → wit-bindgen` chain whose manifest needs edition2024. Comes in via `cc → ring → rustls/rcgen`. |
| `hyper-rustls` | `0.27.5` (lockfile) | `0.27.6+` needs rustc 1.85. Pulled by `reqwest`, only via `yerd-php`'s optional `download` feature - invisible to the default build, only bites `--all-features`. |

These all relax once the MSRV moves past 1.85 / edition2024.

### Wire-stability tripwire pins

Two pins are **not** about MSRV - they convert silent upstream additions to
`#[non_exhaustive]` error/data enums into a deliberate, reviewed version bump:

| Crate | Pinned to | Why |
|---|---|---|
| `rcgen` | `=0.13.2` | `rcgen::Error` is `#[non_exhaustive]`; the pin flips the `rcgen_error_detail_table_is_current` tripwire test in [`yerd-tls`](./crates/yerd-tls) if upstream adds a variant. |
| `hickory-proto` / `hickory-server` / `hickory-client` | `=0.24.4` | Same reasoning for `ProtoErrorKind` / `RData`, which are `#[non_exhaustive]` upstream - used by [`yerd-dns`](./crates/yerd-dns). |

::: warning Before bumping any `=` pin

1. Read the comment block at the bottom of [`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml) - it documents every pin's reason.
2. If it is a **tripwire** pin (`rcgen`, `hickory-*`), expect the bump to trip a test (e.g. `rcgen_error_detail_table_is_current`). Update the corresponding mapping table in the affected crate *deliberately*, don't just silence the test.
3. If it is an **MSRV** pin, confirm the new version still builds the workspace and doesn't drag in a fresh edition2024 dependency.
4. Run the full gate (`fmt` + `clippy` + `test`) on **both** OSes - many of these traps only surface on a clean lockfile resolution.
   :::

## Lints and conventions

The workspace declares strict lints in [`Cargo.toml`](https://github.com/forjedio/yerd/blob/main/Cargo.toml)
that the `clippy -D warnings` gate enforces:

```toml
[workspace.lints.rust]
unsafe_code  = "forbid"
missing_docs = "warn"

[workspace.lints.clippy]
unwrap_used      = "deny"
expect_used      = "deny"
panic            = "deny"
todo             = "deny"
dbg_macro        = "deny"
indexing_slicing = "deny"
pedantic         = { level = "warn", priority = -1 }
```

In practice: no `unsafe`, no `unwrap`/`expect`/`panic` outside tests, no
`todo!`/`dbg!`, no slice indexing that could panic - all clippy-enforced. Use
`thiserror` in libraries and `anyhow` only at binary top level. The
[Contributing](./contributing) guide expands on these conventions.

## Packaging and releasing

Build automation lives in the [`xtask`](./xtask) crate, invoked as
`cargo xtask <command>`. It exposes two subcommands:

```sh
cargo xtask bump 2.0.2           # set the version across the three manifests
cargo xtask version-check v2.0.2 # release gate: assert a tag matches the manifests
```

The shipped artifacts are the **GUI bundle** (`.dmg` on macOS, `.deb` on Linux),
**plus a native Arch package** (`.pkg.tar.zst`, x86-64) **and a Fedora package**
(`.rpm`, x86-64 and arm64). The three binaries
(`yerd`/`yerdd`/`yerd-helper`) are embedded via Tauri `externalBin`
(per-platform overlays in `apps/yerd-gui/src-tauri/`). Tauri builds the `.app`
(macOS) and `.deb` (Linux) directly; the macOS `.dmg` is built as a separate
headless step (`apps/yerd-gui/scripts/build-macos-dmg.sh`, via `appdmg`) after
the `.app`, not by Tauri's own dmg bundler - see
[macOS code signing & notarisation](#macos-code-signing-notarisation) below
for why. The CLI and daemon are never shipped on their own - there is no
CLI-only artifact (tarball or `.deb`) separate from the GUI bundle and the
Arch package.

`bump` keeps three files in sync - `Cargo.toml`,
`apps/yerd-gui/src-tauri/tauri.conf.json`, and `apps/yerd-gui/package.json` - so
the CLI/daemon and the GUI never disagree on version. The release pipeline runs
`version-check` to fail fast on a mismatched tag. See
[Build Automation (xtask)](./xtask) for the full breakdown.

### The Arch package (`.pkg.tar.zst`)

Tauri has no pacman bundler, so the Arch package is built separately: the `arch`
job in [`release.yml`](https://github.com/forjedio/yerd/blob/main/.github/workflows/release.yml)
runs an `archlinux:base-devel` container, compiles the frontend + all four
binaries from source, and assembles the package with
[`packaging/arch/PKGBUILD`](https://github.com/forjedio/yerd/blob/main/packaging/arch).
The package installs the four binaries as real files in `/usr/bin` - the three
driven binaries (`yerd`/`yerdd`/`yerd-helper`) land at the same paths as the
upstream `.deb`, so the daemon's sibling-binary lookup is identical (the GUI binary
is `/usr/bin/yerd-gui`). A `.install` scriptlet `setcap`s `/usr/bin/yerdd` on
install/upgrade so the daemon can bind ports 80/443.

In-app `yerd update` on Arch runs `pacman -U` on the downloaded, minisign-verified
`.pkg.tar.zst` - a **partial upgrade**: if the host is behind on `pacman -Syu`, a
newer library soname can make it abort (Yerd surfaces pacman's message), so Arch
users should keep their system current. It also requires the default
`LocalFileSigLevel = Optional` in `pacman.conf` - the package is not pacman-signed
(Yerd verifies it itself with the embedded update key), so a hardened
`LocalFileSigLevel = Required` rejects the local install.

The Arch package's minisign signature is published as `<pkg>.pkg.tar.zst.minisig`,
not `.sig`. pacman reserves `<pkg>.sig` for a detached OpenPGP signature and feeds
any such sibling to GPGME, so a minisign file under that name hard-fails
`pacman -U` even at `LocalFileSigLevel = Optional` (a missing signature is
tolerated, a present-but-unparseable one is fatal) - this was
[#157](https://github.com/forjedio/yerd/issues/157). The other artifact kinds
(`.app.tar.gz`, `.deb`, `.rpm`) publish a byte-identical legacy `<artifact>.sig`
copy alongside the `.minisig` for a bounded transition window, so self-updaters
built at v2.0.3 or earlier keep resolving a signature; that copy is retired once
those clients have moved on, and the pacman `.sig` is never re-published (the
release workflow fails the publish if a `*.pkg.tar.zst.sig` is present).

### The Fedora package (`.rpm`)

Unlike pacman, Tauri v2 **does** have an rpm bundler (pure-Rust, no `rpmbuild`),
so the `.rpm` reuses the normal Tauri bundle machinery rather than a hand-written
spec. The `fedora` jobs in
[`build.yml`](https://github.com/forjedio/yerd/blob/main/.github/workflows/build.yml)
run on the Ubuntu runners (x86-64 and arm64), build the sidecars with
`--features yerdd/rpm`, and run `tauri build` with the
`tauri.bundle-linux-rpm.conf.json` overlay (rpm `depends` + an `rpm/postinst.sh`
`%post` that `setcap`s `/usr/bin/yerdd`, mirroring the deb postinst). Because the
bundler runs on Ubuntu, a **blocking** `fedora:latest` smoke job in `release.yml`
`dnf install`s the produced `.rpm` (proving every `Requires` resolves) and asserts
`yerdd --pkg-format` before the release can publish.

In-app `yerd update` on Fedora runs `rpm -U --oldpackage` on the downloaded,
minisign-verified `.rpm`. Like `dpkg -i`/`pacman -U` it does no dependency
*resolution*, but it does *check* dependencies, so the packaged `depends` list must
stay stable across releases (a newly-added `Requires` would abort an existing
user's self-update); Yerd surfaces rpm's message on failure.

**The `pacman`/`rpm` feature / `PkgFormat` tiebreak.** A release carries a `.deb`,
a `.pkg.tar.zst`, and a `.rpm` for the same arch, so a running Linux binary can't
tell which to self-update from `Platform` (OS + arch) alone. The format is fixed at
**build time**: `yerd_update::PkgFormat::current()` returns `Pacman` only when
compiled with the `pacman` Cargo feature and `Rpm` only with the `rpm` feature
(the two are mutually exclusive - enabling both is a `compile_error!`). The `arch`
job builds the daemon with `--features yerdd/pacman`, the `fedora` job with
`--features yerdd/rpm`, so each `yerdd` selects its own package and the applier
installs it via `pacman -U` / `rpm -U --oldpackage`; every other build defaults to
`Deb`/`dpkg -i`. **This only works because each distro package is built in a
separate job (its own cargo invocation/target dir)** - within one cargo build, the
feature would unify across the whole graph. The release gate proves the flag took by
running the freshly-built `yerdd --pkg-format` and asserting it prints
`pacman`/`rpm`.

**`tauri/custom-protocol` is required too.** `PKGBUILD`'s `build()` builds the
GUI binary with a raw `cargo build`, not `tauri build`/`npm run tauri build` -
so it must pass `--features yerdd/pacman,tauri/custom-protocol` explicitly.
`tauri build` injects `custom-protocol` automatically; a bare `cargo build`
doesn't. Without it, Tauri's `generate_context!()` bakes `dev: true` into the
binary, and at runtime it tries to load `devUrl` (`http://localhost:1420`)
instead of the embedded frontend `dist` - the GUI fails to load at all, with
"Could not connect to localhost: Connection refused".

### macOS code signing & notarisation

The release workflow Developer ID signs **and** notarises the macOS artifact:
the GUI `.app` (signed, notarised and stapled by Tauri) and its `.dmg`
(codesigned only, by `apps/yerd-gui/scripts/build-macos-dmg.sh` after Tauri
builds the `.app` - not notarised or stapled, and deliberately so: only the
`.app` staple is enforced in CI, the `.dmg`'s own notarisation/staple is
advisory and non-fatal, since the stapled `.app` inside is the gate). The
three embedded binaries (`yerd`/`yerdd`/`yerd-helper`) are signed by Tauri **as
part of the bundle** (Hardened Runtime + secure timestamp + the app's Developer ID
team) and covered by the single `.app` notarisation - so there are no loose,
separately-notarised CLI binaries. Notarisation uses an **App Store Connect API
key**. The CI verify step asserts each embedded binary is Developer-ID signed,
Hardened-Runtime, timestamped, team-matched, and free of broad entitlements
(`allow-jit` / `allow-unsigned-executable-memory` / `get-task-allow`).

This is driven entirely by GitHub Actions **secrets** - there's nothing to
configure in a normal build. To (re)provision them:

| Secret | What it is |
|---|---|
| `APPLE_CERTIFICATE` | base64 of the exported **Developer ID Application** `.p12` |
| `APPLE_CERTIFICATE_PASSWORD` | the `.p12` export password |
| `APPLE_SIGNING_IDENTITY` | `Developer ID Application: <Name> (<TEAMID>)` |
| `APPLE_API_ISSUER` | App Store Connect API **Issuer ID** |
| `APPLE_API_KEY` | App Store Connect API **Key ID** (not the file) |
| `APPLE_API_KEY_P8` | base64 of the `AuthKey_<KEYID>.p8` key file |

**Rotation.** Developer ID certificates last ~5 years - regenerate from a new CSR
(Keychain Access → Certificate Assistant), export a fresh `.p12`, and update
`APPLE_CERTIFICATE`/`APPLE_CERTIFICATE_PASSWORD`/`APPLE_SIGNING_IDENTITY`. API
keys are revocable in App Store Connect → Users and Access → Integrations; create
a replacement (role **Developer**) and update `APPLE_API_*`/`APPLE_API_KEY_P8`.

The GUI's signing config lives in `apps/yerd-gui/src-tauri/tauri.conf.json`
(`bundle.macOS`) and `apps/yerd-gui/src-tauri/entitlements.plist` (the
Hardened-Runtime entitlements - note it must **not** carry `get-task-allow`).

**Verifying a release.** The `gui` job verifies fail-closed before publishing. To
check by hand on a Mac: `xcrun stapler validate Yerd.app` (should pass - this is
the actual gate), `spctl -a -t open --context context:primary-signature -vvv
Yerd.dmg` (expect `source=Unnotarized Developer ID` - the `.dmg` itself is
signed-only, not notarised, so this is normal and not a sign of a broken
release), and `codesign -dv --verbose=4 Yerd.app/Contents/MacOS/yerdd` (expect
`Authority=Developer ID Application`).

## See also

* [Architecture](./architecture) - how the pieces fit together.
* [Crates Overview](./crates) - the workspace's crate map and boundaries.
* [Cross-Platform Model](./cross-platform) - the per-OS trait implementations.
* [Contributing](./contributing) - workflow and conventions.

---

---
url: 'https://yerd.app/developer/contributing.md'
---
# Contributing

This page is the set of conventions every contribution to Yerd must follow. They
are not style preferences - most are mechanically enforced by `clippy`,
dependency-graph tests, and wire-stability tests, and CI fails the moment one is
violated. Read this before opening a pull request; it will save you a round-trip
through the gate.

For the *why* behind these rules, see [Architecture](./architecture) and the
[Cross-Platform Model](./cross-platform). For getting a working build, see
[Building from Source](./building).

::: info The one organising rule

> **Pure logic lives in library crates. I/O and OS calls are pushed to the edges
> behind traits.**

Everything below is a consequence of that single sentence. If a rule ever seems
arbitrary, re-read it in light of this one.
:::

## Layering and purity

Before you write a module, decide which layer it belongs to:

* **Pure** - no I/O, synchronous, runtime-free. It takes data in and returns
  data or a `Result`. It never reads the filesystem, network, clock, or
  environment, and never spawns a process. It must be unit-testable with
  in-memory fixtures and zero setup.
* **Edge** - does I/O, may be `async`. This is where side effects happen, behind
  a trait.

Do not mix the two in one function. Many crates split this physically: a `pure/`
module (sync, no runtime) and an `io/` or `os/` module (the side-effecting
edge). Put new code in the matching directory. `yerd-core` is the exemplar of a
fully pure crate - keep it pure.

If a pure function needs the clock, env, filesystem, network, or a child
process, **do not reach for it directly** - take it as a trait parameter and let
the caller inject it. The real implementations live in `yerd-platform` or in a
crate's `os/` module behind `#[cfg(...)]`; the existing traits include:

```
BackendResolver  CertStore   ChildHandle   Clock         Downloader
HealthProbe      Paths       PortBinder    PortRedirector ProcessSpawner
ResolverInstaller  SystemMetrics  TrustStore
```

Binaries (`bin/yerdd`, `bin/yerd`, `bin/yerd-helper`, and the Tauri
`src-tauri` layer) are **thin**. They wire crates together and own transports.
They contain orchestration, not behaviour - interesting logic belongs in a crate
with tests.

::: warning
The daemon (`yerdd`) is the single source of truth for runtime state. The CLI
and the GUI are both [`yerd-ipc`](./crates/yerd-ipc) *clients* - neither may
reimplement daemon logic. If you find yourself duplicating daemon behaviour in a
client, stop.
:::

### Dependency direction

Internal dependencies flow strictly downhill; there are no cycles.

```mermaid
flowchart LR
    core["yerd-core"]
    ipc["yerd-ipc"]
    config["yerd-config"]
    doctor["yerd-doctor"]
    tls["yerd-tls"]
    platform["yerd-platform"]
    php["yerd-php"]
    proxy["yerd-proxy"]
    bins["binaries"]
    gui["gui"]

    ipc --> core
    config --> ipc
    doctor --> ipc
    bins --> ipc
    gui --> ipc

    platform --> tls
    php --> platform
    proxy --> platform
    bins --> platform
```

* `yerd-core` depends on no other `yerd-*` crate.
* Libraries never depend on binaries.
* The CLI and GUI depend on `yerd-ipc` (plus its transport feature), not on the
  daemon's internals.

See the [Crates Overview](./crates) for the full map.

## Forbidden in non-test code

These constructs are **`clippy`-denied** workspace-wide via `[workspace.lints]`
in the root `Cargo.toml`, so `cargo clippy --workspace --all-targets -- -D
warnings` rejects them:

| Construct | Lint | Level |
|---|---|---|
| `unsafe` blocks | `unsafe_code` | `forbid` (rust) |
| `.unwrap()` | `clippy::unwrap_used` | `deny` |
| `.expect(...)` | `clippy::expect_used` | `deny` |
| `panic!` | `clippy::panic` | `deny` |
| `todo!` | `clippy::todo` | `deny` |
| `dbg!` | `clippy::dbg_macro` | `deny` |
| `v[i]` slice/array indexing | `clippy::indexing_slicing` | `deny` |

`unsafe_code` is `forbid` (stronger than `deny` - it cannot be locally
re-allowed), and crate roots additionally carry `#![forbid(unsafe_code)]` as a
belt-and-braces declaration:

```rust
#![forbid(unsafe_code)]
```

Instead of the forbidden forms, use total functions and explicit handling:
`get(i)` instead of `v[i]`, pattern matching or `?` instead of `unwrap`, and a
typed error variant instead of `panic!`/`unreachable!`. The pedantic clippy
group is `warn`-level too, with a handful of project-wide opt-outs
(`module_name_repetitions`, `missing_errors_doc`, `missing_panics_doc`,
`must_use_candidate`, `cast_possible_truncation`, `needless_pass_by_value`).

::: tip Tests are the only exception
Test files may use the forbidden constructs, but you must opt out **explicitly**
at the top of the file so the exception is visible and scoped:

```rust
#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::indexing_slicing)]
```

:::

Also note: `missing_docs` is `warn`, so document every public item.

## Error handling

* **Libraries use `thiserror`.** Each crate exposes one typed error enum from
  `error.rs`, with specific, matchable variants. There is **no `anyhow` in
  library code, nor anywhere in a library's dependency graph.**
* **Binaries may use `anyhow`** at the top level (`main` / command handlers) for
  context-rich exit errors. Convert typed crate errors with `?` /
  `.context(...)`.
* Never collapse distinct failures into a generic `Internal`/`Other` variant
  when a caller could reasonably branch on them - add a variant.

A real example: `yerd-tls` carries typed sub-reasons rather than wrapping the
upstream `rcgen::Error` (which is not `Clone`), so its error type stays
`Clone + PartialEq + Eq`:

```rust
/// Errors produced by `yerd-tls`.
#[derive(Debug, Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum TlsError {
    /// Failed while building or signing new certificate material.
    #[error("could not generate certificate material: {reason}")]
    Generate { reason: GenerateErrorReason },

    /// Failed while parsing CA material handed in via PEM strings.
    #[error("could not parse certificate material: {reason}")]
    Parse { reason: ParseErrorReason },

    /// Validity window failed construction-time validation.
    #[error("invalid validity window: {reason}")]
    Validity { reason: ValidityErrorReason },
}
```

Mark public error enums `#[non_exhaustive]` so adding variants stays
semver-compatible.

## Comments

Comments are for the next human reading the code, not narration of it. Keep
them short, in plain English, and accurate - fix or delete a comment that has
drifted from what the code actually does.

* **No inline comments inside function bodies.** If a line needs a comment to
  be understood, make the code clearer instead - extract a well-named function,
  rename a variable, restructure the branch. Two exceptions: a `// SAFETY:`
  justification on the rare `unsafe` block, and a short field label on an
  otherwise-opaque byte or magic number in protocol code (`1, // version`).
* **Prefer item and module docs (`///`, `//!`) over inline narration.** Document
  the non-obvious *why* - RFC references, gotchas, cross-platform quirks - not
  the obvious *what*. Don't restate the signature.
* **Skip docs on self-evident private items** where the name says it all.
  Public (`pub`) items still get a short doc line even when obvious, since
  `missing_docs` is `warn` and it feeds the generated API docs.
* **No em dashes in comments.** Use a plain hyphen, comma, or colon instead.

## Testing standard

A change is not done until it is tested at the right layer. The four kinds of
test, and where each applies:

1. **Table-driven unit tests for pure logic.** Pure functions get exhaustive,
   data-driven tests next to the code (or in the crate's `tests/`). This is the
   bulk of the suite and runs with zero setup.
2. **Fakes behind traits for side effects.** Never perform real I/O in a unit
   test. Inject a fake implementation of the relevant trait (`ProcessSpawner`,
   `TrustStore`, `Clock`, …) and assert on the recorded interactions. If you add
   a new side effect, it goes behind a trait *and* gets a fake-backed test.
3. **Integration tests for wiring.** When you wire crates together, add an
   integration test in the crate's `tests/` directory that exercises the seam.
4. **Wire-stability / golden tests.** `serde` JSON (IPC) and TOML (config)
   shapes are a contract, pinned byte-for-byte. `yerd-ipc` has
   `tests/wire_stability.rs`, `yerd-core` has its own `wire_stability.rs`, and
   `yerd-php` ships a `fpm_conf_golden.rs`.

The wire-stability tests assert exact serialized bytes for every IPC variant,
for example:

```rust
#[test]
fn request_park_byte_shape() {
    let r = Request::Park { path: PathBuf::from("/srv/foo") };
    let s = serde_json::to_string(&r).unwrap();
    assert_eq!(s, r#"{"type":"park","path":"/srv/foo"}"#);
    let back: Request = serde_json::from_str(&s).unwrap();
    assert_eq!(back, r);
}
```

::: warning Do not "fix" a wire-stability or golden failure by editing the expected output
A failing byte-shape or golden test almost always means an *accidental* rename,
reorder, or casing change - not that the literal is wrong. Only update the
expected output when you are deliberately making a contract change, and when you
do, bump the protocol version accordingly. See the
[IPC Protocol](./ipc-protocol) page for the additive-evolution rules.
:::

## Dependency policy and version pins

* **Add dependencies through `[workspace.dependencies]`** in the root
  `Cargo.toml` and reference them with `name.workspace = true`. Match the
  existing feature-flag style: `default-features = false` plus explicit features
  is the norm.
* **TLS is `rustls` + `rcgen`. Never OpenSSL or `native-tls`.** Several crates
  enforce this through the dep-graph test below.
* **Respect `=` version pins.** They exist for MSRV traps or to turn silent
  upstream `#[non_exhaustive]` additions into deliberate version bumps. Read the
  comment next to a pin in the root manifest before touching it.

The currently pinned crates (and the reason, abbreviated):

| Pin | Reason |
|---|---|
| `tempfile = "=3.10.1"` | version pin |
| `rcgen = "=0.13.2"` | `rcgen::Error` is `#[non_exhaustive]`; pin forces a deliberate bump that trips `yerd-tls`'s detail-table tripwire |
| `time = "=0.3.36"` | 0.3.37+ pulls `time-core` requiring edition2024; keeps resolved `time-core` at 0.1.2 |
| `hickory-proto`/`hickory-server`/`hickory-client = "=0.24.4"` | `ProtoErrorKind` / `RData` are `#[non_exhaustive]` upstream |
| `clap = "=4.5.20"` | version pin |

Further edition2024 / MSRV traps (`indexmap`, `idna_adapter`, `jobserver`,
`hyper-rustls`) are pinned in `Cargo.lock` via `cargo update --precise`; the
lockfile is the source of truth for those. The full rationale lives in the
comments at the bottom of the root `Cargo.toml`.

### The `no_runtime_deps` guard

Several crates ship a `tests/no_runtime_deps.rs` that walks the resolved
dependency graph with `cargo metadata` and fails if a forbidden crate (`anyhow`,
`reqwest`, `openssl*`, `native-tls`) is reachable through normal-kind edges, or
if a sensitive crate (`tokio`, `time`) resolves to more than one version. For
example, `yerd-tls`'s guard asserts:

```rust
// (1) No tokio in the runtime graph.
assert!(!reachable_pairs.iter().any(|(n, _)| *n == "tokio"), ...);
// (2) No anyhow in the runtime graph.
assert!(!reachable_pairs.iter().any(|(n, _)| *n == "anyhow"), ...);
// (3) Exactly one `time` version.
// (4) Exactly one `x509-parser` version.
```

If you add a dependency, run that crate's tests. **Do not weaken this guard** to
make it pass - a failure means the new dependency dragged in something
forbidden, and the fix is the dependency, not the test.

::: info Async only at the edge
Only edge layers may depend on `tokio`. Never add `tokio` (or any async runtime)
to a crate or module that is meant to be pure - the `no_runtime_deps` test will
catch it for the crates that ship the guard.
:::

## Cross-platform discipline

Per-OS code is selected with `#[cfg(target_os = ...)]`; exactly one of `linux`,
`macos`, or `unsupported` is active per build (Windows adapters are **planned**,
not implemented - do not assume Windows code paths exist).

* **Mirror per-OS changes.** When you touch one OS path, make the equivalent
  change - or a deliberate, commented no-op - in the others. A change that
  compiles only on the host OS will break CI on the other platform. CI runs on
  both Linux and macOS.
* **Keep OS-specific *decisions* in pure helpers** (parsing `profiles.ini`,
  planning ports, matching PEM, …) so they are unit-testable without the OS
  effect itself.
* **Watch for latent single-OS bugs** - macOS-only test fixtures or path
  assumptions are a recurring trap. A test that only the host happens to satisfy
  is a bug waiting for the other runner.

The [Cross-Platform Model](./cross-platform) page covers the `os/{linux,macos,
unsupported}` adapter layout in detail.

::: warning `yerd-helper` is the security boundary
`yerd-helper` is the only privileged surface. It takes strict typed arguments,
**never** shells out, **never** takes network input, performs exactly one
operation, and exits. The GUI process must **never** run as root. Treat any
change near this binary as security-sensitive. See
[yerd-helper](./binaries/yerd-helper).
:::

## Definition of Done

A change is complete only when every box is checked:

* \[ ] Pure logic has **table-driven unit tests**.
* \[ ] Every side-effecting path is **behind a trait and tested with a fake**.
* \[ ] Wiring has an **integration test** in the crate's `tests/`.
* \[ ] **No `unwrap`/`expect`/`panic`/indexing** outside tests; no `unsafe`.
* \[ ] Errors are **typed (`thiserror`)**; no `anyhow` in a library.
* \[ ] New deps are in `[workspace.dependencies]`, pins respected, and the
  `no_runtime_deps` guard still passes.
* \[ ] Per-OS changes are **mirrored** across `linux` / `macos` / `unsupported`.
* \[ ] Public items are **documented**; wire/golden tests changed only on purpose
  (with a protocol-version bump if the IPC contract moved).
* \[ ] The full gate passes on **both Linux and macOS**:

```sh
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

* \[ ] Frontend changes pass `npm run test` and `npm run build` in
  `apps/yerd-gui`.

## When a task conflicts with these boundaries

Stop and surface the conflict rather than working around it. In particular: if a
change would add I/O to a pure crate, route a side effect around a trait, give
the GUI privileged access, or break the IPC contract - raise it in the pull
request or an issue instead of quietly implementing it.

The source lives at
[github.com/forjedio/yerd](https://github.com/forjedio/yerd). For the build
toolchain and GUI prerequisites, continue to [Building from Source](./building).

---

---
url: 'https://yerd.app/developer/ipc-protocol.md'
---
# IPC Protocol

This page is the contributor-facing reference for the protocol spoken between the daemon (`yerdd`) and its clients - the `yerd` CLI and the Tauri desktop app. Everything here lives in the [`yerd-ipc`](./crates/yerd-ipc) crate (`crates/yerd-ipc/`), with socket/pipe binding deferred to the binaries.

The crate has three jobs, layered so they can be tested in isolation:

```
  message model      Request / Response / ErrorCode + status payloads   (always built)
  JSON codec         encode_message / decode_message (serde_json)        (always built)
  frame codec        encode_frame / FrameDecoder (4-byte length prefix)  (always built)
  ----------------------------------------------------------------------------------
  transport          read_frame / read_message / write_message (tokio)   (feature = "transport")
  socket / pipe      interprocess local-socket bind + connect            (lives in the binaries)
```

The top three layers are **pure**: no sockets, no async, no I/O. The `transport` feature pulls in `tokio` async helpers; the actual socket/named-pipe binding never enters the crate at all - it lives in `yerdd`, `yerd`, and the Tauri sidecar.

::: info Source map
`crates/yerd-ipc/src/`: `lib.rs` (re-exports + `PROTOCOL_VERSION`), `frame.rs` (framing), `message.rs` (JSON codec), `request.rs` / `response.rs` / `status.rs` (the wire types), `dump.rs` (the Laravel ▸ Dumps data model: `DumpCategory`, `DumpEvent`, `DumpCounts`, `DumpExtStatus`), `error.rs` (`FrameError` / `IpcError`), `transport.rs` (feature-gated async helpers). Tests: `tests/frame_codec.rs`, `tests/wire_stability.rs`, `tests/roundtrip.rs`. Browse them on [GitHub](https://github.com/forjedio/yerd).
:::

## Transport

The default build of `yerd-ipc` has no transport at all. Enable it explicitly:

```toml
# yerdd / yerd / the Tauri backend depend on it like this
yerd-ipc = { path = "../../crates/yerd-ipc", features = ["transport"] }
```

In the crate's own `Cargo.toml`, `tokio` is `optional = true` and the feature simply turns it on:

```toml
[features]
default   = []
transport = ["dep:tokio"]
```

Keeping the codec runtime-free means tests of framing and wire shapes compile and run with no async runtime, and any consumer that only needs the *types* (for example, to share `Request`/`Response` definitions) pays nothing for `tokio`.

The transport helpers in `transport.rs` are generic over `tokio::io::AsyncRead` / `AsyncWrite` - they never name a concrete socket type. The concrete binding is done in the binaries with the [`interprocess`](https://crates.io/crates/interprocess) crate's `local_socket`, which maps to:

* **Unix domain socket** on macOS and Linux - `<runtime>/yerd.sock`, where `<runtime>` is resolved by `yerd-platform` (with the `/tmp/yerd-$UID` fallback when `XDG_RUNTIME_DIR` is unset). The daemon removes any stale socket file, then `restrict_to_owner`s it (`0o700` runtime dir plus an owner-only socket) because the IPC server performs no peer-credential check - file permissions are the access boundary.
* **Named pipe** on Windows - currently `yerd-<pid>` via `GenericNamespaced`.

The daemon side (`bin/yerdd/src/startup.rs`) selects the name per OS:

```rust
#[cfg(unix)]
let socket_path = dirs.runtime.join("yerd.sock");
// ... to_fs_name::<GenericFilePath>() ...
#[cfg(windows)]
let name = {
    let pipe = format!("yerd-{}", std::process::id());
    pipe.clone().to_ns_name::<GenericNamespaced>()? // namespaced pipe
};
let listener = ListenerOptions::new().name(name).create_tokio()?;
```

::: warning Windows client is not wired up yet
The `yerd` CLI derives the Unix socket path *identically* to the daemon, so they always agree. The Windows pipe name is PID-based and therefore not derivable by a client; the CLI returns `ClientError::DaemonUnreachable` on non-Unix targets today. This is tracked as a follow-up - treat full Windows client support as roadmap. See [Cross-Platform Model](./cross-platform).
:::

The accept loop is one `tokio::spawn` per connection, and a connection is a long-lived request/response stream - the daemon reads a `Request`, dispatches it, writes a `Response`, and loops until EOF (`bin/yerdd/src/ipc_server.rs`). The CLI typically does a single exchange and drops the connection.

## Framing

Every message is one **length-prefixed frame**: a 4-byte big-endian `u32` length followed by exactly that many payload bytes. The codec is byte-agnostic - it takes and returns `&[u8]` / `Vec<u8>` and never inspects the payload - so framing and the JSON codec are fully orthogonal.

```
+----------------+--------------------------------+
| len: u32 (BE)  | payload: `len` bytes           |
+----------------+--------------------------------+
   4 bytes          0 .. DEFAULT_MAX_FRAME
```

The maximum frame size is **16 MiB**:

```rust
/// 16 MiB - the default maximum frame size on both sides.
pub const DEFAULT_MAX_FRAME: usize = 16 * 1024 * 1024;
```

### Encoding

`encode_frame` validates the payload length against a caller-supplied `max` (inclusive - `len == max` is allowed) and prepends the big-endian length:

```rust
pub fn encode_frame(payload: &[u8], max: usize) -> Result<Vec<u8>, FrameError>;
```

It fails with `FrameError::TooLarge { size, max }` if the payload exceeds `max`, or `FrameError::PayloadOverflowsLengthPrefix { size }` if the length does not fit in the 4-byte prefix (only reachable on 64-bit hosts). Both sides default to `DEFAULT_MAX_FRAME`; the sender's cap lets it reject an oversized payload before it ever hits the wire, while the receiver enforces its own cap independently.

### Decoding - `FrameDecoder`

`FrameDecoder` is the stateful read side. You feed it socket bytes and pull complete frames:

```rust
let mut dec = FrameDecoder::new();          // DEFAULT_MAX_FRAME cap
dec.extend_from_slice(&chunk);              // append raw socket bytes
match dec.next_frame()? {
    Some(payload) => { /* one full frame; surplus stays buffered */ }
    None          => { /* header or body incomplete - read more */ }
}
```

It is built to survive the realities of stream sockets, all pinned in `tests/frame_codec.rs`:

| Situation | Behaviour |
| --- | --- |
| **Partial header** (< 4 bytes) | `next_frame()` returns `Ok(None)` |
| **Partial body** (header read, body short) | `Ok(None)` |
| **Multiple frames in one buffer** (pipelined) | successive `next_frame()` calls drain them in order |
| **Trailing surplus bytes** | kept buffered for the next frame; `buffered()` reflects the count |
| **Slow-loris, one byte at a time** | reassembles correctly over many `extend_from_slice` calls |
| **Declared length > `max`** | `Err(FrameError::TooLarge { size, max })`, decoder is **poisoned** |

::: details Decoder poisoning
When `next_frame` rejects an oversized declared length, the decoder is *poisoned*: it clears (and shrinks) its internal buffer to release memory, every later `next_frame()` returns the same `TooLarge` error, and `extend_from_slice` becomes a no-op. Because `buffered()` then returns 0, a subsequent EOF on a poisoned decoder surfaces through the transport layer as `IpcError::UnexpectedEof { bytes: 0 }`. Tested by `decoder_stays_poisoned_after_oversized`.
:::

An empty payload is a valid frame - `encode_frame(b"", _)` yields exactly `[0, 0, 0, 0]`.

## JSON codec

`message.rs` is a thin pair of `serde_json` wrappers that map errors into the IPC error space:

```rust
pub fn encode_message<T: Serialize>(value: &T) -> Result<Vec<u8>, IpcError>;     // -> IpcError::Encode
pub fn decode_message<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, IpcError>; // -> IpcError::Decode
```

The framing layer carries this UTF-8 JSON; the two never depend on each other.

## Message model

Both envelopes are `enum`s, **internally tagged on `type`**, `snake_case`, and `#[non_exhaustive]`:

```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Request { /* ... */ }
```

`#[non_exhaustive]` means consumers in other crates cannot exhaustively match, so new variants are additive without a breaking change.

The two derives differ in one respect: `Request` derives `Eq`, but **`Response` does not** - it is `PartialEq` only. `Response::Dumps` carries `DumpEvent`s whose `payload` is an opaque `serde_json::Value` (which can hold floats, so it is `PartialEq` but not `Eq`). `PartialEq` is all the wire-stability round-trips need on the response side.

### Request (client → daemon)

The variant set is the daemon's whole RPC surface - liveness, site management, PHP version management, **database/cache service management**, **SQL database administration**, **mail capture**, **dump telemetry**, **Cloudflare Tunnel sharing**, status/doctor, and daemon lifecycle. A representative sample with its exact wire shape (the full list of tags lives in `request.rs`):

| Variant | Wire JSON |
| --- | --- |
| `Ping` | `{"type":"ping"}` |
| `ListSites` | `{"type":"list_sites"}` |
| `Park { path }` | `{"type":"park","path":"/srv/foo"}` |
| `Link { name, path }` | `{"type":"link","name":"foo","path":"/srv/foo"}` |
| `SetPhp { name, version }` | `{"type":"set_php","name":"foo","version":"8.3"}` |
| `SetSecure { name, secure }` | `{"type":"set_secure","name":"foo","secure":true}` |
| `SetWebRoot { name, path: Option }` | `{"type":"set_web_root","name":"foo","path":"public"}` or `…,"path":null` (reset to auto-detect) |
| `AddDomain { name, domain }` | `{"type":"add_domain","name":"foo","domain":"api.foo.test"}` (exact host or single-label wildcard `*.foo.test`) |
| `RemoveDomain { name, domain }` | `{"type":"remove_domain","name":"foo","domain":"api.foo.test"}` (refused for a site's last exact domain) |
| `SetPrimaryDomain { name, domain }` | `{"type":"set_primary_domain","name":"foo","domain":"corp.foo.test"}` (exact host only, never a wildcard; auto-added if absent) |
| `ResetDomains { name }` | `{"type":"reset_domains","name":"foo"}` (back to apex only) |
| `InstallPhp { version, confirm_legacy }` | `{"type":"install_php","version":"8.5"}` (`confirm_legacy` defaults `false` and is skipped on the wire; `{"type":"install_php","version":"7.4","confirm_legacy":true}` to install a legacy minor) |
| `InstallPhpStreamed { version, confirm_legacy }` | `{"type":"install_php_streamed","version":"8.5"}` (same `confirm_legacy` convention; replies `JobStarted`; poll `JobStatus`) |
| `UpdatePhp { version: Option }` | `{"type":"update_php","version":"8.5"}` or `…,"version":null` |
| `SetPhpSettings { settings }` | `{"type":"set_php_settings","settings":{…}}` |
| `SetPhpVersionSettings { version, settings }` | `{"type":"set_php_version_settings","version":"8.3","settings":{…}}` (per-version overrides; `""` removes → falls back to global) |
| `SetPhpDirectives { version, directives }` | `{"type":"set_php_directives","version":"8.3","directives":{"xdebug.mode":"debug"}}` (free-form ini directives; `""` removes) |
| `AddPhpExtension { version, path, name: Option, zend }` | `{"type":"add_php_extension","version":"8.5","path":"/a/scrypt.so","name":null,"zend":false}` |
| `RemovePhpExtension { version, name }` | `{"type":"remove_php_extension","version":"8.5","name":"scrypt"}` |
| `ListPhpExtensions` | `{"type":"list_php_extensions"}` (replies `PhpExtensions { by_version }`) |
| `ListServices` / `AvailableServices` | `{"type":"list_services"}` / `{"type":"available_services"}` |
| `InstallService { service, version }` | `{"type":"install_service","service":"redis","version":"8"}` |
| `ChangeServiceVersion { service, version }` | `{"type":"change_service_version","service":"redis","version":"8.1"}` |
| `UninstallService { service, version, purge }` | `{"type":"uninstall_service","service":"redis","version":"8","purge":false}` |
| `StartService` / `StopService` / `RestartService` | `{"type":"start_service","service":"redis"}` (and `stop_`/`restart_`) |
| `SetServicePort { service, port }` | `{"type":"set_service_port","service":"redis","port":6380}` |
| `ServiceLogs { service, lines }` | `{"type":"service_logs","service":"redis","lines":100}` |
| `ListDatabases { service }` | `{"type":"list_databases","service":"mysql"}` |
| `CreateDatabase` / `DropDatabase` | `{"type":"create_database","service":"mysql","name":"app"}` (and `drop_database`) |
| `BackupDatabase { service, name, path }` | `{"type":"backup_database","service":"mysql","name":"app","path":"/tmp/app.sql"}` |
| `RestoreDatabase { service, name, path }` | `{"type":"restore_database","service":"mysql","name":"app","path":"/tmp/app.sql"}` |
| `Status` | `{"type":"status"}` |
| `Diagnose` / `DoctorFix` | `{"type":"diagnose"}` / `{"type":"doctor_fix"}` |
| `RestartDaemon` | `{"type":"restart_daemon"}` (Unix-only re-exec) |
| `ListMails` | `{"type":"list_mails"}` |
| `GetMail { id }` | `{"type":"get_mail","id":"000001"}` |
| `ClearMails` | `{"type":"clear_mails"}` |
| `DeleteMails { ids }` | `{"type":"delete_mails","ids":["000001"]}` |
| `MarkMailsRead { ids }` | `{"type":"mark_mails_read","ids":["000001"]}` |
| `SetMailPort { port }` | `{"type":"set_mail_port","port":2525}` |
| `SetMailEnabled { enabled }` | `{"type":"set_mail_enabled","enabled":true}` |
| `SetMcpEnabled { enabled }` | `{"type":"set_mcp_enabled","enabled":true}` |
| `ListDumps { since_id }` | `{"type":"list_dumps","since_id":0}` |
| `ClearDumps` | `{"type":"clear_dumps"}` |
| `DeleteDump { id }` | `{"type":"delete_dump","id":1}` |
| `SetDumpsEnabled { enabled }` | `{"type":"set_dumps_enabled","enabled":true}` |
| `SetDumpsPort { port }` | `{"type":"set_dumps_port","port":2304}` |
| `SetDumpFeature { feature, enabled }` | `{"type":"set_dump_feature","feature":"queries","enabled":true}` |
| `SetDumpsPersist { persist }` | `{"type":"set_dumps_persist","persist":true}` |
| `DumpsStatus` | `{"type":"dumps_status"}` |
| `ListTools` | `{"type":"list_tools"}` |
| `InstallTool { tool }` | `{"type":"install_tool","tool":"node"}` |
| `UninstallTool { tool }` | `{"type":"uninstall_tool","tool":"bun"}` |
| `CreateSite { spec }` | `{"type":"create_site","spec":{"name":"blog","parent_dir":"/srv","php":"8.3","secure":false,"framework":{"framework":"wordpress",…}}}` (replies `JobStarted`; poll `JobStatus`) |
| `AvailableWordpressVersions` | `{"type":"available_wordpress_versions"}` |
| `MintWordpressLoginToken { site }` | `{"type":"mint_wordpress_login_token","site":"blog"}` |
| `SetWordpressAutoLogin { name, enabled, user: Option }` | `{"type":"set_wordpress_auto_login","name":"blog","enabled":true,"user":"admin"}` |
| `WordpressAdminUsers { site }` | `{"type":"wordpress_admin_users","site":"blog"}` |

Database `name` has operation-specific validation. `CreateDatabase` uses Yerd's
portable creation allowlist. `DropDatabase`, `BackupDatabase`, and
`RestoreDatabase` address an existing engine database and preserve the supplied
name exactly; only an empty name or embedded NUL is rejected. Drop and restore
continue to protect engine system databases. `ListDatabases` returns exact decoded
names in `DatabaseSummary`, including surrounding whitespace and line breaks.

Note `Unpark { path: String }` deliberately uses a `String`, not `PathBuf`: clients echo a value straight back from `Response::Parked`, and an exact-identity match avoids lossy path normalisation (the daemon does not canonicalise it).

::: info Legacy PHP support: an additive `confirm_legacy` field
`InstallPhp` and `InstallPhpStreamed` both gained `confirm_legacy: bool`
(`#[serde(default, skip_serializing_if = "std::ops::Not::not")]`, last field):
`false` is the default and is skipped on the wire, so an install of a supported
version is byte-identical to before the field existed, and an old client's
payload (missing the field entirely) decodes with `confirm_legacy: false`. The
daemon requires `confirm_legacy: true` to install an out-of-support [legacy
version](../guide/php-versions#legacy-php-versions) (7.4 / 8.0 / 8.1) and
otherwise replies `Response::Error { code: ErrorCode::LegacyRestricted, .. }`.
:::

`CreateSite { spec: CreateSiteSpec }` is the wizard's entry point (both Laravel and WordPress): `CreateSiteSpec` carries the shared fields (`name`, `parent_dir`, `php`, `secure`) plus a `framework: Framework` enum internally tagged on `"framework"` (`"laravel"` with `LaravelOptions`, `"wordpress"` with `WordPressOptions` - core version, locale, admin credentials, database engine/name/table-prefix). It replies `JobStarted { job_id }` immediately; the caller polls `Request::JobStatus { job_id }` (streamed via `Response::JobProgress`) the same way `InstallPhpStreamed`/`InstallToolStreamed` do. See [`yerdd`'s WordPress support section](./binaries/yerdd#wordpress-support) for what runs behind the job.

### Response (daemon → client)

```rust
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Response {
    Pong,
    Ok,                                           // generic mutation success
    Sites { sites: Vec<Site> },
    Error { code: ErrorCode, message: String },
    Parked { paths: Vec<String> },
    Info { dns_addr, tld, ca_path, ca_fingerprint, http_port, https_port },
    PhpVersions { installed, default, updates, settings },
    AvailablePhp { available, installed, legacy },
    PhpExtensions { by_version },                  // version → [PhpExtInfo{name,path,zend,present}]
    Status { report: Box<StatusReport> },         // boxed: large payload
    Diagnoses { items: Vec<Diagnosis> },
    DoctorFix { report: FixReport },
    Services { services: Vec<ServiceStatus> },
    AvailableServices { services: Vec<ServiceAvailability> },
    ServiceLogs { lines: Vec<String> },
    Databases { databases: Vec<DatabaseSummary> },
    Mails { mails: Vec<MailSummary> },
    Mail { mail: Box<MailDetail> },               // boxed: large payload
    Tools { tools: Vec<ToolStatus> },             // installable dev tools
    WordpressVersions { versions: Vec<WordPressVersionInfo> },
    WordpressLoginToken { token: String },
    WordpressAdminUsers { users: Vec<WordPressAdminUser> },
    Dumps {
        events: Vec<DumpEvent>,
        removed_ids: Vec<u64>,
        counts: DumpCounts,
        latest_id: u64,
        min_live_id: u64,
    },
    DumpsStatus {
        enabled: bool,
        port: u16,
        running: bool,
        persist: bool,
        extensions: Vec<DumpExtStatus>,
        counts: DumpCounts,
        features: BTreeMap<String, bool>,
    },
    JobStarted { job_id: JobId },                 // CreateSite / InstallToolStreamed / InstallPhpStreamed
    JobProgress { state: JobState, /* phase label, … */ },  // streamed updates
}
```

`Response::Ok` is the generic success for mutating requests (`Park`, `Link`, `Unlink`, `SetPhp`, `SetSecure`, `SetWebRoot`, …). The large `StatusReport` is boxed so it does not bloat every `Response` value; `Box<T>` serializes transparently, so the wire bytes are unchanged.

::: info The `Site` payload gained a field additively
`Site` (inside `Response::Sites`) gained an optional `web_subpath` after `document_root`. It is **skipped when empty**, so a root-served site's JSON is byte-identical to before the field existed - the wire-stability goldens for the empty case are unchanged, and only the non-empty case (`"web_subpath":"public"`) added a new pin. Old clients ignore the field; no `PROTOCOL_VERSION` bump was needed.
:::

::: info WordPress fields on `Site` and `SiteEntry`
`Site` gained `wp_auto_login: bool` and `wp_auto_login_user: Option<String>`, both skipped on the wire when absent/`false` - same additive, no-bump pattern as `web_subpath`. `Response::Sites`'s per-entry payload (`SiteEntry`, `#[serde(flatten)]` over `Site`) separately gained `is_wordpress: bool`, also skipped when `false` - it's a runtime detection fact (see `wordpress_detect`, [`yerdd`'s WordPress support](./binaries/yerdd#wordpress-support)), not a persisted config field, so it lives on the response wrapper rather than the config-backed `Site` itself.
:::

::: info Domain fields on `SiteEntry`, and `StatusReport.shadows`
The multi-domain feature adds three more `SiteEntry` fields alongside `is_wordpress`: `primary_domain: Option<String>` (the canonical FQDN, populated only when it differs from the default `{name}.{tld}` apex), `domains: Vec<String>` (the full routable set, populated only for a customized site), and `apex_shadowed_by: Option<String>` (the other site claiming this apex, if any). All three are skipped when default/empty, so a default site's `Response::Sites` bytes are byte-identical to before - same additive, no-bump pattern as `web_subpath`. Separately, `StatusReport` gained `shadows: Vec<DomainShadow>` (skipped when empty): one `DomainShadow { site, shadowed_by }` per site that lost a domain to another when the router was built, which `yerd doctor` surfaces as a `DomainShadowed` warning. The four domain mutators (`AddDomain` / `RemoveDomain` / `SetPrimaryDomain` / `ResetDomains`) reply with the generic `Ok`.
:::

::: info The mail payloads gained read/unread fields additively
For read/unread tracking, `MailSummary` gained a `read: bool` (last field) and `MailStatus` gained an `unread: u32` (last field), both `#[serde(default)]`. A missing key decodes to `false`/`0`, so old daemons and old clients interoperate without a `PROTOCOL_VERSION` bump; the goldens grew a `,"read":false` / `,"unread":0` suffix. The matching mutator is the additive `Request::MarkMailsRead { ids }`.
:::

::: info `AvailablePhp` and `DumpExtStatus` gained a `legacy` field additively
`Response::AvailablePhp` gained `legacy: Vec<PhpVersion>` (last field,
`#[serde(default)]`, skipped when empty) - the installable [legacy](../guide/php-versions#legacy-php-versions)
minors from `php-legacy.json`, ascending. Separately, `dump.rs`'s `DumpExtStatus`
gained `legacy: bool` (same `#[serde(default, skip_serializing_if = "std::ops::Not::not")]`
convention, `false`/omitted for supported versions and older daemons) marking
whether a PHP version's extension-presence row is a legacy version, so the Dumps
view can flag it as unsupported without a second round-trip. Same additive,
no-`PROTOCOL_VERSION`-bump pattern as `web_subpath`.
:::

::: info Reverse proxies are additive requests plus their own response variant
The proxy feature adds four mutators - `AddProxy { name, url }`, `RemoveProxy { name }`, `AddProxyRule { site, prefix, url }`, `RemoveProxyRule { site, prefix }` (all reply with the generic `Ok`) - and one query, `ListProxies`. Because a whole-host proxy is **not** a `Site`, it can't ride `Response::Sites`/`SiteEntry`; `ListProxies` gets a dedicated `Response::Proxies { proxies: Vec<ProxyEntry>, rules: Vec<ProxyRuleEntry> }` instead, where `ProxyEntry { name, target, secure }` and `ProxyRuleEntry { site, prefix, target }` are all `String`/`bool` so the `Response` `Eq` derive holds. New variants are additive by serde tag, so existing pins are byte-identical and no `PROTOCOL_VERSION` bump is needed. `url` stays a `String` on the wire; the daemon parses and validates it (returning a typed error) rather than the client.
:::

### ErrorCode

Failures are a `Response::Error { code, message }` where `code` is machine-readable and `message` is for human display:

```rust
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ErrorCode {
    NotFound,             // "not_found"
    AlreadyExists,        // "already_exists"
    InvalidPath,          // "invalid_path"
    PortInUse,            // "port_in_use"
    ExtensionLoadFailed,  // "extension_load_failed" - a valid path whose .so failed its load-probe
    LegacyRestricted,     // "legacy_restricted" - a legacy version used somewhere it's disallowed
    Internal,             // "internal" - catch-all; expand the enum, don't overload this
}
```

`LegacyRestricted` is returned when a request tries to do something an [out-of-support legacy version](../guide/php-versions#legacy-php-versions)
(7.4 / 8.0 / 8.1) can't: setting it as the global default, or installing it
without `confirm_legacy: true`.

There is deliberately **no `#[serde(other)]` catch-all**. An unknown code from a newer daemon fails closed as `IpcError::Decode` rather than silently downgrading - the same signal as an unknown `type` tag, and the placeholder for a real version mismatch until a handshake lands.

### Status & doctor payloads

`status.rs` holds the nested payloads carried inside the status/doctor, service/database, and mail responses: `StatusReport`, `PortStatus`, `CaStatus`, `SiteCounts`, `PhpPoolStatus`, `PoolRunState`, `ServiceStatus`, `ServiceRunState`, `ServiceAvailability`, `DatabaseSummary`, `Diagnosis`, `Severity`, `DiagnosisCode`, `FixReport`, `FixResult`, and the mail-capture types `MailStatus`, `MailSummary`, `MailHeader`, and `MailDetail`. Same contract rules apply. `StatusReport` also carries an additive `services: Vec<ServiceStatus>` field alongside the PHP pools, plus an additive `mail: Option<MailStatus>`.

`StatusReport` is also how the MCP gate is read back: `mcp_enabled: bool` (additive, `#[serde(default)]`, always emitted) reports whether `SetMcpEnabled` has been turned on. The daemon runs no MCP server itself - it persists the flag and reports it here, and each `yerd mcp` session reads it to decide whether to serve tools. See [yerd-mcp](./crates/yerd-mcp).

`dump.rs` holds the dump-telemetry payloads carried inside the `Dumps` / `DumpsStatus` responses: `DumpCategory` (the per-tab category enum), `DumpEvent` (one buffered event; its `payload` is an opaque `serde_json::Value`), `DumpCounts` (per-category buffered counts), and `DumpExtStatus` (per-PHP-version extension presence). Same contract rules apply.

::: tip Integer-encoded scalars (the load average)
`Request` derives `Eq`, but `Response` does **not** - the `Dumps` response carries arbitrary JSON dump payloads (a `serde_json::Value`, which may hold floats), so an `Eq` derive is impossible there. That float escape hatch is confined to opaque dump payloads, though: the daemon never interprets them. The daemon's *own* status scalars are still integer-encoded so they stay exact and comparable. The system load average therefore crosses as integer hundredths - `StatusReport::load_avg` is `Option<[u32; 3]>`, each value `load × 100` - and the CLI renders it back to `x.xx`.
:::

## Errors

Two layers, by design:

* **`FrameError`** - pure framing error, `Clone + Eq`. Variants: `TooLarge { size, max }` and `PayloadOverflowsLengthPrefix { size }`.
* **`IpcError`** - top-level, wraps framing and serde errors. Variants: `Encode`, `Decode`, `Frame(FrameError)`, `UnexpectedEof { bytes }`, and `Io { kind: std::io::ErrorKind }`. It is **not** `Clone`/`Eq` because `serde_json::Error` is not.

For GUI/Tauri command returns that need `Clone + Eq`, call `IpcError::kind()` to get the shadow enum `IpcErrorKind`, which mirrors every variant (dropping the non-cloneable `serde_json::Error` detail) and carries `std::io::ErrorKind` (which is `Copy + Eq`). A `frame_error_to_kind_is_exhaustive` test enforces that every `FrameError` variant has a paired `IpcErrorKind`, with a `FrameOther { description }` catch-all guarding against drift.

EOF is split from framing: the pure codec never synthesises EOF. The transport `read_frame` returns `Ok(None)` on a clean EOF with an empty buffer, and `Err(IpcError::UnexpectedEof { bytes })` on EOF mid-frame. I/O failures map to `IpcError::Io { kind }`, preserving only the OS error category.

## Transport helpers

With `--features transport`, three async helpers in `transport.rs` glue the codec to a `tokio` stream:

```rust
pub async fn write_message<W, T>(writer: &mut W, value: &T, max: usize) -> Result<(), IpcError>;
pub async fn read_frame<R>(reader: &mut R, decoder: &mut FrameDecoder)
    -> Result<Option<Vec<u8>>, IpcError>;
pub async fn read_message<R, T>(reader: &mut R, decoder: &mut FrameDecoder)
    -> Result<Option<T>, IpcError>;
```

`read_frame` loops: try `decoder.next_frame()`, and on `None` read another chunk (a 4 KiB scratch buffer) into the decoder. It returns the raw payload so a caller can inspect the `type` tag before fully decoding. `read_message` is `read_frame` then `decode_message`. The daemon's per-client loop drives exactly these (`bin/yerdd/src/ipc_server.rs`):

```rust
let mut decoder = FrameDecoder::new();
loop {
    let req = match read_message::<_, Request>(&mut reader, &mut decoder).await {
        Ok(Some(r)) => r,
        Ok(None)    => return,            // clean EOF - client hung up
        Err(_)      => return,            // decode/EOF error - close quietly
    };
    let resp = dispatch(req, &state).await;
    write_message(&mut writer, &resp, DEFAULT_MAX_FRAME).await?;
}
```

A decode error (unknown `type`, unknown `ErrorCode`, malformed JSON) closes the connection quietly at debug level - that is the common signature of a mismatched-version client.

## Wire-stability tests

The JSON shapes are the **published contract**, pinned three ways so a rename or reshape cannot land silently:

1. **`tests/wire_stability.rs`** asserts byte-exact JSON for *every* `Request`, `Response`, `ErrorCode`, and status sub-type, e.g.

   ```rust
   assert_eq!(serde_json::to_string(&Request::SetPhp {
       name: "foo".into(), version: PhpVersion::new(8, 3),
   }).unwrap(), r#"{"type":"set_php","name":"foo","version":"8.3"}"#);
   ```

   It also pins additive back-compat: `Response::Info` decodes legacy daemons that omit `http_port`/`https_port` (they default to 0), and `Response::PhpVersions` skips an empty `updates`/`settings`/`version_settings`/`directives` on the wire so the bytes match the pre-field shape.

2. **Inline `variant_name_pinning` modules** in `request.rs` and `response.rs` contain exhaustive `match` arms over the (in-crate, so matchable despite `#[non_exhaustive]`) enums. A renamed Rust variant fails to compile there - integration tests can't catch this across the crate boundary.

3. **A CI grep gate** forbids per-field `#[serde(rename = "...")]` in `crates/yerd-ipc/src/`. Casing is owned entirely by `rename_all = "snake_case"`. Pairing the no-rename rule with the byte pins means a Rust rename trips *both* the wire pin (changed JSON) and the compile-time match - you cannot mask a rename with a `serde` attribute.

`tests/roundtrip.rs` additionally pins an `encode_message` ∘ `decode_message` identity plus the deliberate envelope/inner asymmetry: the outer `Request`/`Response` envelope **accepts** unknown JSON fields (so additive changes stay compatible), while an inner `Site` is **strict** (`deny_unknown_fields`). So `{"type":"ping","__extra":42}` decodes as `Request::Ping`, but an unknown field on a `Site` inside `Response::Sites` is rejected.

## Contract rules

The invariants that keep the protocol forward-compatible:

1. **Additive only.** Add variants and fields; never rename or remove a variant, field, or `ErrorCode`. `#[non_exhaustive]` keeps additions out of the breaking-change category.
2. **No per-field serde renames.** Let `rename_all` handle casing; the grep gate enforces it.
3. **Expand `ErrorCode`, don't overload `Internal`.** New typed failure categories get their own variant rather than collapsing into the catch-all.
4. **Fail closed.** Unknown `type` tags and unknown `ErrorCode`s surface as `IpcError::Decode`, not a silent `Unknown` downgrade.
5. **Versioning.** `PROTOCOL_VERSION` (currently `1`) is exposed but is effectively dead until a `Hello`/`Welcome` handshake lands; bump it only alongside that handshake.

   ```rust
   /// The current IPC protocol version. Bump on any breaking change;
   /// add a handshake before doing so.
   pub const PROTOCOL_VERSION: u32 = 1;
   ```

   Until then, a newer client talking to an older daemon is detected only when an unknown tag arrives mid-conversation - adding the handshake is the roadmap for proper version negotiation.

## See also

* [yerd-ipc crate reference](./crates/yerd-ipc)
* [The Daemon](../guide/daemon) and [yerdd internals](./binaries/yerdd)
* [yerd CLI internals](./binaries/yerd) · [Desktop App Internals](./gui)
* [Cross-Platform Model](./cross-platform) · [Architecture](./architecture)

---

---
url: 'https://yerd.app/developer/dev-tools.md'
---
# Dev-tool installer subsystem

The **Tooling** feature lets a user install Composer, Node (`node`/`npm`/`npx`),
Bun (`bun`/`bunx`), the Laravel installer, and WP-CLI as self-contained
binaries on their `PATH`, from the [desktop app](./gui) or the
[`yerd` CLI](./binaries/yerd). This page documents its implementation
end-to-end: the daemon subsystem that downloads/verifies/lays down the
binaries (or, for the Laravel installer and WP-CLI, builds them via Composer),
the `{data}/bin` shim reconciliation, the IPC contract, and the thin GUI/CLI
wiring.

It follows the same I/O-edge pattern as PHP installs and the
[cover-shim/pcov work](./binaries/yerdd#cover-shim-reconciliation-and-pcov):
all logic lives in the daemon and its libraries; the GUI is a
[thin IPC client](./binaries/yerd). Everything is **Unix-first** - the shim
symlinks and the `composer` multi-call exec are `#[cfg(unix)]`.

::: info Source
The subsystem is [`bin/yerdd/src/tools/`](https://github.com/forjedio/yerd/tree/main/bin/yerdd/src/tools)
(`mod.rs` + `composer.rs` / `node.rs` / `bun.rs`). The `composer` exec shim is
[`bin/yerd/src/composer_shim.rs`](https://github.com/forjedio/yerd/tree/main/bin/yerd/src/composer_shim.rs).
:::

## At a glance

```mermaid
flowchart TD
    GUI["Tooling view (Vue)"] -->|invoke| TC["Tauri command\nlist/install/uninstall_tool"]
    CLI["yerd tools / install tool"] -->|IPC| DISP
    TC -->|IPC| DISP["ipc_server::dispatch"]
    DISP --> INST["tools::install(tool, dirs, dl)"]
    INST --> DL["download + sha256 verify"]
    DL --> SWAP["stage_and_swap → {data}/tools/<id>/"]
    SWAP --> REC["reconcile_tool_shims_now\n(under shim_reconcile mutex)"]
    REC --> BIN["{data}/bin symlinks\ncomposer/node/npm/npx/bun/bunx"]
    BIN -.->|on PATH via `yerd path`| SHELL["user's shell"]
```

## The `Tool` registry (`tools/mod.rs`)

A small `Copy` enum drives everything; there is no per-tool trait - the variants
differ enough (phar vs multi-file tarball vs single-binary zip) that a `match`
into per-tool modules is clearer than an abstraction.

```rust
pub enum Tool { Composer, Node, Bun, Laravel, WpCli }

impl Tool {
    pub const ALL: [Tool; 5];
    pub const fn id(self) -> &'static str;            // "composer" | "node" | "bun" | "laravel" | "wp-cli"
    pub const fn display_name(self) -> &'static str;  // for the UI
    pub const fn primary_bin(self) -> &'static str;   // the command external detection looks for
    pub const fn exposed_bins(self) -> &'static [&'static str]; // commands on PATH
    pub const fn accepts_external(self) -> bool;      // may a PATH copy stand in?
    pub fn parse(id: &str) -> Option<Tool>;           // wire id → Tool
}
```

`exposed_bins` is the single source of truth for which `{data}/bin` names a tool
owns: `composer`; `node`/`npm`/`npx`; `bun`/`bunx`; `laravel`; `wp`. It drives
both shim creation and pruning.

`accepts_external` is the source of truth for whether a copy already on the
user's `PATH` can substitute for a managed install. It is `false` only for
`WpCli`, and that asymmetry is load-bearing: the Laravel flow resolves and execs
whatever `laravel`/`composer` it finds, whereas every WP-CLI caller (WordPress
scaffolding, the admin-user list, URL sync, the `wp` shim) execs the *managed*
`vendor/wp-cli/wp-cli/php/boot-fs.php` by path and can never use an external
`wp`. Reporting one as external is what caused
[#150](https://github.com/RichardAnderson/yerd/issues/150) - preflight passed,
then scaffolding failed spawning a `boot-fs.php` that was never installed. Keep
`ListTools` and any new preflight honest to this flag rather than re-deriving
the rule.

Failures are a binary-local `thiserror` enum (the tools subsystem has no library
crate of its own, so this mirrors `MutateError`/`DaemonError` rather than the
library `PhpError`/`ServiceError`):

```rust
pub enum ToolError {
    Download(String), Sha256Mismatch(String), Unpack(String),
    UnsupportedHost(&'static str), Io(String), Unknown(String),
}
```

`ipc_server::tool_error_code` maps it to a wire `ErrorCode` (mirrors
`php_error_code`): `Unknown → NotFound`, `UnsupportedHost → InvalidPath`, else
`Internal`.

## Status: pure filesystem reads

`status(dirs, tool)` and `list_status(dirs)` read a tool's `.version` marker
under `{data}/tools/<id>/` and return a `yerd_ipc::ToolStatus` (`id`,
`display_name`, `installed`, `version`, `binaries`). No marker → `installed:
false`. There is **no network or lock**, so `ListTools` is cheap and can never
block - unlike `ListServices`, which probes run-state.

## Install: download → verify → stage → swap

`install(tool, dirs, dl)` returns `Result<(), ToolError>` - a real Ok/Error so
the synchronous dispatch arm can report success or failure (it deliberately does
**not** reuse Composer's old error-swallowing `ensure_present` wrapper). The
shared helpers in `mod.rs`:

* **`sha_for_asset(sums_text, exact_filename)`** - Node and Bun publish a
  `SHASUMS256.txt` listing *many* assets (platforms, plus `-baseline`/`-musl`/
  `-profile` decoys). The parser tokenises each `"<hex>  <file>"` line
  (tolerating CRLF, a UTF-8 BOM on line 1, and a `*` binary-mode marker) and
  matches the filename **exactly** - never a `contains`/`ends_with`, which would
  pick a decoy.
* **`extract_root_dir(dir)`** - Node and Bun archives wrap their payload in one
  top-level, version-named directory (`node-v24.17.0-darwin-arm64/…`,
  `bun-darwin-aarch64/bun`). This resolves the *actual* single child dir (erroring
  unless exactly one), so the install never reconstructs the name from a version
  string that could drift upstream.
* **`stage_and_swap(dirs, tool, version, unpack)`** - mirrors
  `php_install::install`: unpack into a fresh `.staging-<id>-<pid>` dir, write the
  `.version` marker, remove any existing `{data}/tools/<id>`, then atomic
  `rename`. So a reinstall/update replaces in place and always leaves exactly one
  versioned child (keeping `extract_root_dir`'s invariant true across updates).
* **Trust boundary.** The tar/zip unpackers validate member *names* against
  traversal (`yerd_php::is_safe_member`) and preserve symlinks (Node needs its
  internal `bin/npm → ../lib/node_modules/npm/bin/npm-cli.js` links); the sha256
  verification before unpack is the integrity boundary.

The `reqwest`-backed `ReqwestDownloader` (from `php_install`) is reused; it sets
a `User-Agent` (the GitHub API used for Bun rejects requests without one).

### Per-tool specifics

| Module | Version source | Artifact | Integrity | Layout |
|---|---|---|---|---|
| `composer.rs` | `getcomposer.org/versions` → newest stable the installed PHP can run (honours each entry's `min-php` `PHP_VERSION_ID`) | `…/download/<ver>/composer.phar` | `composer.phar.sha256sum` (single line) | `{data}/tools/composer/composer.phar` |
| `node.rs` | `nodejs.org/dist/index.json` → first entry with a string `lts` (newest LTS) | `node-<ver>-<os>-<arch>.tar.gz` | per-release `SHASUMS256.txt` | unpacked tree under a versioned dir |
| `bun.rs` | GitHub `releases/latest` → `tag_name` (`bun-v…`) | `bun-<os>-<arch>.zip` (plain, non-baseline) | per-release `SHASUMS256.txt` | `bun-<os>-<arch>/bun` |

Each module has a pure host→asset mapper (`current_os_arch()` → `darwin-arm64` /
`linux-x64` / `bun-darwin-aarch64` / …) that returns a typed
`ToolError::UnsupportedHost` for a platform the publisher doesn't ship, rather
than building a URL that 404s. Bun's zip is unpacked with the `zip` crate
(`default-features = false, features = ["deflate"]`, pulling only the pure-Rust
flate2 backend - pinned to 2.x to stay within the workspace's MSRV-1.77
discipline; see the `Cargo.toml` MSRV-pin block).

### Composer-built tools: the Laravel installer and WP-CLI

`laravel.rs` and `wp_cli.rs` don't fit the download-a-release-asset shape above

* neither project publishes a standalone binary with a checksum sidecar worth
  pinning to. Both instead run the managed **Composer** (`composer.rs`'s phar,
  so Composer itself must already be installed) as a `create-project`:

| Module | Composer package | Entry point | Layout |
|---|---|---|---|
| `laravel.rs` | `laravel/installer` | `vendor/laravel/installer/bin/laravel` | `{data}/tools/laravel/` (the create-project root) |
| `wp_cli.rs` | `wp-cli/wp-cli-bundle` (a root project depending on `wp-cli/wp-cli`, not that package itself) | `vendor/wp-cli/wp-cli/php/boot-fs.php` | `{data}/tools/wp-cli/` |

`install(dirs, progress)` runs `php <composer.phar> create-project --prefer-dist --no-interaction --no-dev <package> <staging-dir>`, streaming output through the same `drain`/`stage_and_swap` helpers the download-based tools use - so a `create-project` failure never leaves a partial install in place. The installed version is read back out of the built `composer.lock` (`wp-cli/wp-cli`'s resolved version for WP-CLI, since `wp-cli-bundle`'s own `composer.lock` has no self-entry for the *root* package the way a dependency does for Laravel's installer). **Integrity is Composer's own** (its `composer.lock` hash pinning and Packagist's TLS), not a yerd-side checksum - consistent with the "Composer needs PHP" trust boundary already described in the [Tooling guide](../guide/tooling#composer-needs-php).

Both shims exec their entry point under `boot_name`'s bare file name with `cwd` set to that file's own directory (not the invocation's cwd) - see [`yerd`'s `wp` shim](./binaries/yerd#cover-shims-yerd-as-a-multi-call-binary-cover_shim-rs) for why (a macOS space-in-path bug in some subcommands' self-re-invocation).

::: tip WP-CLI deprecation suppression
WP-CLI's bundled dependencies emit PHP deprecation notices on newer PHP that would otherwise flood streamed job logs. See [`yerdd`'s WordPress support section](./binaries/yerdd#wordpress-support) for `QUIET_DEPRECATIONS` and the `PHP_INI_SCAN_DIR`-based fix for subprocesses WP-CLI spawns internally via `launch_self()`.
:::

## Shims: `reconcile_tool_shims`

The commands a tool provides are symlinks in `{data}/bin` - the same directory as
the PHP `php`/`php<ver>`/`phpcover` shims. The two reconcilers partition the
namespace cleanly: the PHP reconcile only prunes `php<X.Y>*` names, and
`reconcile_tool_shims` owns `composer`/`node`/`npm`/`npx`/`bun`/`bunx`.

For each installed tool it creates `(name → target)` links via the shared
`php_install::place_symlink` (atomic temp+rename); for each **uninstalled** tool
it prunes that tool's owned names. Pruning keys on **name-ownership** gated on
`symlink_metadata().is_symlink()` - never `target.exists()` - so a link left
dangling by an uninstall is still removed. Per-tool targets:

| Tool | Link → target |
|---|---|
| Composer | `composer` → the `yerd` binary (a multi-call shim, like `phpcover`) |
| Node | `node`/`npm`/`npx` → **absolute** `node_root/bin/{…}` |
| Bun | `bun` → `bun_root/bun`; `bunx` → `{data}/bin/bun` (sibling; Bun dispatches on argv0) |

::: tip Why npm points at an absolute path
Node's `bin/npm` and `bin/npx` are themselves *relative* symlinks into
`../lib/node_modules/npm`. Pointing `{data}/bin/npm` at the **absolute**
`node_root/bin/npm` lets the kernel resolve that inner relative link correctly
(each link resolves relative to its own directory). The npm-cli shebang
`#!/usr/bin/env node` then finds `{data}/bin/node` via `PATH`. Pointing
`{data}/bin/npm` straight at `npm-cli.js` would lose npm's own arg handling.
:::

### Concurrency

`{data}/bin` is written by both the PHP reconcile and the tool reconcile, and the
daemon serves IPC requests `tokio::spawn`-per-connection - so two clients could
mutate the directory at once. `reconcile_tool_shims_now` takes the **same**
`state.shim_reconcile` mutex as the PHP reconcile, serialising all `{data}/bin`
mutation. The slow download runs *before* the lock is taken; only the reconcile
holds it.

## The `composer` exec shim (`bin/yerd/src/composer_shim.rs`)

Composer is a phar, so its `composer` command can't be a direct symlink - it
needs a PHP interpreter. Like the [cover shims](./binaries/yerd#cover-shims-yerd-as-a-multi-call-binary-cover_shim-rs),
`{data}/bin/composer` symlinks to the `yerd` binary, which detects `argv[0] ==
"composer"` *before clap* (in `main.rs`, ahead of `cover_shim::dispatch`) and
`exec`s the default managed PHP against `{data}/tools/composer/composer.phar`. If
no PHP is installed it prints a clear "install a PHP version" message; if the
phar is absent it points the user at the Tooling page.

## IPC contract

Three additive variants (no `PROTOCOL_VERSION` bump - see
[IPC Protocol](./ipc-protocol)):

| Request | Response |
|---|---|
| `ListTools` | `Tools { tools: Vec<ToolStatus> }` |
| `InstallTool { tool: String }` | `Ok` / `Error` |
| `UninstallTool { tool: String }` | `Ok` / `Error` |

`ToolStatus` lives in `crates/yerd-ipc/src/status.rs` (alongside `ServiceStatus`/
`DatabaseSummary`); its field declaration order is the wire contract and is pinned
by `tests/wire_stability.rs`. The install/uninstall arms run the slow work with no
lock held, then call `reconcile_tool_shims_now`; the daemon also reconciles tool
shims once at startup (self-healing the `composer` link if the `yerd` binary
moved between runs).

## GUI & CLI wiring

* **Tauri** (`apps/yerd-gui/src-tauri/src/commands.rs`): `list_tools`,
  `install_tool(tool)`, `uninstall_tool(tool)` - each `finish(exchange(&Request::…))`,
  registered in `main.rs`'s `generate_handler!`. No capabilities edit (our
  `#[tauri::command]`s are permitted by registration).
* **Frontend**: `ipc/types.ts` (`ToolStatus` + the `tools` response), `ipc/client.ts`
  (`listTools`/`installTool`/`uninstallTool`), `views/ToolingView.vue` (a table
  copied from the PHP view's pattern - install/update/uninstall with a busy
  spinner and toasts), plus the `SideNav.vue` + `router.ts` entries that place
  **Tooling** between Sites and Services.
* **CLI**: `yerd tools`, `yerd install tool <id>`, `yerd uninstall tool <id>` -
  a `Tool` variant on the `InstallTarget`/`UninstallTarget` enums and a `Tools`
  command, mapped in `map::to_request` (exhaustive, compile-checked) with an
  explicit `Response::Tools` arm in `map::render` (which has a wildcard, so a
  missing arm would silently misrender).

## Composer is opt-in

Composer was briefly auto-installed on daemon start; that was reverted when the
Tooling page landed. The startup/12h auto-fetch and the unconditional `composer`
shim were removed; Composer now installs only via `InstallTool` (or `yerd install
tool composer`), and its phar moved from `{data}/composer/` to
`{data}/tools/composer/`. A fresh daemon start performs no Composer network I/O.

## Tests

* **Pure helpers** (inline): the `sha_for_asset` exact-match against a multi-asset
  fixture with `-baseline`/`-musl`/`-profile` decoys and a CRLF line;
  `extract_root_dir`'s single-child invariant; Node's LTS pick from an
  `index.json` fixture; the host→asset mappers; Composer's `min-php` selection;
  Bun's zip unpack preserving the executable bit.
* **Subsystem**: `status` reflects the marker; `stage_and_swap` places then
  replaces in place; `reconcile_tool_shims` creates an installed tool's links,
  prunes an uninstalled tool's, and leaves PHP shims untouched.
* **Wire stability**: byte-shape goldens for `ListTools`/`InstallTool`/
  `UninstallTool` and `Tools` in `crates/yerd-ipc/tests/wire_stability.rs`.

## See also

* [Tooling guide](../guide/tooling) - the user-facing view.
* [yerdd (daemon)](./binaries/yerdd) - the host process and its
  [cover-shim/pcov](./binaries/yerdd#cover-shim-reconciliation-and-pcov) sibling.
* [yerd (CLI)](./binaries/yerd) - the multi-call binary that backs `composer`.
* [IPC Protocol](./ipc-protocol) - the additive wire contract.

---

---
url: 'https://yerd.app/developer/cross-platform.md'
---
# Cross-Platform Model

Yerd supports macOS and Linux from a single workspace, with Windows compiling (but not yet functioning) against a stub. Almost all of the OS-specific surface area is concentrated in one crate, [`yerd-platform`](./crates/yerd-platform). This page walks the actual module map, the compile-time OS selection, the purity discipline that keeps decisions testable, the privilege boundary that keeps the library unprivileged, and the per-OS behaviour matrices for the four privileged subsystems.

::: info Where this lives in the architecture
`yerd-platform` is unprivileged library code. The daemon ([`yerdd`](./binaries/yerdd)) calls it; the privileged work is delegated to [`yerd-helper`](./binaries/yerd-helper). For the bigger picture see [Architecture](./architecture); for the runtime story see [Elevation & Privileges](../guide/elevation).
:::

## Design goals

The crate doc (`crates/yerd-platform/src/lib.rs`) states the contract directly:

```rust
//! The core traits live here - Paths, TrustStore, ResolverInstaller,
//! PortBinder, and PortRedirector - each with a single thin
//! implementation per OS selected by #[cfg(target_os = ...)].
//! macOS and Linux ship in Phase 1; Windows compiles against the
//! os::unsupported stub that returns PlatformError::Unsupported for
//! every method.
```

Three rules follow from this and recur throughout the crate:

1. **Exactly one OS implementation is active per build**, chosen at compile time by `#[cfg(target_os = ...)]`. There is no runtime OS dispatch.
2. **Decisions live in `pure/`, side effects live in the OS impls.** Anything that can be expressed as "given this text/these outcomes, what should happen?" is a pure, runtime-free, I/O-free function with table-style unit tests. The OS impl only does the file reads, binds, and command spawns.
3. **The platform crate never elevates itself.** Operations needing root return `PlatformError::NeedsHelper` carrying a typed operation tag; the daemon owns the spawn of `yerd-helper`.

The crate is also `#![forbid(unsafe_code)]`, and a dep-graph test (`tests/no_runtime_deps.rs`) asserts that `tokio`, `anyhow`, `reqwest`, and any OpenSSL/native-tls variant never enter its runtime graph.

## The trait surface

Every OS difference is funnelled through six small traits, each defined in its own module and re-exported from `lib.rs`:

| Trait | Module | Responsibility |
| --- | --- | --- |
| `Paths` | `paths.rs` | Resolve config / data / state / cache / runtime directories into `PlatformDirs`. |
| `TrustStore` | `trust_store.rs` | Install / uninstall / probe a root CA in the **system** store, plus a per-user Firefox/NSS install. |
| `ResolverInstaller` | `resolver.rs` | Install / uninstall / probe the per-TLD OS resolver redirect. |
| `PortBinder` | `port_binder.rs` | Bind a single TCP listener, plus an atomic 80+443 (or rootless 8080+8443) pair. |
| `PortRedirector` | `port_redirect.rs` | Probe whether the privileged-port redirect is live (macOS pf), and whether a non-Yerd process is squatting 80/443 (cross-platform). |
| `SystemMetrics` | `metrics.rs` | Best-effort per-process RSS and system load average. |

`SystemMetrics` is the odd one out: it returns `Option` rather than `Result`, because metrics are best-effort and an unsupported OS is indistinguishable (to callers) from a transient read failure - both collapse to "show nothing".

## Compile-time OS selection

`src/os/mod.rs` is the switchboard. Exactly one submodule is compiled, and a single `active` module re-exports its concrete types under OS-neutral aliases:

```rust
#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "macos")]
mod macos;
#[cfg(not(any(target_os = "linux", target_os = "macos")))]
mod unsupported;

pub(crate) mod active {
    #[cfg(target_os = "linux")]
    pub use super::linux::{
        LinuxPaths as ActivePaths, LinuxPortBinder as ActivePortBinder,
        LinuxPortRedirector as ActivePortRedirector,
        LinuxResolverInstaller as ActiveResolverInstaller,
        LinuxSystemMetrics as ActiveSystemMetrics, LinuxTrustStore as ActiveTrustStore,
    };
    // macos and unsupported blocks mirror this, gated by their own cfg.
}
```

`lib.rs` then re-exports the active set as the crate's public entry point:

```rust
pub use os::active::{
    ActivePaths, ActivePortBinder, ActivePortRedirector, ActiveResolverInstaller,
    ActiveSystemMetrics, ActiveTrustStore,
};
```

Callers depend on `ActivePaths`, `ActiveTrustStore`, and so on - never on `LinuxPaths` or `MacosPaths` directly. This is what makes the rest of the workspace OS-agnostic: the daemon writes `ActiveTrustStore::new()` once and the compiler resolves it to the right concrete type for the target.

```mermaid
flowchart TD
    Lib["lib.rs re-exports ActivePaths, ActiveTrustStore, ..."]
    Mod["os/mod.rs active module"]
    Linux["cfg(linux)<br/>os/linux.rs (LinuxPaths...)"]
    Macos["cfg(macos)<br/>os/macos.rs (MacosPaths...)"]
    Unsupported["cfg(not(linux or macos))<br/>os/unsupported.rs (UnsupportedPaths...)"]
    Pure["call into pure/"]
    Unsup["every method returns Unsupported"]

    Lib --> Mod
    Mod --> Linux
    Mod --> Macos
    Mod --> Unsupported
    Linux --> Pure
    Macos --> Pure
    Unsupported --> Unsup
```

### The `unsupported` stub (Windows today)

`os/unsupported.rs` provides a complete set of trait impls whose every fallible method returns `Err(PlatformError::Unsupported { operation })`. Its doc comment states the purpose plainly:

```rust
//! Stub implementations for unsupported OSes (Phase 1: Windows).
//!
//! Every trait method returns Err(PlatformError::Unsupported { operation }).
//! This lets `cargo check --workspace` stay green on every host while the
//! macOS + Linux impls are the only ones with behaviour.
```

`SystemMetrics` is the one exception - its stub returns `None` rather than an error, matching the best-effort contract. `tests/unsupported.rs` (gated to non-Linux, non-macOS targets) asserts every other method returns the `Unsupported` variant, so the stub cannot silently rot.

::: warning Windows compiles, but does not run
Building for Windows produces a working `cargo check`, but every privileged or path operation returns `Unsupported`. Real Windows support, plus `Autostart` and `Elevation` traits, is explicitly deferred to a later phase.
:::

## Purity: decisions in `pure/`, effects in the OS impls

`src/pure/mod.rs` sets the discipline:

```rust
//! Pure, in-memory decision helpers used by the OS impls.
//!
//! Every function in this module is sync, runtime-free, and free of I/O,
//! clock reads, and environment lookups. Each submodule is unit-tested
//! table-style.
```

The OS impls read a file or attempt a bind, then hand the bytes/outcome to a pure helper that decides what it means. The decision is therefore testable without a filesystem, a network stack, or root:

| Pure module | Decision it owns | Consumed by |
| --- | --- | --- |
| `port_plan` | Should a failed port-pair bind fall back to rootless ports, hard-fail, or be kept? | both `bind_pair` impls |
| `resolver_file` | Compose/parse/match macOS `/etc/resolver/<tld>`; pick latest backup; `restorable` guard for restoring one. | macOS `ResolverInstaller` |
| `resolved_drop_in` | Compose/parse/match a `systemd-resolved` drop-in. | Linux `ResolverInstaller` |
| `resolv_conf` | Select systemd-resolved, positively marked NetworkManager, or unsupported; validate the NetworkManager reload post-condition. | Linux `ResolverInstaller` |
| `networkmanager_dnsmasq` | Compose and match NetworkManager dnsmasq plugin and per-TLD rules. | Linux `ResolverInstaller` |
| `dns_probe` | Compose the loopback A probe and validate a `127.0.0.1` answer. | Linux resolver post-condition (helper) |
| `pem_match` | Match a SHA-256 fingerprint against a list of PEM blobs. | Linux `TrustStore` |
| `pf_anchor` | Compose the macOS pf `rdr` ruleset, anchor refs, and LaunchDaemon plist. | macOS pf redirect (helper) |
| `firefox` | Parse `profiles.ini` to discover NSS databases. | NSS install (planned) |
| `proc_metrics` | Parse `/proc/<pid>/status` `VmRSS` and `/proc/loadavg`. | Linux `SystemMetrics` |
| `ps_metrics` | Parse headerless `ps -o rss=` output. | macOS `SystemMetrics` |

A concrete example: `port_plan::classify_desired` takes two `Result<(), io::ErrorKind>` bind outcomes and returns an action - `KeepDesired`, `UseFallback`, or `HardFail(kind)`. The retry trigger is exactly three error kinds:

```rust
pub fn is_retry_kind(kind: ErrorKind) -> bool {
    matches!(
        kind,
        ErrorKind::PermissionDenied | ErrorKind::AddrInUse | ErrorKind::AddrNotAvailable
    )
}
```

Both `os/linux.rs` and `os/macos.rs` carry their own copy of `bind_pair_impl` (they cannot share one - the Linux copy is `cfg`-gated to Linux), but both delegate the actual precedence decision to this single pure function, which is exhaustively table-tested for the http/https × retry/hard-fail matrix.

## The privilege boundary

This is the load-bearing safety property of the whole crate. From `lib.rs`:

```rust
//! `yerd-platform` is unprivileged library code. Operations that need root
//! return PlatformError::NeedsHelper. The typed HelperInvocation enum
//! carries the request to the `yerd-helper` binary (a separate crate) for
//! execution. The OS impls never spawn the helper themselves - a
//! privileged caller owns the Command::new(...) call.
```

So the flow for any root-requiring operation is:

1. The daemon calls e.g. `ActiveTrustStore::install_system(pem, &fp)`.
2. The impl immediately returns `Err(PlatformError::NeedsHelper { operation: ops::INSTALL_CA })`. It does **no** privileged work and spawns **nothing**.
3. The daemon recognises `NeedsHelper`, builds the matching typed `HelperInvocation`, and is the one that runs `yerd-helper` (directly for its own setup, or via `yerd elevate` under `sudo`/`osascript`).

`PlatformError::NeedsHelper` carries only a `&'static str` operation tag, sourced from the single-source-of-truth `error::ops` module (`INSTALL_CA`, `UNINSTALL_RESOLVER`, `SETCAP`, `INSTALL_PORT_REDIRECT`, …). The same constants are the leading argv element of the helper invocation, so the tag round-trips end to end.

### `HelperInvocation`: the typed wire contract

`src/helper.rs` defines the enum the daemon hands to its spawner. Values stay typed all the way to the spawn site - there is no `Vec<String>` round-trip in between:

```rust
#[non_exhaustive]
pub enum HelperInvocation {
    InstallCa { ca_pem_path: PathBuf, fp: CaFingerprint },
    UninstallCa { fp: CaFingerprint },
    InstallResolver { tld: String, addr: SocketAddr },
    UninstallResolver { tld: String },
    Setcap { daemon_binary: PathBuf },
    InstallPortRedirect { http_from: u16, http_to: u16, https_from: u16, https_to: u16 },
    UninstallPortRedirect,
}
```

`to_argv` serialises this to a `Vec<OsString>` (operation tag, then alternating `--flag value` pairs); `from_argv` is the strict inverse used inside the helper - unknown flags, missing values, and trailing argv are all rejected with a typed `ArgvParseError`. Fingerprints render as exactly 64 lowercase hex characters; socket addresses use their `Display` form; paths pass as native `OsString`. The argv shape is pinned by `tests/helper_argv_shape.rs` and round-tripped by the unit tests in `helper.rs`, so adding or reordering a flag trips a test.

::: tip Why typed all the way down
Keeping the invocation a typed enum (rather than assembling strings in the daemon) means the privileged boundary is crossed with a value the compiler has checked - the only stringly-typed moment is the single `to_argv`/`from_argv` hop, and that hop is guarded by round-trip tests. See [IPC Protocol](./ipc-protocol) and [yerd-helper](./binaries/yerd-helper) for the execution side.
:::

The probes (`is_present_system`, `is_installed`, `bind`, `is_active`, the metrics reads) are all read-only and run **unprivileged** in the daemon - they never return `NeedsHelper`.

## Per-OS behaviour matrices

The same five-field `PlatformDirs` is produced by both OSes, but with different sources: Linux uses XDG via the `directories` crate (with `state` distinct from `data` and a `/tmp/yerd-$UID` runtime fallback when `XDG_RUNTIME_DIR` is unset); macOS collapses `state` onto `data` and uses a deterministic `/tmp/yerd-$UID` runtime dir so a `sudo`-elevated process can reconstruct the IPC socket path from `SUDO_UID` alone. The four privileged subsystems differ as follows.

### Resolver install

| Aspect | Linux | macOS | Windows (stub) |
| --- | --- | --- | --- |
| Backend | `systemd-resolved` drop-in (preferred), else NetworkManager dnsmasq plugin | `/etc/resolver/<tld>` | - |
| File path | resolved drop-in, or `/etc/NetworkManager/{conf.d,dnsmasq.d}/yerd-*.conf` | `/etc/resolver/<tld>` | - |
| File body | `[Resolve]` route, or `[main] dns=dnsmasq` plus `server=/<tld>/<ip>#<port>` | `nameserver <ip>` `port <n>` (`resolver_file::compose`) | - |
| `install` / `uninstall` | `NeedsHelper` (`install-resolver` / `uninstall-resolver`) | `NeedsHelper` (same tags) | `Unsupported` |
| `is_installed` probe | resolved drop-in is shape/TLD-only; NetworkManager requires matching plugin, TLD, address, and port snippets | parse file; **requires** matching nameserver **and** port | `Unsupported` |
| Empty TLD | `Err(Resolver { TldEmpty })` | `Err(Resolver { TldEmpty })` | `Unsupported` |

The macOS probe is deliberately strict about the port: a bare `nameserver 127.0.0.1` left by Valet/Herd defaults to port 53 (where nothing listens), so it must read as *not installed* and get rewritten with the daemon's real DNS port. The helper backs up any replaced `/etc/resolver/<tld>` under `/Library/Application Support/io.yerd.Yerd/resolver-backups` (path logic in `resolver_file`, I/O in the helper). `uninstall-resolver` (i.e. `unelevate resolver`) is the inverse: it restores the newest backup over `/etc/resolver/<tld>` then clears the rest - but only after confirming the backup is root-owned, not a symlink, and `resolver_file::restorable` (parses as a real resolver file); otherwise it falls back to a plain removal.

### Port binding

| Aspect | Linux | macOS | Windows (stub) |
| --- | --- | --- | --- |
| Privileged 80/443 | bind **directly** after `setcap cap_net_bind_service` | cannot bind 80/443 unprivileged → pf redirect | `Unsupported` |
| `bind` / `bind_pair` | `127.0.0.1` loopback via `TcpListener` | `127.0.0.1` loopback via `TcpListener` | `Unsupported` |
| Fallback decision | `pure::port_plan` (shared) | `pure::port_plan` (shared) | - |
| Retry triggers | `PermissionDenied`, `AddrInUse`, `AddrNotAvailable` | same | - |

`bind_pair(desired, fallback)` attempts the desired pair (e.g. 80/443), and on a retry-kind failure drops any partial listener and retries the fallback pair (e.g. 8080/8443). A non-retry error on the desired pair surfaces immediately as `PlatformError::Bind` without trying the fallback. If both pairs fail, `PlatformError::BindPair::BothPairsFailed` carries all four `io::ErrorKind`s, so the daemon can tell "`setcap` missing" (`PermissionDenied` across the board) from "port already in use" (`AddrInUse`) and message accordingly.

### Trust store

| Aspect | Linux | macOS | Windows (stub) |
| --- | --- | --- | --- |
| System store | anchor dir + distro `update-ca-certificates`/`update-ca-trust` (via helper) | `/Library/Keychains/System.keychain` | - |
| Anchor dirs scanned | `/usr/local/share/ca-certificates`, `/etc/pki/ca-trust/source/anchors`, `/etc/ca-certificates/trust-source/anchors` | n/a | - |
| `install` / `uninstall` | `NeedsHelper` (`install-ca` / `uninstall-ca`) | `NeedsHelper` (same tags) | `Unsupported` |
| `is_present_system` probe | hash each anchor `.crt` DER, match fingerprint (`pem_match`) | enumerate Keychain certs via `security-framework`, SHA-256 the DER | `Unsupported` |
| Firefox/NSS install | degraded `NssOutcome` (`certutil_missing: false`) - wiring planned | degraded `NssOutcome` (`certutil_missing: true`) - wiring planned | `Unsupported` |

The fingerprint is a `CaFingerprint` newtype wrapping a 32-byte SHA-256 digest, with a strict lowercase-hex wire form (`to_hex` / `from_hex`). The presence probe is a *presence* check, not a trust-policy check.

::: info Firefox/NSS is partially landed
Both OS impls currently return a degraded `NssOutcome` reporting zero profiles attempted; the actual `certutil` invocation is a planned follow-up that lands when the daemon and helper drive it end to end. The `pure::firefox` `profiles.ini` parser already exists.
:::

### Autostart

Yerd does not yet expose a general cross-platform autostart abstraction - an `Autostart` trait is explicitly deferred to a later phase. The only boot persistence in the codebase today is for the macOS pf redirect:

| Aspect | Linux | macOS | Windows (stub) |
| --- | --- | --- | --- |
| Generic daemon autostart trait | not implemented (roadmap) | not implemented (roadmap) | not implemented |
| pf-redirect boot persistence | n/a (binds 80/443 directly via `setcap`) | `LaunchDaemon` plist `dev.yerd.pf` at `/Library/LaunchDaemons/dev.yerd.pf.plist` | n/a |
| Re-applied at boot by | n/a | `/sbin/pfctl -E -f /etc/pf.conf`, one-shot `RunAtLoad`, no `KeepAlive` | n/a |
| Installed by | n/a | `yerd-helper` via `launchctl bootstrap system` | n/a |

The plist is composed by `pure::pf_anchor::compose_launchdaemon_plist` and installed by the helper's `install-port-redirect` operation. It is one-shot (`RunAtLoad` without `KeepAlive`) so launchd does not respawn a process that exits 0 in a tight loop. Because Linux binds the privileged ports directly after `setcap`, it needs no equivalent.

## Probing vs. doing: the `PortRedirector` nuance

On macOS the daemon still *binds* its high rootless ports even after the pf redirect makes 80/443 reachable, so the status field `http.fell_back` stays `true`. The doctor needs a separate signal that 80/443 are genuinely reachable, which is what `PortRedirector::is_active` provides. It is an **active, unprivileged** probe that confirms the redirect reaches *Yerd's own proxy* (not merely that something answers):

```rust
impl PortRedirector for MacosPortRedirector {
    fn is_active(&self) -> Option<bool> {
        // :80 must answer with the proxy's `Server: yerd` marker; :443 reachable.
        Some(loopback_redirect_reaches_proxy(80) && loopback_port_reachable(443))
    }
}
```

`loopback_redirect_reaches_proxy` speaks HTTP to loopback and checks for `yerd_core::PROXY_SERVER_ID` on the reply, rather than checking whether the pf anchor file exists (a file-existence check is a false-green - the file can exist while the rule isn't redirecting) or merely that a socket accepts (a foreign web server or stale `pf` rule would read as a live Yerd redirect). Linux returns `None` for `is_active` ("not applicable") because it binds the privileged ports directly.

The trait also has a **cross-platform** default method, `foreign_web_listener() -> Option<bool>`: `Some(true)` when a privileged web port answers but the proxy marker is absent - a non-Yerd process squatting 80/443. The daemon reports it as `StatusReport.foreign_web_listener` and `yerd-doctor` turns it into the `ForeignWebListener` warning (which supersedes `PortFallback`). The `unsupported` stub overrides it back to `None`.

## Invariants worth knowing

These are enforced by tests in `crates/yerd-platform/tests/`:

* **Exactly one OS impl is active.** `linux_smoke.rs`, `macos_smoke.rs`, and `unsupported.rs` are each `#![cfg(...)]`-gated to their target so only the active one runs.
* **The stub never silently gains behaviour.** `unsupported.rs` asserts every trait method returns `PlatformError::Unsupported`.
* **The helper argv shape is pinned.** `helper_argv_shape.rs` and the `helper.rs` round-trip tests fail if a flag is added or reordered.
* **No heavy runtime deps.** `no_runtime_deps.rs` walks the `--filter-platform`-scoped dep graph and fails if `tokio`, `anyhow`, `reqwest`, or OpenSSL/native-tls is reachable from `yerd-platform`.
* **Pure helpers are table-tested in memory** - every `pure/` submodule ships its own `#[cfg(test)] mod tests`.

## Where to go next

* [yerd-platform crate reference](./crates/yerd-platform) - the full module-by-module API.
* [yerd-helper (privileged)](./binaries/yerd-helper) - the execution side of `HelperInvocation`.
* [Elevation & Privileges](../guide/elevation) - the user-facing privilege story.
* [Architecture](./architecture) - how the crates fit together.

For source, see the public repository: <https://github.com/forjedio/yerd>.

---

---
url: 'https://yerd.app/developer/config-schema-history.md'
---
# Config schema history

`yerd.toml`'s on-disk schema is versioned independently of everything else - the IPC wire protocol, the app version, the daemon binary. This page is the version-by-version changelog: what each schema version added, whether the daemon can migrate a file forward automatically, and - the reason this page exists - **exactly what to change by hand if you need to downgrade** a config file so an older Yerd build will accept it again.

For how the versioning *mechanism* works (the `STEPS` array, `deny_unknown_fields`, the purity boundary), see [yerd-config](./crates/yerd-config#schema-versioning-and-migration). For the field-by-field "how do I configure X" reference, see the [Configuration Reference](../reference/configuration).

## Where the file lives

`yerd.toml` sits in the OS-standard config directory for the `io.yerd.Yerd` app, resolved once at startup by [`yerd-platform`](./crates/yerd-platform)'s `PlatformDirs`:

| OS | Default config directory | Full default path |
| --- | --- | --- |
| macOS | `~/Library/Application Support/io.yerd.Yerd` | `~/Library/Application Support/io.yerd.Yerd/yerd.toml` |
| Linux | `$XDG_CONFIG_HOME/yerd` (falls back to `~/.config/yerd` when unset) | `~/.config/yerd/yerd.toml` |
| Windows | Not yet supported (`os::unsupported` stub) | n/a |

::: info Overriding the path
`yerdd serve -c <path>` (`--config <path>`) points the daemon at a different file entirely - useful for testing a downgraded copy without touching your real config. A missing file is not an error: the daemon boots with `Config::default()` (a fresh, empty config) and logs that it's using defaults for a first-run boot. Anything else - invalid TOML, a version the daemon doesn't understand, a value that fails validation - is fatal; the daemon refuses to start rather than silently discarding your settings.
:::

macOS's `config`, `data`, and `state` directories all coincide at the same `io.yerd.Yerd` bundle (no XDG-style state/data/config split); Linux keeps them genuinely separate per the XDG base-directory spec, so `yerd.toml` (config) is not near the CA certificate or PHP installs (data) or the daemon's runtime state.

## How to read this page

Every on-disk file **must** carry a top-level `version = N` key - there is no "unversioned" file, and a missing key is a hard parse error. The daemon migrates a file **forward only**, one version at a time, the moment it loads it; there is no automatic downgrade path. A file whose version is *newer* than what a given Yerd build understands is rejected cleanly as `UnsupportedVersion` (a clear error naming both versions) rather than being partially parsed or silently corrupted - so an old binary reading a new file always fails safely. That rejection is also *why* you'd want this page: to hand-edit a newer file back down so an older build can read it, rather than losing your settings and starting from a blank config.

Each entry below states what changed, whether the daemon's own migration is a bare version-number bump (nothing else in the file needs to change to move forward) or a structural rewrite, and - under **To downgrade** - the exact manual edit that reverses it.

## Version-by-version

### v18 (current)

**Added:** the optional `[php.directives]` table - free-form (shape-validated) per-version ini directives such as `xdebug.mode`. `[php.directives."<version>"]` holds the directives for one installed version. It defaults to empty when absent, so an uncustomised file omits it entirely.

```toml
[php.directives."8.3"]
"xdebug.mode" = "debug"
```

The table loads **leniently**: an invalid or reserved entry (e.g. from a hand-edit) is dropped during parsing rather than failing the load, so a bad entry can never stop the daemon. A malformed version key is still a hard error, and the strict validation lives at set time (CLI/GUI/IPC).

**Migration from v17:** bare version bump - the table defaults to empty when absent, so a v17 file needs no other change.

**To downgrade to v17:** change `version = 18` to `version = 17` and delete any `[php.directives.*]` tables (a v17 daemon rejects the unknown tables under `deny_unknown_fields`, it doesn't just ignore them). Every version falls back to the `[php.settings]` and `[php.version_settings]` values.

### v17

**Added:** the top-level `mcp_enabled` scalar (bool) - whether `yerd mcp` serves Yerd's tools to local AI agents. Defaults to `false`, so exposing Yerd to agents is an explicit opt-in, and is always emitted.

```toml
mcp_enabled = false
```

The daemon runs no MCP server of its own: it stores this flag and reports it in the status report, and each `yerd mcp` session reads it to decide whether to serve. See [AI Agents](../guide/ai-agents).

**Migration from v16:** bare version bump - the key defaults to `false` when absent, so a v16 file needs no other change.

**To downgrade to v16:** change `version = 17` to `version = 16` and delete the `mcp_enabled` line (a v16 daemon rejects the unknown key under `deny_unknown_fields` rather than ignoring it). Agents lose access to Yerd's tools; nothing else is affected.

### v16

**Added:** the optional `[php.version_settings]` table - per-version overrides of the global PHP settings. `[php.version_settings."<version>"]` holds sparse overrides of the allowlisted `[php.settings]` directives for one installed version. It defaults to empty when absent, so an uncustomised file omits it entirely.

```toml
[php.version_settings."8.3"]
memory_limit = "1G"
```

The table loads **leniently**: an invalid entry (e.g. from a hand-edit) is dropped during parsing rather than failing the load, so a bad entry can never stop the daemon. A malformed version key is still a hard error, and the strict validation lives at set time (CLI/GUI/IPC).

**Migration from v15:** bare version bump - the table defaults to empty when absent, so a v15 file needs no other change to become a valid v16 file.

**To downgrade to v15:** change `version = 16` to `version = 15`, then delete any `[php.version_settings.*]` tables (a v15 daemon rejects the unknown tables under `deny_unknown_fields`, it doesn't just ignore them). Every version falls back to the global `[php.settings]` values.

### v15

**Added:** the multi-instance services rework - the optional per-instance `site` field inside `[services.<id>]` tables and the `"{type}:{site}"` wire ids for per-site app servers, plus a behaviour change: the `enabled` flag now actually gates boot autostart (before v15 every installed engine auto-started regardless).

**Migration from v14:** structural but small - the migration marks every existing single-instance engine (colon-free `[services.<id>]` key) `enabled = true`, so engines installed before the upgrade keep starting with Yerd now that the flag is enforced.

**To downgrade to v14:** change `version = 15` to `version = 14`, then delete any per-site `[services."<type>:<site>"]` tables and any `site = "..."` lines (a v14 daemon rejects the unknown field under `deny_unknown_fields`). Single-instance `enabled` flags survive; a v14 daemon auto-starts every installed engine regardless of the flag.

### v14

**Added:** the optional `[[proxies]]` array (whole-host reverse proxies) and the `[proxy_rules]` table (per-site path-prefix rules). Both default to empty when absent, so an uncustomised file omits them entirely.

```toml
[[proxies]]
name = "reverb"
target = "http://127.0.0.1:8080"
secure = true

[[proxy_rules.linked.myapp]]
prefix = "/app"
target = "http://127.0.0.1:8080"
```

`[proxy_rules]` is split by site class exactly like `[domains]`: `[proxy_rules.linked.<name>]` keys by site name, `[proxy_rules.parked."<docroot>"]` by byte-exact document-root. Removing a site's last rule drops its key, so the file round-trips byte-identically.

**Migration from v13:** bare version bump - both sections default to empty when absent, so a v13 file needs no other change to become a valid v14 file.

**To downgrade to v13:** change `version = 14` to `version = 13`, then delete any `[[proxies]]` entries and the whole `[proxy_rules]` table (a v13 daemon rejects the unknown tables under `deny_unknown_fields`, it doesn't just ignore them). Those proxies and rules stop being served; the sites they were attached to are otherwise unaffected.

### v13

**Added:** the optional per-site `front_controller` key (bool) inside `[[linked]]` and `[[overrides]]` - the toggle between single-front-controller mode (every request funnels through the site-root `index.php`) and direct script execution (a named `.php` under the served root runs directly). Absent = auto: a framework served from a subdirectory (non-empty `web_subpath`) defaults to front-controller mode; WordPress (any layout) and plain root-served sites default to direct execution.

```toml
[[overrides]]
path = "/home/me/projects/blog"
front_controller = false
```

**Migration from v12:** bare version bump - the field defaults to auto when absent, so a v12 file needs no other change to become a valid v13 file.

**Security note (behaviour change on upgrade):** because the default is auto, a plain root-served site (a parked directory that is a whole project, not just its `public/` dir) flips from single-front-controller mode to **direct execution** on upgrade. Any real `.php` under its served root - a stray `phpinfo.php`, `adminer.php`, an old admin tool, a vendored dev script - becomes directly URL-executable where it was previously funnelled to `index.php`. If the site is exposed beyond loopback (a tunnel), those files become remotely reachable. To keep the old behaviour, set `front_controller = true` on the site (`yerd front-controller <name> on`), or point its `web_root` at a clean public directory. Unknown paths still fall back to `index.php`, so custom-router apps are unaffected.

**To downgrade to v12:** change `version = 13` to `version = 12`, then delete any `front_controller` lines (a v12 daemon rejects the unknown key under `deny_unknown_fields`, it doesn't just ignore it).

### v12

**Added:** the top-level `symlink_protection` scalar (bool) - the global toggle for the proxy's symlink-escape guard. `true` (the default) blocks assets/scripts reached via a symlink resolving outside a site's document root; `false` serves them.

```toml
version = 12
symlink_protection = false
```

**Migration from v11:** bare version bump - the field defaults to `true` when absent, so a v11 file needs no other change to become a valid v12 file.

**To downgrade to v11:** change `version = 12` to `version = 11`, then delete the `symlink_protection` line (a v11 daemon rejects the unknown key under `deny_unknown_fields`, it doesn't just ignore it).

### v11

**Added:** the optional top-level `[domains]` table - per-site domain sets (a primary domain plus aliases, subdomains, and single-label wildcards). Split into `[domains.linked.<name>]` (keyed by site name) and `[domains.parked."<docroot>"]` (keyed by byte-exact document-root), each a delta of `added` / `suppressed` / `primary` stored as TLD-relative sub-parts. See the [Configuration Reference](../reference/configuration#domains) for the field-by-field shape.

```toml
[domains.linked.blog]
added = ["corp", "*.blog"]
suppressed = ["blog"]
primary = "corp"
```

**Migration from v10:** bare version bump - `[domains]` defaults to empty when absent, so a v10 file needs no other change to become a valid v11 file.

**To downgrade to v10:** change `version = 11` to `version = 10` and delete the entire `[domains]` table (including every `[domains.linked.*]` / `[domains.parked.*]` sub-table). Each affected site reverts to answering only its default apex `<name>.<tld>`; a v10 daemon rejects the `[domains]` key under `deny_unknown_fields` rather than ignoring it.

### v10

**Added (two independent, optional additions):**

1. The `wp_auto_login` (bool) and `wp_auto_login_user` (string) keys, inside both `[[linked]]` entries and `[[overrides]]` entries - one-click, pre-authenticated `WordPress` admin login, opt-in per site.
2. The `[php.extensions]` registry - custom `.so` extensions to load into both FPM and the CLI, keyed by PHP version and written as an array-of-tables per version.

```toml
[[linked]]
name = "blog"
document_root = "/Users/you/code/blog"
php = "8.3"
secure = true
kind = "linked"
wp_auto_login = true
wp_auto_login_user = "editor"

[[php.extensions."8.5"]]
name = "scrypt"
path = "/opt/homebrew/lib/php/pecl/20250925/scrypt.so"
zend = false
```

**Migration from v9:** bare version bump - both additions default to absent/empty when missing, so a v9 file needs no other change to become a valid v10 file.

**To downgrade to v9:** change `version = 10` to `version = 9`, then delete every `wp_auto_login`/`wp_auto_login_user` line from `[[linked]]`/`[[overrides]]` entries and remove any `[[php.extensions.*]]` tables (a v9 daemon rejects those keys under `deny_unknown_fields`, it doesn't just ignore them).

### v9

**Added:** the optional `[groups]` table - the desktop app's site-grouping overlay (cosmetic only; never affects routing).

```toml
[groups]
order = ["Client work", "Personal"]

[groups.members]
blog = "Personal"
shop = "Client work"
```

**Migration from v8:** bare version bump - `[groups]` defaults to empty when absent.

**To downgrade to v8:** change `version = 9` to `version = 8` and delete the entire `[groups]` table (including `[groups.members]`). You'll lose the group assignments; sites themselves are unaffected.

### v8

**Added:** the optional `[tunnel]` table - Cloudflare Tunnel sharing state (named tunnels and per-site hostnames).

```toml
[tunnel]
named = { my-tunnel = "1a2b3c4d-uuid" }

[tunnel.sites]
blog = "blog.example.com"
```

**Migration from v7:** bare version bump - `[tunnel]` defaults to empty when absent.

**To downgrade to v7:** change `version = 8` to `version = 7` and delete the `[tunnel]` table (and any `[tunnel.sites]`/`[tunnel.named]` sub-tables). Any active shared-tunnel sites will need reconfiguring after you're back on the older build.

### v7

**Added:** `fallback_http` and `fallback_https` keys inside `[ports]` (the rootless-fallback port pair, `8080`/`8443` by default, used when `80`/`443` need elevation).

```toml
[ports]
http = 80
https = 443
fallback_http = 8080
fallback_https = 8443
```

**Migration from v6:** bare version bump - both keys default to `8080`/`8443` when absent.

**To downgrade to v6:** change `version = 7` to `version = 6` and delete the `fallback_http`/`fallback_https` lines from `[ports]` (keep `http`/`https` - those predate v7).

### v6

**Added:** the top-level `update_channel` scalar (self-update channel selector, e.g. `"stable"`).

```toml
version = 6
update_channel = "stable"
```

**Migration from v5:** bare version bump - `update_channel` defaults to `"stable"` when absent.

**To downgrade to v5:** change `version = 6` to `version = 5` and delete the top-level `update_channel = "..."` line.

### v5

**Added:** the optional `[dumps]` table - Laravel ▸ Dumps telemetry capture settings.

```toml
[dumps]
enabled = true
port = 2304
persist = false

[dumps.features]
queries = true
jobs = false
```

**Migration from v4:** bare version bump - `[dumps]` defaults to disabled/empty when absent.

**To downgrade to v4:** change `version = 5` to `version = 4` and delete the `[dumps]` table (including `[dumps.features]`).

### v4

**Added:** the optional `[mail]` table - the built-in mail-capture SMTP server's `enabled`/`port` settings.

```toml
[mail]
enabled = true
port = 2525
```

**Migration from v3:** bare version bump - `[mail]` defaults to enabled on the default port when absent.

**To downgrade to v3:** change `version = 4` to `version = 3` and delete the `[mail]` table.

### v3

**Added:** nothing new - this is the one **structural** migration in the whole history. Every other version bump only adds optional keys; this one rewrites an existing one.

**Before (v0-v2):**

```toml
[services]
enabled = ["mysql", "redis"]
```

**After (v3+):**

```toml
[services.mysql]
enabled = true

[services.redis]
enabled = true
```

Each previously-listed service id becomes its own table with `enabled = true`; a service's `version`/`port` overrides (added independently, not tied to this migration) live inside that same per-service table.

**Migration from v2:** the daemon rewrites the flat `enabled = [...]` array into per-service tables automatically, then bumps the version - this is not a bare bump, but it *is* fully automatic and lossless (nothing to hand-edit going forward).

**To downgrade to v2:** change `version = 3` to `version = 2`, then manually reverse the rewrite: collect every `[services.<id>]` table whose `enabled` is `true` back into a flat array, and delete the per-service tables entirely.

```toml
version = 2

[services]
enabled = ["mysql", "redis"]
```

::: warning Downgrading past v3 loses per-service settings
A per-service `version`/`port` override (e.g. pinning Redis to a specific version, or a custom port) has nowhere to live in the v0-v2 shape - only the flat enabled-ids list survives. Note those values elsewhere before downgrading past v3 if you need them back later.
:::

### v2

**Added:** the optional `web_subpath` key inside `[[linked]]` entries, and `web_root` inside `[[overrides]]` entries - the served web-root override (e.g. `public/` for a Laravel project), independent of automatic detection.

```toml
[[linked]]
name = "blog"
document_root = "/Users/you/code/blog"
web_subpath = "public"
php = "8.3"
secure = true
kind = "linked"
```

**Migration from v1:** bare version bump - `web_subpath`/`web_root` default to "auto-detect" when absent.

**To downgrade to v1:** change `version = 2` to `version = 1` and delete any `web_subpath` (from `[[linked]]`) or `web_root` (from `[[overrides]]`) lines. Those sites fall back to Yerd's automatic web-root detection, which is usually - but not guaranteed to be - the same directory.

### v1

The first schema version any shipped build of Yerd actually wrote to disk. No older shipped file exists to migrate from in practice, but v0 is kept reachable in the migration chain for a hand-crafted `version = 0` file.

**To downgrade to v0:** not meaningful - no Yerd build has ever read a v0 file from disk. If you're here, you almost certainly want v1, which every build since the schema was introduced understands.

## Downgrading in practice

1. **Stop the daemon first.** Editing `yerd.toml` while `yerdd` is running risks it being overwritten by the next mutation (any `yerd park`/`yerd secure`/… command, or a GUI action, rewrites the whole file).
2. **Back up the file** before editing - `cp yerd.toml yerd.toml.bak` - so you can restore the newer version if the older build turns out not to be what you needed.
3. **Walk the versions one at a time**, newest to oldest, applying each "To downgrade" step above in order - don't skip straight from v11 to v5, since some steps (structural v3, in particular) need the intermediate shape.
4. **Reinstall/switch to the older Yerd build**, then start the daemon and confirm it comes up clean (check its log output for a config error) before relying on it.

If you'd rather not hand-edit at all: delete `yerd.toml` outright and let the older daemon boot with a fresh default config, then re-park/re-link your sites. That's often faster than a multi-version downgrade if you don't have many customised settings to preserve.

## See also

* [yerd-config crate reference](./crates/yerd-config) - the migration mechanism itself (`STEPS`, wire mirrors, `deny_unknown_fields`).
* [Configuration Reference](../reference/configuration) - the current schema's field-by-field guide.
* [yerd-platform crate reference](./crates/yerd-platform) - `PlatformDirs` and the config/data/state/cache/runtime split.
* [yerdd (daemon)](./binaries/yerdd) - where the config is loaded at startup (`startup::bring_up`).

---

---
url: 'https://yerd.app/developer/crates/yerd-core.md'
---
# yerd-core

`yerd-core` is the foundation of the Yerd workspace. It holds the **pure domain
model** - the validated value types that describe PHP versions, sites, and TLDs

* and the **host→site routing** algorithm that maps an incoming HTTP `Host:`
  header to a registered site. Every other crate in the workspace depends on it,
  directly or transitively.

The crate's defining property is its purity: **no I/O, no async, no internal
`yerd-*` dependencies, and `unsafe` is forbidden at the crate level.** Side
effects (reading config files, spawning processes, touching the filesystem or
the network) live behind traits in adapter crates such as
[`yerd-platform`](./yerd-platform). That separation is what lets the domain
logic be exhaustively unit-tested without mocks, and lets the same types travel
across the IPC boundary unchanged. See the [Crates Overview](../crates) for how
this fits the wider workspace, and the [IPC Protocol](../ipc-protocol) page for
the shared wire types these definitions pin.

## Crate metadata

```toml
[package]
name        = "yerd-core"
description = "Pure domain model and host→site routing for Yerd."

[dependencies]
serde     = { workspace = true }
thiserror = { workspace = true }

[dev-dependencies]
serde_json = { workspace = true }
serde_test = { workspace = true }
toml       = { workspace = true }
```

The only runtime dependencies are `serde` (for wire serialisation) and
`thiserror` (for the error enum). There are no internal dependencies - this is
the bottom of the dependency graph. The crate root opens with:

```rust
#![forbid(unsafe_code)]
```

`unsafe_code` is also forbidden workspace-wide (`[workspace.lints.rust]
unsafe_code = "forbid"`), so the crate-level attribute is belt-and-braces.

## Module map

The crate splits into focused modules; only a curated surface is re-exported
from `lib.rs`:

```rust
pub mod detect;
mod error;
mod host;
mod php;
pub mod php_settings;
mod router;
mod site;
mod tld;

pub use detect::{detect, Detection, ProjectSignals};
pub use domain::{choose_primary, effective_domains, Domain, DomainErrorReason};
pub use error::{CoreError, PhpVersionErrorReason, SiteNameErrorReason, TldErrorReason};
pub use php::PhpVersion;
pub use php_settings::{PhpSettingError, ValueErrorReason};
pub use router::{RouterConfig, SiteRouter};
pub use site::{Site, SiteKind};
pub use tld::Tld;
```

| Module          | Visibility    | Responsibility                                            |
| --------------- | ------------- | --------------------------------------------------------- |
| `error`         | re-exported   | `CoreError` + the typed `*Reason` sub-enums               |
| `php`           | re-exported   | `PhpVersion` `(major, minor)` value type                  |
| `site`          | re-exported   | `Site` / `SiteKind`                                       |
| `tld`           | re-exported   | `Tld` validated DNS-suffix newtype                        |
| `domain`        | re-exported   | `Domain` sub-part + `effective_domains` / `choose_primary` algebra |
| `router`        | re-exported   | `RouterConfig` + `SiteRouter` (the resolve algorithm)     |
| `php_settings`  | `pub mod`     | managed PHP ini directives + value validation             |
| `detect`        | `pub mod`     | pure web-root detection (`ProjectSignals` → `Detection`)  |
| `host`          | `pub(crate)`  | `Host:` header normalisation, consumed only by `resolve`  |

`php_settings` is a `pub mod` (callers reach functions as
`yerd_core::php_settings::validate_value(...)`); `host` is deliberately
crate-private - only `SiteRouter::resolve` consumes it.

## `PhpVersion`

A PHP `major.minor` pair. Both fields are `pub`, but the constructor that
accepts user input is `FromStr` - `new` is unchecked and intended for code
constructing known-good versions.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct PhpVersion {
    pub major: u8,
    pub minor: u8,
}

impl PhpVersion {
    #[must_use]
    pub const fn new(major: u8, minor: u8) -> Self { /* ... */ }
}
```

Deriving `Ord` on `(major, minor)` gives **numeric**, not lexicographic,
ordering: `(8, 9) < (8, 10) < (8, 99)`. `Display` emits the dotted form
(`"8.3"`).

### Parsing

`FromStr` (and therefore `Deserialize`) runs a pinned three-step algorithm:

1. **Leading-byte classification.** A non-ASCII first byte (letter, emoji,
   zero-width space, CJK) is rejected uniformly as `UnsupportedPrefix`. An ASCII
   letter is only accepted if the first three bytes are a case-insensitive
   `"php"` and nothing alphabetic follows - so `"php8.3"`, `"PHP8.3"`,
   `"Php8.3"` parse, but `"phpa8.3"`, `"v8.3"`, `"py8.3"` are
   `UnsupportedPrefix`. Anything else (digit, punctuation, whitespace) passes
   through to step 2.
2. **Shape.** `rest` must match `DIGIT+ "." DIGIT+`. A missing `.` is
   `MissingMinor`; an empty side or any non-digit byte is `NonNumeric`.
3. **Range.** Parts are parsed as `u16` so overflow is classified uniformly:
   `major ∈ 5..=9` else `MajorOutOfRange`; `minor ∈ 0..=99` else
   `MinorOutOfRange`; values ≥ 65536 that overflow `u16` are `NonNumeric`.

Parsing is total and never panics on multibyte input - the algorithm operates
on bytes and only does char-boundary-safe slicing. Round-tripping is
canonicalising: `"8.00"` parses to `(8, 0)` and displays as `"8.0"`.

### Serde shape

`PhpVersion` serialises as a **string** via `collect_str`, and deserialises
through a custom visitor that rejects JSON numbers and ints:

```rust
assert_tokens(&PhpVersion::new(8, 3), &[Token::Str("8.3")]);   // frozen
serde_json::from_str::<PhpVersion>("8.3").is_err();            // number → error
serde_json::from_str::<PhpVersion>("8").is_err();              // int → error
```

::: tip
The string representation is what makes the type safe to embed in TOML config
and JSON IPC payloads alike - a bare `8.3` in TOML would be a float and lose the
distinction between `8.10` and `8.1`.
:::

## `Site` and `SiteKind`

A `Site` is a routable target with a validated name, a document root, a served
web subpath, a PHP version, an HTTPS flag, and a kind. Fields are **private** to
enforce the name invariant; the type exposes accessors and typed setters.

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SiteKind {
    Parked,   // auto-discovered under a parked directory
    Linked,   // explicitly registered
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Site {
    name: String,
    document_root: PathBuf,
    web_subpath: PathBuf,   // served web root, relative to document_root ("" = root)
    php: PhpVersion,
    secure: bool,
    kind: SiteKind,
}
```

Construction goes through `Site::parked` or `Site::linked`, both of which
validate and lowercase the name and **initialise `secure = false`** (promote
with `set_secure`):

```rust
pub fn parked(name: &str, document_root: impl Into<PathBuf>, php: PhpVersion)
    -> Result<Self, CoreError>;
pub fn linked(name: &str, document_root: impl Into<PathBuf>, php: PhpVersion)
    -> Result<Self, CoreError>;
```

Accessors: `name() -> &str`, `document_root() -> &Path`,
`web_subpath() -> &Path`, `php() -> PhpVersion`, `secure() -> bool`,
`kind() -> SiteKind`. Setters: `set_document_root`, `set_web_subpath`,
`set_php`, `set_secure`, `set_kind`.

`served_root() -> PathBuf` is the directory the proxy actually serves:
`document_root` when `web_subpath` is empty (avoiding a stray `join("")`
trailing separator), else `document_root.join(web_subpath)`. It is **defensive by
construction - it can never escape the document root**: an absolute or
`..`-bearing `web_subpath` (which `Path::join` would let climb out) falls back to
serving the document root. The authoritative containment check is in `yerd-config`
at load time; `served_root` is the second line of defence because `Site` itself
does no path validation.

There is **no `set_name`**. The name is immutable after construction because it
doubles as the router's lookup key - renaming is a router-level remove/reinsert
operation, not a field mutation. This is what makes `SiteRouter::get_mut` safe:
a caller can mutate any field of a stored site without the routing key drifting.

### Name validation

`validate_and_lowercase_name` runs a pinned, ordered algorithm. The order is
load-bearing and is pinned by tests - e.g. `ContainsDot` (step 2) beats
`LabelTooLong` (step 6), and `LeadingOrTrailingHyphen` (step 5) beats length:

1. empty → `Empty`
2. contains `.` → `ContainsDot` (sites are single DNS labels)
3. byte outside `[A-Za-z0-9-]` (including any non-ASCII or whitespace) →
   `InvalidCharacter`
4. lowercase
5. leading/trailing `-` → `LeadingOrTrailingHyphen`
6. length > 63 bytes → `LabelTooLong` (RFC 1035 single label; byte length equals
   char length because step 3 rejected non-ASCII)

### Document root is *not* validated

```rust
// document_root is **not** validated by yerd-core - this is a pure crate.
```

`document_root` may be empty, relative, or non-canonical. Path semantics,
existence, and platform normalisation belong to `yerd-config` (load time) and
[`yerd-platform`](./yerd-platform) (runtime). Serde uses `PathBuf`'s default
string representation, which is lossy for paths that are not valid UTF-8;
callers needing a guaranteed-UTF-8 path must normalise upstream.

### Serde shape

`Site` has a hand-written `Serialize` and a `Deserialize` that routes through a
private `Wire` struct with `#[serde(deny_unknown_fields)]` and then re-runs name
validation/lowercasing. `web_subpath` is **skipped when empty** (the struct
serialises 5 fields then, 6 when a subpath is set), so the byte shape for a
root-served site is byte-identical to before the field existed:

```json
{"name":"foo","document_root":"/srv/foo","php":"8.3","secure":false,"kind":"parked"}
{"name":"app","document_root":"/srv/app","web_subpath":"public","php":"8.3","secure":false,"kind":"linked"}
```

The `Wire` deserialiser marks `web_subpath` `#[serde(default)]`, so a payload
written before the field existed (no `web_subpath` key) parses as the empty
subpath. Deserialisation lowercases the name, rejects invalid names, and rejects
*other* unknown fields - so config files and IPC payloads can't smuggle an
unvalidated site past the type boundary.

## `Tld`

A validated, lowercased, ASCII-only DNS-suffix newtype used by the router for
TLD enforcement.

```rust
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Tld(String);

impl Tld {
    pub fn new(s: &str) -> Result<Self, CoreError>;   // validate + lowercase
    #[must_use] pub fn as_str(&self) -> &str;
}

impl Default for Tld {                 // yields the canonical ".test"
    fn default() -> Self { Self(String::from("test")) }
}
```

`Default` returns the canonical `test` TLD - the *only* hard-coded TLD
construction in the crate, and a test (`default_is_test_and_matches_new`) walks
every validation step against `"test"` so a future tightening of `validate`
can't silently break the default.

Validation (`Tld::new` / `FromStr` / `Deserialize`) is again a pinned algorithm:
reject empty; strip one trailing `.` then reject leading/trailing/empty dots;
cap total length at 253 bytes; reject non-ASCII and whitespace; lowercase; then
per-label checks (no empty labels → `ConsecutiveDots`, ≤ 63 bytes, `[a-z0-9-]`
only, no leading/trailing hyphen). Multi-label suffixes such as `"dev.local"`
are valid. Serde shape is a plain string (`"test"`).

## `php_settings`

A pure module modelling the small, fixed set of global PHP ini directives Yerd
manages. These values flow **unescaped** into every installed version's FPM pool
config as `php_value[...]` / `php_flag[...]` lines, so `validate_value` is the
**security boundary** against config injection. It runs when a value is set
(CLI + daemon), when config is loaded (`yerd-config`), and defensively again at
render time ([`yerd-php`](./yerd-php)).

The allowlist (extend here to support more directives):

| Directive             | Kind                          | Renders as  |
| --------------------- | ----------------------------- | ----------- |
| `memory_limit`        | byte size (`-1` allowed)      | `php_value` |
| `max_execution_time`  | non-negative integer          | `php_value` |
| `max_input_time`      | non-negative integer          | `php_value` |
| `max_file_uploads`    | non-negative integer          | `php_value` |
| `upload_max_filesize` | byte size                     | `php_value` |
| `post_max_size`       | byte size                     | `php_value` |
| `display_errors`      | flag (boolean)                | `php_flag`  |
| `error_reporting`     | int or constant expression    | `php_value` |

Public surface:

```rust
pub fn is_supported(name: &str) -> bool;
pub fn supported_names() -> Vec<&'static str>;       // declaration order
pub fn directive(name: &str) -> Option<&'static str>; // "php_flag" | "php_value"
pub fn validate_value(name: &str, value: &str) -> Result<(), PhpSettingError>;
pub fn canonical_value(name: &str, value: &str) -> String;
```

`validate_value` enforces a global invariant *before* the per-kind shape:
non-empty / not all-whitespace, `≤ 256` bytes, no control characters, and none
of the FPM/ini metacharacters `[ ] = ; #`. The per-kind validators are
hand-rolled (no `regex` dependency): byte sizes accept `\d+[KMGkmg]?` (plus `-1`
only when `allow_unlimited`), integers accept ASCII digits, flags accept
`on|off|1|0|true|false` case-insensitively, and `error_reporting` accepts an
integer or a constant expression limited to `[A-Za-z0-9_ &|~^()-]`.
`canonical_value` normalises validated booleans to `On`/`Off` and trims the
rest.

::: warning Security boundary
Injection attempts - embedded newlines, `;`, `#`, `]`, `=`, or over-length
input - are all rejected here. Downstream renderers re-validate, but this is the
first and primary gate.
:::

## `detect`

A pure module that decides which subdirectory of a PHP project is its web root.
It is the *decision* half of framework detection; the *I/O* half - reading
`composer.json` and stat-ing marker files - lives in
[`yerd-platform`](./yerd-platform), which feeds this function a `ProjectSignals`.

```rust
pub struct ProjectSignals {
    pub composer_requires: BTreeSet<String>,   // lowercased composer package names
    pub markers: BTreeSet<String>,             // present root markers: "artisan", "wp-config.php", …
    pub web_dirs_with_index: BTreeSet<String>, // candidate dirs containing index.php
}

pub struct Detection { pub subpath: PathBuf, pub resolved: bool } // "" = serve root

pub fn detect(sig: &ProjectSignals) -> Detection;

pub const WEB_DIR_CANDIDATES: &[&str]; // ["public", "web", "webroot", "pub"]
pub const ROOT_MARKERS: &[&str];       // the marker files/dirs the gatherer probes
```

`detect` runs a first-match-wins precedence: Laravel / Symfony (4+) /
CodeIgniter 4 → `public`, CakePHP → `webroot`, Drupal (Composer) / Yii2 → `web`,
Magento 2 → `pub`, WordPress / plain-PHP → root, then a generic
"first candidate web dir with an `index.php`" fallback, then root.

`Detection::resolved` is the signal the daemon's filesystem watcher keys on: it
is `true` for every confident branch (a framework or web dir was identified, or
the project is a confident root like WordPress) and **`false` only for the
no-evidence fallback** - an empty folder served at root provisionally. The daemon
keeps watching the unresolved ones so a project cloned in later is picked up. The
shared `WEB_DIR_CANDIDATES` / `ROOT_MARKERS` consts keep the pure decider and the
platform gatherer from drifting on what to probe. Every branch is table-tested
with fixture `ProjectSignals` (precedence, mixed signals, empty-project default).

## `Domain` and the effective-set algebra

A `Domain` is the **sub-part** of a routable host - everything left of the
configured TLD. For TLD `test`: `foo`, `api.foo`, `*.foo`, `*.api.foo`. Storing
the sub-part (not the FQDN) is canonical because the router strips the TLD before
matching, and it keeps the value TLD-agnostic. A leftmost `*` label is a
**single-label wildcard**. `Domain` deliberately derives no serde - config
persists it through wire mirrors, and IPC carries FQDN strings.

```rust
pub struct Domain { /* private: the validated sub-part */ }

impl Domain {
    #[must_use] pub fn apex(name: &str) -> Self;                 // a site's default exact domain
    pub fn parse(fqdn: &str, tld: &str) -> Result<Self, CoreError>;   // strips + checks the TLD
    pub fn parse_subpart(sub: &str) -> Result<Self, CoreError>;       // from stored config
    #[must_use] pub fn as_str(&self) -> &str;                    // the stored sub-part
    #[must_use] pub fn is_wildcard(&self) -> bool;              // leftmost label is '*'
    #[must_use] pub fn to_fqdn(&self, tld: &str) -> String;    // sub-part + '.' + tld
}
```

Two free functions own the pure "effective set" algebra a site's routable domains
are computed with (`implicit_default ± delta`):

* `effective_domains(name, added, suppressed) -> Vec<Domain>` = `({apex} - suppressed) + added`, de-duplicated, apex-first. There is **no** implicit subdomain catch-all; the default set is just the apex. Zero-exact normalization restores the apex if a hand-edited config would otherwise leave only wildcards, so a site is always reachable under one concrete host.
* `choose_primary(name, effective, stored) -> Domain` picks the canonical, displayed domain: the stored primary if it is exact and still present, else the apex if present, else the first exact. A wildcard is never a primary.

`DomainErrorReason` (on `CoreError::InvalidDomain`) enumerates the shape failures
(`Empty`, `EmptyLabel`, `MisplacedWildcard`, `BareWildcard`, `NotUnderTld`,
`TooLong`, `LabelTooLong`, `InvalidCharacter`, `LeadingOrTrailingHyphen`).

## `SiteRouter` and `RouterConfig`

`RouterConfig` pairs a `Tld` with a **cached** `".{tld}"` suffix used on the hot
path. Its invariant - `dotted_tld == format!(".{}", tld.as_str())` - is upheld
by construction only; there is no field-by-field constructor.

```rust
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RouterConfig {
    tld: Tld,
    dotted_tld: String,   // cache; NEVER serialised
}

impl RouterConfig {
    pub fn new(tld: &str) -> Result<Self, CoreError>;   // validates
    #[must_use] pub fn with_tld(tld: Tld) -> Self;      // pre-computes dotted_tld
    #[must_use] pub fn tld(&self) -> &str;
    #[must_use] pub fn tld_typed(&self) -> &Tld;
}
```

Serde emits exactly one field, `tld` (`{"tld":"test"}`); the `dotted_tld` cache
is never serialised, and `Deserialize` rebuilds it via `RouterConfig::new` with
`deny_unknown_fields`.

`SiteRouter` keeps a `BTreeMap<String, Site>` keyed by `site.name()` (for
identity and ordered iteration), plus - since the multi-domain feature - two
`HashMap` routing indices built from every site's effective domain set: `exact`
(sub-part → name) and `wildcards` (`*.rest` → name), and per-site `domains` /
`primaries` maps. `Default` is **deliberately not derived** - callers must pass a
config consciously rather than relying on an implicit `"test"`.

```rust
impl SiteRouter {
    #[must_use] pub fn new(config: RouterConfig) -> Self;
    pub fn from_sites(config: RouterConfig, sites: impl IntoIterator<Item = Site>)
        -> Result<Self, CoreError>;                       // first dup aborts
    pub fn insert(&mut self, site: Site) -> Result<(), CoreError>;   // DuplicateSite
    // Insert a site with an explicit effective domain set + chosen primary; the
    // colliding-key safety net returns DuplicateSite / DuplicateDomain.
    pub fn insert_with_domains(&mut self, site: Site, effective: Vec<Domain>, primary: Domain)
        -> Result<(), CoreError>;
    pub fn remove(&mut self, name: &str) -> Result<Site, CoreError>; // SiteNotFound
    #[must_use] pub fn get(&self, name: &str) -> Option<&Site>;
    pub fn get_mut(&mut self, name: &str) -> Option<&mut Site>;
    pub fn iter(&self) -> impl Iterator<Item = &Site> + '_;          // name order
    #[must_use] pub fn len(&self) -> usize;
    #[must_use] pub fn is_empty(&self) -> bool;
    #[must_use] pub fn config(&self) -> &RouterConfig;
    #[must_use] pub fn resolve(&self, host: &str) -> Option<&Site>;
    // Domain accessors used by the daemon's DTO/doctor surfaces:
    #[must_use] pub fn domain_owner(&self, domain: &Domain) -> Option<&str>;
    #[must_use] pub fn primary_domain(&self, name: &str) -> Option<&Domain>;
    #[must_use] pub fn effective_domains(&self, name: &str) -> Option<&[Domain]>;
    #[must_use] pub fn apex_shadowed_by(&self, name: &str) -> Option<&str>;
}
```

Because the map is a `BTreeMap`, `iter` yields sites in lexicographic name order
deterministically. `get_mut` is invariant-safe precisely because `Site` has no
`set_name`. The plain `insert` gives a site only its default apex;
`insert_with_domains` is how the daemon installs a customised domain set.

### The `resolve` algorithm

`resolve` maps a raw `Host:` header value to at most one site. It first
normalises the host (via the private `host` module), then does an exact lookup
followed by a **single-label wildcard** lookup. There is **no** implicit
subdomain catch-all: an uncustomised site answers only its exact apex.

**Step 1 - host normalisation** (`host::normalise`), returning either a clean
hostname or `Unroutable`:

```
1. empty                              → Unroutable
2. starts with '['  (IPv6/bracketed)  → Unroutable
3. any non-ASCII byte                 → Unroutable
4. strip port via rsplit_once(':'):
     - no ':'                         → keep
     - tail empty or all-digits       → strip it
     - otherwise (junk tail)          → Unroutable
5. empty after strip                  → Unroutable
6. strip one trailing '.'  (FQDN)     → if now empty, Unroutable
7. starts with '.'                    → Unroutable
8. lowercase if any uppercase; else borrow (Cow)
```

The `Cow` return means the common already-normalised case (`"foo.test"`)
allocates nothing.

**Step 2 - routing**, on the normalised hostname:

```
let sub = host.strip_suffix(".{tld}")?;     // must end with the TLD; None otherwise
if host == tld          → None              // bare TLD has no site label
if sub.is_empty()       → None
if exact.get(sub)       → Some              // exact match beats wildcard
// single-label wildcard: replace the LEFTMOST label with '*', one lookup only
if let Some((_, rest)) = sub.split_once('.') {
    if wildcards.get(&format!("*.{rest}"))  → Some
}
None
```

Exact is always tried before the one wildcard candidate, so exact beats wildcard.
A wildcard matches exactly one label: `*.foo` (stored for a site) answers
`api.foo.test` but never `x.api.foo.test` (which needs `*.api.foo`). With only
`foo` registered, `api.foo.test` is unresolved (404). This lets `foo.test` and
`*.foo.test` belong to two **different** sites.

The behaviour is pinned by the router's table tests. Representative rows (site
`foo` registered with default apex only, unless a domain is noted):

| Host                | Resolves to | Rule                                      |
| ------------------- | ----------- | ----------------------------------------- |
| `foo.test`          | `foo`       | exact apex                                |
| `foo.test:8443`     | `foo`       | port stripped                             |
| `foo.test:abc`      | -           | port junk → unroutable                    |
| `[::1]:8080`        | -           | IPv6 literal                              |
| `foo.test.`         | `foo`       | trailing FQDN dot stripped                |
| `FOO.TEST`          | `foo`       | case-insensitive                          |
| `föö.test`          | -           | non-ASCII                                 |
| `foo.example`       | -           | wrong TLD                                 |
| `test`              | -           | bare TLD                                  |
| `api.foo.test`      | -           | no implicit catch-all (apex-only default) |
| `api.foo.test`      | `foo`       | when `*.foo` is registered on `foo`       |
| `x.api.foo.test`    | -           | single-label wildcard doesn't nest        |
| `foo..test`         | -           | embedded empty label                      |
| `foo.dev.local`     | `foo`       | multi-label custom TLD                    |

::: info
`resolve` returns `&Site`, so a hit gives the caller the full record -
document root, served web root (`served_root()`), PHP version, and `secure` flag -
needed to dispatch the request. The proxy and daemon hold a `SiteRouter` and call
`resolve` per request.
:::

## Error model

`CoreError` is the single error type for every fallible public API in the crate.
Each variant carries a typed `*Reason` sub-enum so callers match on precise
failure modes without parsing message strings. Every error enum is
`#[non_exhaustive]`, so new variants are semver-compatible additions.

```rust
#[derive(Debug, Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum CoreError {
    InvalidPhpVersion { input: String, reason: PhpVersionErrorReason },
    InvalidTld        { input: String, reason: TldErrorReason },
    InvalidDomain     { input: String, reason: DomainErrorReason },
    DuplicateSite     { name: String },
    DuplicateDomain   { domain: String },
    SiteNotFound      { name: String },
    InvalidSiteName   { name: String, reason: SiteNameErrorReason },
}
```

`DuplicateDomain` is the router's colliding-key safety net (mirroring
`DuplicateSite`), returned by `insert_with_domains` when two domains map to the
same routing key; the daemon feeds a pre-de-conflicted set so it never fires in
production.

`php_settings` has its own pair, `PhpSettingError` (`Unsupported` /
`InvalidValue`) with `ValueErrorReason`. All error types are `Send + Sync +
Clone + Eq`, which lets them cross the IPC boundary and be compared in tests.

## Tests and invariants

Each module carries exhaustive unit tests (reason-by-reason validation tables,
ordering pins, serde-token assertions). Two **integration tests** under
`tests/` guard the cross-crate contract:

* **`serde_roundtrip.rs`** - proves the public types compose into the shapes
  downstream crates need. A `ConfigShape { php, tld, sites }` round-trips
  through TOML (mirroring what `yerd-config` loads), and an
  `IpcSetPhp { name, version }` round-trips through JSON (mirroring a `yerd-ipc`
  request payload). It asserts the human-readable forms, e.g.
  `php = "8.3"` and `tld = "test"` in TOML.

* **`wire_stability.rs`** - pins byte-exact JSON shapes for the public types.
  Renaming any public field, variant, or type name fails this file, which fails
  CI before [`yerd-ipc`](./yerd-ipc) can ship a divergent wire format:

  ```rust
  // PhpVersion          → "8.3"
  // SiteKind::Parked     → "parked"   (snake_case)
  // Site                 → {"name":"foo","document_root":"/srv/foo","php":"8.3","secure":false,"kind":"parked"}
  // RouterConfig::default → {"tld":"test"}
  ```

Together these make `yerd-core` the place where the wire contract is *defined
and frozen*, not merely consumed.

## Design boundaries - what `yerd-core` does *not* do

* **No I/O or async.** It never reads config, spawns FPM, or touches DNS - those
  live in `yerd-config`, [`yerd-php`](./yerd-php), [`yerd-dns`](./yerd-dns), and
  [`yerd-platform`](./yerd-platform).
* **No path validation.** `document_root` correctness is a load-time / runtime
  concern.
* **No `unsafe`.** Forbidden at the crate root and workspace-wide.
* **No implicit defaults that matter operationally.** `SiteRouter` has no
  `Default`; the only hard-coded value is the `.test` TLD via `Tld::default`.

## Source

Browse the crate on GitHub:
[`crates/yerd-core`](https://github.com/forjedio/yerd/tree/main/crates/yerd-core).

See also: [Crates Overview](../crates) · [IPC Protocol](../ipc-protocol) ·
[Architecture](../architecture) · [Cross-Platform Model](../cross-platform).

---

---
url: 'https://yerd.app/developer/crates/yerd-ipc.md'
---
# yerd-ipc

The IPC protocol, framing, and codec that sit between `yerdd` (the daemon) and its clients - the [`yerd` CLI](../binaries/yerd) and the [Tauri GUI](../gui). The crate owns the *shape of the wire*: the message envelopes, the length-prefixed frame codec, the error types, and an optional async transport. It owns nothing about *where* the wire is (Unix sockets, named pipes); that binding lives in the binaries.

::: tip Looking for the protocol semantics?
This page documents the **crate** - its modules, public API, and design decisions. For the end-to-end protocol walkthrough (connection lifecycle, request/response choreography, version-skew handling) see [IPC Protocol](../ipc-protocol).
:::

## At a glance

| Property | Value |
| --- | --- |
| Crate path | [`crates/yerd-ipc`](https://github.com/forjedio/yerd/tree/main/crates/yerd-ipc) |
| Default build | **pure**: no sockets, no async, no I/O |
| Runtime deps | `yerd-core`, `serde`, `serde_json`, `thiserror` |
| Optional dep | `tokio` (only via the `transport` feature) |
| Wire format | 4-byte big-endian `u32` length prefix + UTF-8 JSON payload |
| Default frame cap | 16 MiB (`DEFAULT_MAX_FRAME`) |
| Protocol version | `PROTOCOL_VERSION = 1` (reserved; no handshake yet) |

## Module map

The crate is small and deliberately flat. Every module is private; the public surface is the curated re-export list in `lib.rs`.

```
src/
├── lib.rs         re-exports, PROTOCOL_VERSION, types module
├── frame.rs       encode_frame + FrameDecoder (pure length-prefix codec)
├── message.rs     encode_message / decode_message (serde_json wrappers)
├── request.rs     Request enum (client → daemon)
├── response.rs    Response enum + ErrorCode + PhpUpdate (daemon → client)
├── create.rs      CreateSiteSpec + Framework/StarterKit/Database/… (the `yerd create` site-scaffold spec) + JobId/JobState
├── dump.rs        DumpCategory / DumpEvent / DumpCounts / DumpExtStatus (Laravel ▸ Dumps telemetry)
├── status.rs      StatusReport / Diagnosis / FixReport and friends
├── error.rs       FrameError, IpcError, IpcErrorKind
└── transport.rs   #[cfg(feature = "transport")] async read/write helpers
```

The public re-exports, copied from `lib.rs`:

```rust
pub use create::{
    AuthProvider, CreateSiteSpec, Database, Framework, JobId, JobState, JsRuntime, LaravelOptions,
    StarterKit, Testing,
};
pub use dump::{DumpCategory, DumpCounts, DumpEvent, DumpExtStatus};
pub use error::{FrameError, IpcError, IpcErrorKind};
pub use frame::{encode_frame, FrameDecoder, DEFAULT_MAX_FRAME};
pub use message::{decode_message, encode_message};
pub use request::Request;
pub use response::{ErrorCode, PhpUpdate, Response};
pub use status::{
    CaStatus, DatabaseSummary, Diagnosis, DiagnosisCode, FixReport, FixResult, MailDetail,
    MailHeader, MailStatus, MailSummary, PhpPoolStatus, PoolRunState, PortStatus,
    ServiceAvailability, ServiceRunState, ServiceStatus, Severity, SiteCounts, StatusReport,
    ToolStatus,
};

pub mod types {
    pub use yerd_core::{PhpVersion, Site, SiteKind};
}

#[cfg(feature = "transport")]
pub use transport::{read_frame, read_message, write_message};
```

The `types` module re-exports the [`yerd-core`](./yerd-core) types that travel on the wire so a client can depend on `yerd-ipc` alone (`use yerd_ipc::types::*;`) rather than pulling `yerd-core` directly.

## Purity and the `transport` feature

The headline design constraint is that **the default build is pure**: no sockets, no async runtime, no I/O. `Cargo.toml` makes `tokio` optional and gates it behind a feature:

```toml
[features]
default   = []
transport = ["dep:tokio"]
```

That split lets the codec be unit-tested without a runtime, lets the GUI link the message types without dragging `tokio` into its dependency graph if it doesn't need the helpers, and keeps the framing logic provably allocation- and side-effect-free. The daemon and CLI build with `--features transport` to get the async read/write helpers; everything else uses the pure surface.

Two further purity rules the crate enforces on itself: no `tracing` (the binaries own logging), and no `unwrap`/`expect`/`panic!`/indexing in non-test code (the workspace clippy gate denies them - even test modules carry an explicit `#[allow(...)]` block).

## The frame codec (`frame.rs`)

Every message is a length-prefixed frame: a 4-byte big-endian `u32` length followed by exactly that many payload bytes. The codec is **byte-agnostic** - it takes and returns `&[u8]` / `Vec<u8>` and never inspects payload contents. JSON encoding is an orthogonal layer (`message.rs`).

### `encode_frame`

```rust
pub fn encode_frame(payload: &[u8], max: usize) -> Result<Vec<u8>, FrameError>
```

Prepends the big-endian length and returns the framed bytes. `max` is **inclusive** (`payload.len() == max` is allowed). It fails with `FrameError::TooLarge` when the payload exceeds `max`, or `FrameError::PayloadOverflowsLengthPrefix` when the length does not fit in a `u32` (only reachable on 64-bit hosts). The sender capping with `max` lets it reject oversized payloads *before they hit the wire*; the receiver enforces its own cap independently. Both sides default to `DEFAULT_MAX_FRAME` (16 MiB) for symmetry.

### `FrameDecoder`

```rust
pub struct FrameDecoder { /* buf, max, poisoned */ }

impl FrameDecoder {
    pub fn new() -> Self;                                   // == with_max(DEFAULT_MAX_FRAME)
    pub fn with_max(max: usize) -> Self;
    pub fn with_max_and_capacity(max: usize, capacity: usize) -> Self;
    pub fn buffered(&self) -> usize;
    pub fn extend_from_slice(&mut self, chunk: &[u8]);
    pub fn next_frame(&mut self) -> Result<Option<Vec<u8>>, FrameError>;
}
```

The decoder is a small state machine. You feed it socket bytes with `extend_from_slice` and pull complete frames with `next_frame`:

* `Ok(Some(payload))` - one full frame is ready; any surplus bytes (from pipelined frames) stay buffered for the next call.
* `Ok(None)` - the header or body is still incomplete; feed more bytes.
* `Err(FrameError::TooLarge)` - the wire-declared length exceeds `max`.

It handles partial reads (header or body split across reads), multiple frames in a single buffer, and a hostile declared length.

::: warning Poisoning is permanent
When `next_frame` rejects an oversized declared length, the decoder is **poisoned**: it clears (and shrinks) its internal buffer to release memory, subsequent `next_frame` calls return the *same* error, and `extend_from_slice` becomes a no-op. Because `buffered()` then returns `0`, a transport helper reading a poisoned decoder at EOF may surface `IpcError::UnexpectedEof { bytes: 0 }`. There is no un-poison; a poisoned connection is dead.
:::

The length check itself is a tiny private helper, `check_payload_length(len, max) -> Result<u32, FrameError>`, shared by `encode_frame` and exercised directly by the unit tests (zero/zero, at-cap, one-over-cap, and the 64-bit `u32` overflow case).

## The message codec (`message.rs`)

```rust
pub fn encode_message<T: Serialize>(value: &T) -> Result<Vec<u8>, IpcError>;
pub fn decode_message<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, IpcError>;
```

These are thin `serde_json` wrappers that map `serde_json::Error` to `IpcError::Encode` / `IpcError::Decode`. Framing is entirely separate, so you can encode a message, inspect or log the JSON, and frame it later - or vice versa.

## Message envelopes

### `Request` (`request.rs`)

The client → daemon envelope is an internally tagged, `snake_case`, `#[non_exhaustive]` enum:

```rust
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
#[non_exhaustive]
pub enum Request { /* ... */ }
```

The variants, grouped by area:

| Area | Variants |
| --- | --- |
| Liveness / info | `Ping`, `DaemonInfo`, `Status`, `Diagnose`, `DoctorFix`, `RestartDaemon` |
| Sites | `ListSites`, `Park`, `Link`, `Unlink`, `ListParked`, `Unpark`, `SetPhp`, `SetSecure`, `SetWebRoot` |
| Domains | `AddDomain`, `RemoveDomain`, `SetPrimaryDomain`, `ResetDomains` |
| PHP | `InstallPhp`, `InstallPhpStreamed`, `SetDefaultPhp`, `ListPhp`, `UpdatePhp`, `CheckPhpUpdates`, `AvailablePhp`, `SetPhpSettings`, `RestartPhp`, `RestartAllPhp`, `UninstallPhp` |
| Services | `ListServices`, `AvailableServices`, `InstallService`, `UninstallService`, `StartService`, `StopService`, `RestartService`, `SetServicePort`, `ServiceLogs`, `ChangeServiceVersion` |
| Databases | `CreateDatabase`, `ListDatabases`, `DropDatabase`, `BackupDatabase`, `RestoreDatabase` |
| Dumps (Laravel ▸ telemetry) | `ListDumps`, `ClearDumps`, `DeleteDump`, `SetDumpsEnabled`, `SetDumpsPort`, `SetDumpFeature`, `SetDumpsPersist`, `DumpsStatus` |
| Mail | `ListMails`, `GetMail`, `ClearMails`, `DeleteMails`, `MarkMailsRead`, `SetMailPort`, `SetMailEnabled` |
| Tools | `ListTools`, `InstallTool`, `UninstallTool`, `InstallToolStreamed` |
| Site creation / jobs | `CreateSite`, `JobStatus`, `JobCancel` |

A few details that the source pins down and are worth knowing as a contributor:

* `Park`/`Link` carry a `PathBuf`; the path is opaque to `yerd-ipc` (the daemon canonicalises before storing) and Windows backslash paths are fine.
* `Unpark` carries a `String`, **not** a `PathBuf`, deliberately: the daemon stores parked roots as canonical `String`s in a `BTreeSet` and the client echoes a value straight back from `Response::Parked`, so an exact identity match avoids lossy `PathBuf` normalisation, and a folder deleted from disk stays removable.
* `UpdatePhp { version: Option<PhpVersion> }` - `Some` targets one minor, `None` means every installed version.
* `SetPhpSettings { settings: BTreeMap<String, String> }` - an empty-string value removes a key (resets it to PHP's built-in default).
* `SetWebRoot { name: String, path: Option<String> }` - sets a site's served web root (e.g. `"public"`); `None` resets it to auto-detection. The daemon validates the path resolves to a directory inside the site's document root.
* `RestartDaemon` is Unix-only; the daemon replies `Ok` *before* tearing down, then the connection closes as it re-execs.

### `Response` (`response.rs`)

Same shape - internally tagged, `snake_case`, `#[non_exhaustive]`:

| Variant | Replies to | Notable fields |
| --- | --- | --- |
| `Pong` | `Ping` | - |
| `Ok` | mutating requests (`Park`, `Link`, `Unlink`, `SetPhp`, `SetSecure`, `SetWebRoot`, …) | - |
| `Error` | any failure | `code: ErrorCode`, `message: String` |
| `Sites` | `ListSites` | `sites: Vec<SiteEntry>` (lexicographic); each `SiteEntry` flattens a `Site` and adds the domain fields `primary_domain: Option<String>`, `domains: Vec<String>`, `apex_shadowed_by: Option<String>` (all skip-when-default, so a default site's bytes are unchanged) |
| `Parked` | `ListParked` | `paths: Vec<String>` |
| `Info` | `DaemonInfo` | `dns_addr`, `tld`, `ca_path`, `ca_fingerprint`, `http_port`, `https_port` |
| `PhpVersions` | `ListPhp` / `CheckPhpUpdates` / `UpdatePhp` | `installed`, `default`, `updates`, `settings` |
| `AvailablePhp` | `AvailablePhp` | `available`, `installed` |
| `Status` | `Status` | `report: Box<StatusReport>` |
| `Diagnoses` | `Diagnose` | `items: Vec<Diagnosis>` |
| `DoctorFix` | `DoctorFix` | `report: FixReport` |
| `Services` | `ListServices` | `services: Vec<ServiceStatus>` |
| `AvailableServices` | `AvailableServices` | `services: Vec<ServiceAvailability>` |
| `ServiceLogs` | `ServiceLogs` | `lines: Vec<String>` |
| `Databases` | `ListDatabases` | `databases: Vec<DatabaseSummary>` |
| `Dumps` | `ListDumps` | `events: Vec<DumpEvent>` + deleted ids (cursor paging) |
| `DumpsStatus` | `DumpsStatus` / dump toggles | `enabled`, `port`, persist/feature flags |
| `Mails` | `ListMails` | `mails: Vec<MailSummary>` |
| `Mail` | `GetMail` | `Box<MailDetail>` |
| `Tools` | `ListTools` | `tools: Vec<ToolStatus>` |
| `JobStarted` | `CreateSite` / `InstallToolStreamed` / `InstallPhpStreamed` | `job_id: JobId` (poll with `JobStatus`) |
| `JobProgress` | streamed job updates | `state: JobState`, phase label, … |

Notable behaviours:

* `Status` boxes its report (`Box<StatusReport>`) so the large payload doesn't bloat every `Response` value. `Box<T>` serializes transparently, so the wire bytes are unchanged.
* `Info.http_port` / `Info.https_port` are `#[serde(default)]` (defaulting to `0`) so an older daemon that omits them stays decodable by a newer client.
* `PhpVersions.updates` and `PhpVersions.settings` are `#[serde(default, skip_serializing_if = ...)]` - empty collections vanish from the wire, keeping the bytes identical to the pre-field shape.

### `ErrorCode`

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ErrorCode { NotFound, AlreadyExists, InvalidPath, PortInUse, Internal }
```

`code` is machine-readable; `message` is for human display. There is **no** `#[serde(other)]` catch-all: an unknown code from a newer daemon fails closed as `IpcError::Decode`, which is the broad "version mismatch" signal until a handshake exists. `Internal` is the catch-all for daemon-side failures that don't fit a typed code - the guidance in the source is to *expand* the enum rather than overload `Internal`.

### `PhpUpdate`

```rust
pub struct PhpUpdate { pub version: PhpVersion, pub installed: String, pub latest: String }
```

One entry per installed minor that has a newer published patch (e.g. version `8.5`, installed `8.5.6`, latest `8.5.7`).

## Dump telemetry (`dump.rs`)

The Laravel ▸ Dumps feature ships per-request telemetry from the `yerd-php-ext` extension to the daemon's loopback dump server; the daemon buffers it and serves it to the GUI over IPC. `dump.rs` holds the shared data model. The daemon treats each event's payload as **opaque** JSON, so the extension's payload schema can evolve without daemon changes; the GUI renders it per category. Wire shapes are pinned in `tests/wire_stability.rs`.

| Type | Shape | Role |
| --- | --- | --- |
| `DumpCategory` | `snake_case`, `#[non_exhaustive]` enum: `Dump`, `Query`, `Job`, `View`, `Request`, `Log`, `Cache`, `Http` | One per GUI tab; the category of a captured frame. `Copy + Ord`. |
| `DumpEvent` | `{ id: u64, category: DumpCategory, ts_ms: u64, site: String, request_id: String, payload: serde_json::Value }` | One buffered event. `id` is assigned by the daemon (clients page with `since_id`); `payload` is the opaque category-specific JSON. |
| `DumpCounts` | `{ dumps, queries, jobs, views, requests, logs, cache, http: u32 }` | Per-category counts of events currently in the daemon's ring (capacity ~2000, so `u32` not `u64`). `increment(category)` bumps the matching field. `Copy + Eq`. |
| `DumpExtStatus` | `{ version: PhpVersion, present: bool }` | Whether a matching extension `.so` is present for an installed PHP version (a yerd-side "artifact present and wired" fact, not proof FPM `dlopen`'d it). `Eq`. |

::: warning `DumpEvent` is not `Eq` - and that ripples up to `Response`
`DumpEvent::payload` is a `serde_json::Value`, which can hold floats, so `DumpEvent` derives `PartialEq` but **not** `Eq`. Because a `DumpEvent` is reachable from `Response`, `Response` itself **no longer derives `Eq`** (only `PartialEq`). `Request`, which reaches no float-bearing type, still derives `PartialEq + Eq`. See the [No `f64` on the wire](#no-f64-on-the-wire-note) note below for what this changes.
:::

## Status & doctor payloads (`status.rs`)

These types ride inside `Response::Status`, `Response::Diagnoses`, `Response::DoctorFix`, and the service/database responses. The headline list:

`StatusReport`, `PortStatus`, `CaStatus`, `SiteCounts`, `PhpPoolStatus`, `PoolRunState`, `ServiceStatus`, `ServiceRunState`, `ServiceAvailability`, `DatabaseSummary`, `DomainShadow`, `Diagnosis`, `Severity`, `DiagnosisCode`, `FixReport`, `FixResult`.

::: info No `f64` on the status payload {#no-f64-on-the-wire-note}
`StatusReport` and everything it reaches stays float-free even though `Response` no longer derives `Eq` (the `DumpEvent::payload` `serde_json::Value` forced that to `PartialEq`-only - see [Dump telemetry](#dump-telemetry-dump-rs)). The system load average still crosses as integer hundredths - `StatusReport.load_avg` is `Option<[u32; 3]>` where each value is `load × 100`. The CLI renders it back to `x.xx`. The daemon does the conversion from the platform layer's `f64` reading at assembly time. Keeping the *status* payload integer-only preserves its `Eq`-based golden assertions; the only intentional float on `Response` is the opaque, daemon-uninterpreted dump payload.
:::

`StatusReport` follows the same additive-and-back-compatible discipline as the envelopes: optional probe fields (`port_redirect` and the cross-platform `foreign_web_listener`, plus macOS-only `resolver_backup`) are `#[serde(default, skip_serializing_if = "Option::is_none")]` so the wire stays additive and older daemons stay decodable; `daemon_version` is `#[serde(default)]` so a newer client decoding an older daemon's status gets `""` (rendered "unknown") instead of failing the whole decode. It also carries `shadows: Vec<DomainShadow>` (`#[serde(default, skip_serializing_if = "Vec::is_empty")]`, empty on a healthy config): one `DomainShadow { site, shadowed_by }` per site that lost a domain (its apex, or a hand-edited explicit domain) to another site when the router was built. `yerd doctor` surfaces these as `DomainShadowed` warnings.

`PoolRunState` is `Running` / `Stopped` / `Failed`; `ServiceRunState` is `Running` / `Stopped` / `Failed`; `Severity` is `Ok` / `Warn` / `Fail`; `DiagnosisCode` enumerates the doctor checks (`DaemonDown`, `PortFallback`, `ForeignWebListener`, `CaNotTrusted`, `ResolverNotInstalled`, `NoPhpInstalled`, `DefaultPhpNotInstalled`, `FpmPoolFailed`, `ServiceFailed`, `DomainShadowed`, `PhpUpdateAvailable`, `NoSites`, `ResolverBackupSaved`, `AllGood`). See [Diagnostics](../../guide/diagnostics) for what these mean to a user.

## Errors (`error.rs`)

Two layers, split on cloneability:

```rust
#[derive(Debug, Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum FrameError {
    TooLarge { size: u64, max: u64 },
    PayloadOverflowsLengthPrefix { size: u64 },
}
```

`FrameError` is the pure framing error and is `Clone + Eq`. `IpcError` is the top-level error:

```rust
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum IpcError {
    Encode(#[source] serde_json::Error),
    Decode(#[source] serde_json::Error),
    Frame(#[from] FrameError),
    UnexpectedEof { bytes: usize },
    Io { kind: std::io::ErrorKind },
}
```

`IpcError` is **not** `Clone`/`Eq` because `serde_json::Error` isn't. `UnexpectedEof` and `Io` are produced *only* by the `transport` helpers (the pure codec cannot synthesise them); `Io` carries `std::io::ErrorKind` (which is `Copy + Eq`) rather than the non-cloneable `std::io::Error`.

For callers that need a `Clone + Eq` value - notably Tauri commands, which serialize their `Result` error into the GUI - `IpcError::kind()` returns a pattern-matchable shadow:

```rust
pub fn kind(&self) -> IpcErrorKind;   // Clone + Eq mirror
pub fn message(&self) -> String;      // == Display, allocates once
```

`IpcErrorKind` mirrors every `IpcError` variant and additionally has a `FrameOther { description }` catch-all that carries the `Display` rendering of any *future* `FrameError` variant added before its paired `IpcErrorKind` variant lands. A unit test, `frame_error_to_kind_is_exhaustive`, matches exhaustively on the in-crate `FrameError` and asserts each maps to a concrete (non-`FrameOther`) kind - so the catch-all is unreachable today and the pairing can't silently drift.

## The transport layer (`transport.rs`, feature-gated)

Behind `--features transport`, three helpers are generic over `tokio::io::AsyncRead` / `AsyncWrite` so the daemon and CLI share one read/write path while socket and named-pipe binding stays in the binaries:

```rust
pub async fn write_message<W, T>(writer: &mut W, value: &T, max: usize) -> Result<(), IpcError>
where W: AsyncWrite + Unpin, T: Serialize;

pub async fn read_frame<R>(reader: &mut R, decoder: &mut FrameDecoder)
    -> Result<Option<Vec<u8>>, IpcError>
where R: AsyncRead + Unpin;

pub async fn read_message<R, T>(reader: &mut R, decoder: &mut FrameDecoder)
    -> Result<Option<T>, IpcError>
where R: AsyncRead + Unpin, T: DeserializeOwned;
```

`write_message` encodes → frames → `write_all`. `read_frame` loops: drain a ready frame from the decoder, else `read` a 4 KiB chunk and feed it in. Its three EOF-adjacent outcomes are precise:

* `Ok(Some(payload))` - a full frame.
* `Ok(None)` - clean EOF with an empty decoder buffer.
* `Err(IpcError::UnexpectedEof { bytes })` - EOF arrived mid-frame (`bytes` were buffered).
* `Err(IpcError::Frame(_))` - declared length exceeded the cap; the decoder is now poisoned.

`read_message` is `read_frame` followed by `decode_message`. The caller can therefore inspect the raw `type` tag from `read_frame` before committing to a full decode. The private `io_to_ipc` helper preserves only the OS error *category* (`ErrorKind`), keeping `IpcErrorKind` cloneable; clean EOF (a zero-byte read) is handled separately so it never masquerades as an `Io` error.

## Wire-stability policy

The `Request` / `Response` / `ErrorCode` JSON shapes are a **published contract**. Three mechanisms enforce it, and breaking any of them fails CI before a divergent format reaches a client:

1. **Add additively, never rename.** `#[non_exhaustive]` allows new variants without a major bump. Renaming a variant, field, or error code is forbidden.
2. **No per-field `#[serde(rename = "...")]`.** Casing is `#[serde(rename_all = "snake_case")]` only. A grep gate fails on any per-field rename in `crates/yerd-ipc/src/`. The reason is subtle: pairing the no-rename rule with the byte-pin tests means a Rust variant rename trips *both* the wire pin (changed JSON) and the in-crate exhaustive match (compile error) - a stray `#[serde(rename = ...)]` could otherwise mask a Rust rename while silently breaking clients.
3. **Byte-exact pinning.** `tests/wire_stability.rs` asserts the literal JSON for every variant. Inline `variant_name_pinning` modules in `request.rs` / `response.rs` carry an exhaustive `match` over every variant - these live *inside* the crate because `#[non_exhaustive]` blocks exhaustive matching from an integration test across the crate boundary.

`PROTOCOL_VERSION` is `1` and is reserved: there is no `Hello`/`Welcome` handshake yet, so a newer client against an older daemon surfaces an unknown `type` tag as `IpcError::Decode`. Don't bump the version without landing the paired handshake variants first.

### Envelope-permissive, payload-strict

A deliberate asymmetry, asserted in `tests/roundtrip.rs`:

* The **outer envelope** (`Request` / `Response`) **accepts** unknown JSON fields, so additive field changes stay backward-compatible. `{"type":"ping","__extra":42}` decodes as `Request::Ping`.
* The **inner `Site`** payload is **strict** (`yerd_core::Site` uses `deny_unknown_fields`). An unknown field on a `Site` inside `Response::Sites` is rejected.

Unknown `type` tags and unknown `ErrorCode` values both fail closed as `IpcError::Decode` - there is no silent-downgrade catch-all.

## Tests and invariants

| File | Covers |
| --- | --- |
| `tests/frame_codec.rs` | partial header/body reads, pipelined frames, oversized rejection, decoder poisoning, exact-max boundary, empty payload (`[0,0,0,0]`), slow-loris byte-at-a-time |
| `tests/wire_stability.rs` | byte-exact JSON for every `Request`/`Response`/`ErrorCode`/`DiagnosisCode`/`Severity`/`PoolRunState` variant, plus back-compat (legacy `Info` without ports, `skip_serializing_if` field omission) |
| `tests/roundtrip.rs` | `encode_message` ∘ `decode_message` identity; negative tests for unknown tag, missing required field, unknown envelope field (accepted), unknown `Site` field (rejected), unknown `ErrorCode` (rejected) |
| inline `src/*.rs` | `check_payload_length` edge cases, `IpcError::kind` exhaustiveness, `Display` parity, `PROTOCOL_VERSION` pin, variant-name pinning, async transport over an in-memory `duplex` |

The async transport tests (`transport.rs`) run on an in-memory `tokio::io::duplex`, covering a full round-trip, a frame split across two writes with a yield between, clean EOF, mid-frame EOF, a write to a closed reader surfacing as `IpcError::Io`, and partial writes over a tiny buffer.

::: details Local verification gate

```sh
cargo build -p yerd-ipc
cargo build -p yerd-ipc --features transport
cargo test  -p yerd-ipc
cargo test  -p yerd-ipc --features transport
cargo fmt   --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
# fail on any per-field serde rename in this crate's src/
! grep -REn '#\[serde\([^)]*[^_[:alnum:]]?rename[[:space:]]*=' crates/yerd-ipc/src/
```

:::

## Related

* [IPC Protocol](../ipc-protocol) - the full protocol deep-dive (connection lifecycle, choreography, version skew).
* [yerd-core](./yerd-core) - the `Site`, `PhpVersion`, and `SiteKind` types re-exported through `yerd_ipc::types`.
* [yerdd (daemon)](../binaries/yerdd) and [yerd (CLI)](../binaries/yerd) - the `transport`-feature consumers that bind the actual sockets.
* [Crates Overview](../crates) - where this crate sits in the workspace.

---

---
url: 'https://yerd.app/developer/crates/yerd-config.md'
---
# yerd-config

`yerd-config` owns the on-disk configuration for Yerd: a single schema-versioned
TOML file. It is responsible for exactly four verbs - **parse**, **validate**,
**serialise**, and **migrate** - plus two thin I/O leaves that read and write
that file atomically. Nothing more.

The crate is built around a strict purity boundary. Everything except
[`Config::load`](#config-load) and [`Config::save`](#config-save) is a pure
function over strings and in-memory values: no filesystem, no network, no
environment reads. That makes the parse / validate / serialise pipeline trivially
testable with string inputs and keeps the side-effecting surface down to two
functions.

For the user-facing field reference (what each key means, defaults, examples),
see [Configuration Reference](../../reference/configuration). This page is the
contributor-facing tour of the source.

::: info Crate boundaries
`yerd-config` does **not** decide *where* the config lives, and it does **not**
scan the filesystem for sites. Path discovery is the caller's job (the daemon);
site scanning lives elsewhere. See [What it must not do](#what-it-must-not-do).
:::

## Dependencies

From `Cargo.toml`:

```toml
[dependencies]
yerd-core = { path = "../yerd-core" }
serde     = { workspace = true }
toml      = { workspace = true }
thiserror = { workspace = true }
tempfile  = { workspace = true }
```

* `yerd-core` supplies the validated domain types (`Tld`, `PhpVersion`, `Site`,
  `SiteKind`) and the `php_settings` validator. Per-field invariants are
  enforced by `yerd-core`, not re-implemented here.
* `toml` + `serde` drive (de)serialisation through crate-internal wire mirrors.
* `tempfile` provides `NamedTempFile` for the atomic write-temp-then-rename save.
* `thiserror` derives the [`ConfigError`](#errors) enum.

The crate sets `#![forbid(unsafe_code)]`.

## Module map

```
src/
  lib.rs        Re-exports + CURRENT_VERSION; the purity-boundary doc.
  schema.rs     Public types (Config, Ports, PhpSection, ParkedSection,
                SiteOverride, ServicesSection, MailSection, DumpsSection)
                + Config's public methods.
  parse.rs      Wire mirrors, TOML deserialisation, TryFrom<Wire>, validate().
  serialize.rs  Borrowed wire mirrors + to_toml().
  migrate.rs    Schema-version reading and forward-migration step walker.
  io.rs         The only impure code: load() and save().
  error.rs      ConfigError + ValidateErrorReason + MigrationErrorReason.
```

The two halves are clearly separated: `parse.rs` / `serialize.rs` / `migrate.rs`
/ `schema.rs` are the pure core; `io.rs` is the thin atomic leaf.

## The public API

All public surface hangs off `Config` plus the re-exported helper types. From
`lib.rs`:

```rust
pub use error::{ConfigError, MigrationErrorReason, ValidateErrorReason};
pub use schema::{
    Config, DomainDelta, DomainsSection, DumpsSection, GroupsSection, MailSection, ParkedSection,
    PhpSection, Ports, ServiceInstance, ServicesSection, SiteOverride, TunnelSection,
    DEFAULT_DNS_PORT, DEFAULT_DUMP_PORT, DEFAULT_MAIL_PORT, RESERVED_GROUP_NAME,
};

pub const CURRENT_VERSION: u32 = 11;
```

`Config` exposes exactly four pure methods and two I/O methods:

```rust
impl Config {
    pub fn from_toml(s: &str) -> Result<Self, ConfigError>;
    pub fn to_toml(&self) -> Result<String, ConfigError>;
    pub fn validate(&self) -> Result<(), ConfigError>;

    pub fn load(path: &std::path::Path) -> Result<Self, ConfigError>;
    pub fn save(&self, path: &std::path::Path) -> Result<(), ConfigError>;
}
```

| Method        | Purity | Role |
|---------------|--------|------|
| `from_toml`   | pure   | parse string → version routing → wire deser → `TryFrom<Wire>` → `validate` |
| `to_toml`     | pure   | serialise to a TOML string (always writes `version = CURRENT_VERSION`) |
| `validate`    | pure   | cross-field + container-content invariants |
| `load`        | impure | read file, then `from_toml` |
| `save`        | impure | `to_toml`, then atomic write-temp-then-rename |

## The schema types

`Config` is the top-level on-disk shape:

```rust
pub struct Config {
    pub(crate) version: u32,
    pub tld: Tld,
    pub dns_port: u16,
    pub ports: Ports,
    pub php: PhpSection,
    pub parked: ParkedSection,
    pub linked: Vec<Site>,
    pub overrides: BTreeMap<String, SiteOverride>,
    pub services: ServicesSection,
    pub mail: MailSection,
    pub dumps: DumpsSection,
    pub domains: DomainsSection,
    // ... plus the optional tunnel / groups / update_channel state.
}
```

`DomainsSection` (schema v11) carries per-site domain deltas, split by site class
to mirror `overrides`: `linked: BTreeMap<String, DomainDelta>` keyed by site name
and `parked: BTreeMap<String, DomainDelta>` keyed by document-root. Each
`DomainDelta { added, suppressed, primary }` layers over a site's default apex.
The `Domain` values themselves live in `yerd-core`; this crate only persists them
(via wire mirrors, since `Domain` is deliberately non-serde). `Config::validate`
checks the structural invariants (no duplicate `added`; `added`/`suppressed`
disjoint; `primary` not a wildcard); name/TLD/uniqueness rules are the daemon's.

Notable design decisions, all grounded in the source:

* **`version` is private.** Every `Config` produced by this build carries
  `version == CURRENT_VERSION`, so a public accessor would only ever return that
  constant. Callers read [`CURRENT_VERSION`](#schema-versioning) directly.
* **The public types implement neither `Serialize` nor `Deserialize`.**
  Round-trip goes through crate-internal *wire mirrors* (see
  [below](#wire-mirrors)). This keeps the public surface free of an accidental
  serde contract that downstream consumers might pin to.
* **`Ports`** carries `http` / `https` `u16`s. Constructors `Ports::well_known()`
  (`80 / 443`, the `Default`) and `Ports::unprivileged()` (`8080 / 8443`) are
  `const fn`.
* **`PhpSection`** holds the default `PhpVersion` (defaults to `8.3`) and a
  `BTreeMap<String, String>` of global FPM ini settings, validated against
  `yerd_core::php_settings`.
* **`ParkedSection::paths`** is a `BTreeSet<String>` - *not* `BTreeSet<PathBuf>`.
  This is deliberate: the config layer does not own platform path semantics, and
  `PathBuf::serialize` is lossy for non-UTF-8 paths on Windows. Paths are stored
  byte-exact and never canonicalised, so `"/srv/foo"` and `"/srv/foo/"` are
  distinct entries. The `BTreeSet` gives stable lexicographic order and makes
  duplicates structurally impossible.
* **`overrides`** is a `BTreeMap` keyed by a parked site's `document_root` string,
  stored byte-exact and never canonicalised. A parked site is otherwise derived
  purely from a directory listing, so it has no persistent record to hold a pinned
  PHP version, HTTPS flag, or web root; the daemon records the override here and
  re-applies it during the scan, leaving the site parked. `SiteOverride` is
  all-`Option` (`php`, `secure`, `web_root`, `wp_auto_login`, `wp_auto_login_user`,
  added in schema v10) so `None` means "inherit" (or, for `web_root`,
  "auto-detect on every scan") and future per-site settings slot in additively
  without a wire break. `web_root` is the pinned served subdirectory relative to
  the document root - the parked-site analogue of a linked `Site`'s
  `web_subpath`. `wp_auto_login`/`wp_auto_login_user` (one-click `WordPress`
  admin login, opt-in per site) are the same fields a linked `Site` carries
  directly, mirrored here for a parked site's override record.
* **`ServicesSection::instances`** is a `BTreeMap<String, ServiceInstance>` keyed
  by the service id (since the v2→v3 migration; v0–v2 stored a flat
  `enabled = [...]` array of ids). Each `ServiceInstance` carries
  `version: Option<String>`, `port: Option<u16>`, and `enabled: bool`. The keys
  are stringly-typed here on purpose: the canonical typed `Service` enum lives
  downstream in [`yerd-services`](./yerd-services), and a string key allows
  forward-compatibility with experimental services without a `yerd-config`
  release. Keys are validated against the private `KNOWN_SERVICES` const in
  `parse.rs`: `["mysql", "mariadb", "meilisearch", "postgres", "redis"]`.
* **`MailSection`** (the `[mail]` table, added in schema v4) configures the
  built-in mail-capture SMTP sink. It carries `enabled: bool` (**default
  `true`**) and `port: u16` (the loopback port, default `DEFAULT_MAIL_PORT` =
  `2525`). When enabled the daemon binds the port on `127.0.0.1`; a busy port is
  non-fatal (the daemon logs and runs with capture not listening). The struct is
  `Copy`.
* **`DumpsSection`** (the `[dumps]` table, added in schema v5) configures the
  Laravel ▸ Dumps telemetry feature. Fields: `enabled: bool` (**default
  `false`** - the "antenna"), `port: u16` (loopback port the dump server listens
  on and the PHP extension connects to, default `DEFAULT_DUMP_PORT` = `2304`),
  `persist: bool` (default `false`: the buffer is cleared each new request so the
  viewer shows only the latest request; `true` accumulates across requests), and
  `features: BTreeMap<String, bool>` (per-feature capture toggles keyed by
  feature name - `dumps`/`queries`/`jobs`/`views`/`requests`/`logs`/`cache` - an
  absent key meaning "on"). `BTreeMap` for stable serialisation order.

`DEFAULT_DNS_PORT` is `1053`. A fixed (non-ephemeral) port keeps the resolver
configuration installed by `yerd elevate resolver` valid across daemon restarts.
`DEFAULT_MAIL_PORT` is `2525` and `DEFAULT_DUMP_PORT` is `2304`; both are fixed
for the same reason (a sender / the PHP extension connects to a known port).

## The parse pipeline

`Config::from_toml` delegates to `parse::parse_toml`, which is the heart of the
read path:

```rust
pub(crate) fn parse_toml(s: &str) -> Result<Config, ConfigError> {
    let mut value: toml::Value = toml::from_str(s)?;
    let found = crate::migrate::read_version(&value)?;
    if found > crate::CURRENT_VERSION {
        return Err(ConfigError::UnsupportedVersion {
            found,
            current: crate::CURRENT_VERSION,
        });
    }
    if found < crate::CURRENT_VERSION {
        crate::migrate::up(&mut value, found)?;
    }
    let wire: Wire = value.try_into()?;
    let cfg = Config::try_from(wire)?;
    validate(&cfg)?;
    Ok(cfg)
}
```

The stages, in order:

1. **Lex/parse** to a generic `toml::Value` (syntax errors → `ConfigError::Parse`).
2. **Read the version** (`migrate::read_version`). A missing or non-integer
   `version` key is a hard error.
3. **Version routing.** A future version (`found > CURRENT_VERSION`) is rejected
   with `UnsupportedVersion`. An older version runs forward migrations.
4. **Wire deserialisation** into the raw `Wire` mirror.
5. **`TryFrom<Wire>`** converts raw strings into validated `yerd-core` types,
   surfacing per-field failures as `ConfigError::Core`.
6. **`validate`** runs cross-field invariants.

### Wire mirrors

The `Wire` struct is the raw shape `serde` deserialises into. It is
`#[serde(deny_unknown_fields)]` - at every level - so a typo'd key is a hard
parse error rather than a silently dropped field:

```rust
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
    version: u32,
    #[serde(default = "default_tld_str")]
    tld: String,
    #[serde(default = "default_dns_port")]
    dns_port: u16,
    #[serde(default)]
    ports: PortsWire,
    // …php, parked, linked, overrides, services
}
```

The mirror is **raw-typed**: `tld`, `php.default`, and override/site `php` are
held as `String`, not as `Tld` / `PhpVersion`. This is the key design choice in
`parse.rs`. If the wire structs deserialised directly into the domain types,
`yerd-core`'s validation failures would be folded into `ConfigError::Parse` via
`serde::de::Error::custom`. By keeping the fields raw and converting in
`TryFrom<Wire>`, a bad domain value surfaces as the precise
`ConfigError::Core(..)` carrying the underlying `yerd_core::CoreError` - e.g. a
`PhpVersion` minor out of range, or a TLD containing whitespace.

`#[serde(default)]` on the section fields means an omitted `[parked]`,
`[services]`, or `[[overrides]]` block parses as empty. This matters for
forward-compatibility: a v1 file written before `overrides` existed still parses
under `deny_unknown_fields` because the field defaults rather than being required.
The same applies to the v2 additions: `SiteWire.web_subpath` and
`OverrideWire.web_root` are `#[serde(default)]`, so a migrated v1 file (which has
neither key) parses cleanly with both defaulting to "none / auto-detect".

### `TryFrom<Wire>` → Config

`TryFrom<Wire> for Config` does the raw → typed conversion:

* A post-migration sanity check asserts `wire.version == CURRENT_VERSION`; a
  `STEPS` misconfiguration that failed to bump the version surfaces here as
  `UnsupportedVersion`.
* `Tld::new`, `PhpVersion::from_str`, and `Site::linked` / `Site::parked` run the
  `yerd-core` validators. Any failure short-circuits with `ConfigError::Core`.
* The `[[overrides]]` array is folded into the path-keyed `BTreeMap`. A duplicate
  `path` (only reachable by hand-editing) is last-wins via `BTreeMap::insert`.

::: warning Silent TLD normalisation
`yerd_core::Tld::new` strips one trailing dot. So `tld = "test."` parses as
`Tld("test")`, and the next `save` emits `tld = "test"`. This is a known,
intentional silent normalisation - pinned by
`parse_strips_trailing_dot_from_tld_silently`.
:::

## Validation

`validate` enforces invariants the type system and `BTreeSet` storage cannot.
Per-field invariants on typed fields (TLD, `PhpVersion`, site name) are already
enforced during `Wire → Config`; `validate` covers cross-field and
container-content checks. The order is fixed and pinned by a test
(`validate_returns_first_failure_in_documented_order`) so the *first* failure is
deterministic:

| # | Check | `ValidateErrorReason` |
|---|-------|-----------------------|
| 1 | `ports.http == 0` | `HttpPortZero` |
| 2 | `ports.https == 0` | `HttpsPortZero` |
| 3 | `ports.http == ports.https` | `HttpHttpsPortsEqual` |
| 4 | `mail.port == 0` | `MailPortZero` |
| 5 | `dumps.port == 0` | `DumpsPortZero` |
| 6 | two linked sites share a `name()` | `DuplicateLinkedSite` |
| 7 | a `parked.paths` entry is empty | `ParkedPathEmpty` |
| 8 | an `overrides` key is empty | `OverridePathEmpty` |
| 9 | a linked `web_subpath` or override `web_root` is absolute or contains `..` | `WebRootEscapes` |
| 10 | a `services.instances` key is not in `KNOWN_SERVICES` | `UnknownService` |
| 11 | a `php.settings` entry fails `php_settings::validate_value` | `InvalidPhpSetting` |

The `mail.port` / `dumps.port` zero-checks (added with schema v4 / v5) sit
alongside the HTTP/HTTPS port checks: both ports are bound on `127.0.0.1` when
their feature is enabled, so a zero (ephemeral) port is meaningless - a sender or
the PHP extension could never find it.

The `php.settings` check runs last (it is the newest invariant). It rejects both
unsupported directives (e.g. `allow_url_fopen`) and values that fail the shape /
security validation (e.g. `"256M; evil"`). The `WebRootEscapes` check (added with
schema v2) is the load-time containment guarantee for `web_subpath` / `web_root`:
a plain relative path is allowed, but an absolute path or one with a `..`/root
component is rejected so a hand-edited value can never make `Site::served_root`
escape the project directory.

## Schema versioning and migration

Every on-disk file **MUST** carry a top-level `version = N` key. A missing key is
a hard error (`ConfigError::Migration { MissingVersion }`), not a default. The
version is the single trigger for forward migrations.

```rust
/// The on-disk schema version this crate writes.
pub const CURRENT_VERSION: u32 = 11;
```

`CURRENT_VERSION` is **decoupled** from `yerd_ipc::PROTOCOL_VERSION`: the on-disk
TOML schema and the IPC wire protocol evolve independently. It is bumped together
with a new entry in `migrate::STEPS`.

`migrate.rs` holds the steps, indexed so that **`STEPS[N]` walks `vN → v(N+1)`**

* matching `migrate::up`, which indexes `STEPS[current]` (the version being
  migrated *from*). At v11 there are eleven (`STEPS.len() == CURRENT_VERSION`, pinned
  by `steps_cover_every_version_below_current`):

```rust
pub(crate) type MigrationStep = fn(&mut Value) -> Result<(), ConfigError>;

/// STEPS[N] walks vN → v(N+1); a v1 file is migrated by STEPS[1].
pub(crate) const STEPS: &[MigrationStep] = &[
    migrate_v0_to_v1,
    migrate_v1_to_v2,
    migrate_v2_to_v3,
    migrate_v3_to_v4,
    migrate_v4_to_v5,
    migrate_v5_to_v6,
    migrate_v6_to_v7,
    migrate_v7_to_v8,
    migrate_v8_to_v9,
    migrate_v9_to_v10,
    migrate_v10_to_v11,
];
```

`STEPS[0]` (v0→v1) is reachable only via a hand-crafted `version = 0` file - v0
was never written to disk - but it must exist so the later indices line up.
`v0→v1` and `v1→v2` are bare version bumps (v2 only **added** the optional
`web_subpath` / `web_root` keys, which default when absent). `v2→v3` is the only
**structural** step: it rewrites the old flat `services.enabled = [...]` array of
ids into per-service `[services.<id>]` tables (each previously-enabled id becomes
an `enabled = true` instance). `v3→v4` through `v9→v10` are again bare version
bumps, each adding an optional section that defaults when absent: `[mail]` (v4),
`[dumps]` (v5), the `update_channel` scalar (v6), the `[ports]` fallback keys
(v7), `[tunnel]` (v8), `[groups]` (v9), and the `wp_auto_login`/`wp_auto_login_user`
keys inside `[[linked]]` and `[[overrides]]` (v10). Each bump still exists so an
*older* binary rejects a file that uses the newer table/keys cleanly as
`UnsupportedVersion` rather than failing on an unknown key under
`deny_unknown_fields`.

Each step rewrites the parsed `toml::Value` in place and is responsible for
leaving the `version` key set to `N + 1`. A step need not produce a *valid*
config - `parse_toml` unconditionally runs wire deserialisation and `validate`
after the final step, so the validator is the ultimate gate. `migrate::up` walks
`STEPS` from the found version up to `CURRENT_VERSION`; a missing step yields
`MigrationErrorReason::MissingStep { from }` (a developer error, not user input).

`read_version` defends against a non-table root (`MissingVersion`), a
non-integer or out-of-`u32`-range version (`NonIntegerVersion`), and a negative
version (also `NonIntegerVersion`).

::: tip Adding a migration
Bump `CURRENT_VERSION`, append a `MigrationStep` to `STEPS` that mutates the
`toml::Value` and sets `version = N + 1`, and never silently drop fields. The
post-migration `wire.version == CURRENT_VERSION` assertion and `validate` catch a
step that forgets to bump the version.
:::

## Serialisation and byte shape

`to_toml` routes through *borrowed* wire mirrors (`WireSer<'a>` and friends) that
hold references into the public `Config`, then calls `toml::to_string_pretty`.
The output shape is deliberate and pinned by `tests/toml_byte_shape.rs`:

* **`version` is always written first.** `WireSer.version` is the first struct
  field, and TOML emits scalars before sub-tables. The output always starts with
  `version = 5\n`.
* **Scalars precede their sibling tables.** `dns_port` is emitted as a top-level
  scalar before any `[section]`; `php.default` precedes the `[php.settings]`
  sub-table.
* **Empty optionals are omitted.** Empty `overrides` emits no `[[overrides]]`
  table; empty `php.settings` emits no `[php.settings]` sub-table; per-override
  `php` / `secure` are skipped individually when `None`.
* **Empty sets still emit `[]`.** `parked.paths` serialises as `paths = []` rather
  than being dropped; an empty `services.instances` emits no `[services.*]` tables.
* **Deterministic ordering.** `BTreeSet` / `BTreeMap` give lexicographic output,
  so `parked.paths` is sorted, `[services.<id>]` tables emit in id order, and
  `[[overrides]]` order is stable.
* **`services` wire shape** is one `[services.<id>]` table per engine, each with
  `version` / `port` (omitted when unset) and `enabled`.

A representative populated document round-trips cleanly:

```toml
version = 5
tld = "test"
dns_port = 1053

[ports]
http = 8080
https = 8443

[php]
default = "8.2"

[parked]
paths = ["docroot-a", "docroot-b"]

[[linked]]
name = "api"
document_root = "docroot"
php = "8.3"
secure = true
kind = "linked"

[[overrides]]
path = "docroot-a/blog"
php = "8.4"
secure = true

[services.mysql]
port = 3306
enabled = true

[services.redis]
version = "8"
port = 6379
enabled = true
```

(`web_subpath` on `[[linked]]` and `web_root` on `[[overrides]]` are omitted when
empty, so they don't appear in a root-served example like this one.)

## Atomic I/O (`io.rs`)

The two impure functions are intentionally minimal. `load` reads the file and
hands the string to `from_toml`, wrapping any I/O failure as `ConfigError::Io`
carrying the caller-supplied `PathBuf`. `save` is a write-temp-then-rename:

```rust
pub(crate) fn save(cfg: &Config, path: &Path) -> Result<(), ConfigError> {
    let serialised = cfg.to_toml()?;

    let parent = path
        .parent()
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or_else(|| Path::new("."));

    fs::create_dir_all(parent)?;                 // (errors mapped to ConfigError::Io)
    let tmp = NamedTempFile::new_in(parent)?;    // sibling temp in the same dir
    fs::write(tmp.path(), serialised.as_bytes())?;
    tmp.persist(path)?;                          // atomic rename onto destination
    Ok(())
}
```

Properties worth knowing as a contributor:

* **Atomicity.** The temp file is created *in the destination's parent dir*, so
  `persist` is a same-filesystem `rename(2)` on Unix - atomic. On Windows it is
  `MoveFileExW` with `MOVEFILE_REPLACE_EXISTING`, atomic for the rename itself but
  able to fail with `ERROR_SHARING_VIOLATION` if another process holds an
  exclusive handle to the destination. The daemon must not hold a write handle to
  the config file between saves.
* **No orphan temp files.** On `persist` failure the original `NamedTempFile` is
  dropped, which deletes the temp file.
* **Unix permissions.** `NamedTempFile` creates the file mode `0600`
  (owner read/write only); that propagates to the destination. Intentional - the
  daemon is the only intended writer.
* **No `fsync`.** Neither the file nor the parent directory is fsynced. The
  portability cost outweighs the durability gain for a developer-only config
  file; loss under sudden power loss is acceptable.
* **Parent-less paths.** `path.parent()` is `None` for a bare filename and `""`
  for some inputs; both are treated as the current working directory. So
  `Path::new("config.toml")` saves relative to the process CWD.
* **Parent dirs are created but not cleaned up.** `fs::create_dir_all` may create
  intermediate directories; they are not removed on a later failure.

## Errors

`ConfigError` is the single error type returned by every fallible public API.
It is `#[non_exhaustive]` (as are the reason sub-enums), so new variants are
semver-compatible. It is **not** `Clone`/`Eq` because it wraps `toml::de::Error`,
`toml::ser::Error`, and `std::io::Error` - and it stores the full `io::Error`
plus a `PathBuf` because diagnostic detail matters for `load`/`save` debugging.

| Variant | Meaning |
|---------|---------|
| `Parse(toml::de::Error)` | TOML failed to lex/parse syntactically |
| `Serialize(toml::ser::Error)` | serialisation failed (always a bug) |
| `Validate { reason: ValidateErrorReason }` | a cross-field / container invariant failed |
| `Core(yerd_core::CoreError)` | a domain value (TLD, `PhpVersion`, `Site`) was rejected during `TryFrom<Wire>` |
| `UnsupportedVersion { found, current }` | on-disk version incompatible (usually `found > current`) |
| `Migration { reason: MigrationErrorReason }` | version reading or forward migration failed |
| `Io { path, source }` | I/O failed in `load` / `save` |

`ValidateErrorReason` enumerates the eleven checks in the
[validation table](#validation). `MigrationErrorReason` is `MissingVersion`,
`NonIntegerVersion`, or `MissingStep { from }`.

## Key tests and invariants

The crate has a coverage gate (`cargo llvm-cov … --fail-under-lines 80`, with
`tests/`, `lib.rs`, and `yerd-core` excluded). Beyond unit tests in each module,
the integration tests pin the durable contracts:

* **`tests/roundtrip.rs`** - `default` and a fully populated config survive
  `to_toml` → `from_toml`, and the populated config passes `validate`.
* **`tests/toml_byte_shape.rs`** - structural goldens on the emitted TOML: the
  `version = 5` first line, scalar-before-table ordering, omitted empty optional
  tables, `[]` for empty sets, lexicographic ordering, and the
  per-id `[services.<id>]` table shape. These survive
  `to_string_pretty`'s line-break and table-ordering choices by asserting on
  substrings and re-parsed `toml::Value`s rather than exact bytes.
* **`tests/io.rs`** - `save` → `load` round-trip, parent-dir creation, overwrite
  semantics, and that a missing file / invalid TOML surface as `Io` / `Parse`
  with the caller-supplied path.
* **`tests/io_parentless.rs`** - isolated single-test binary (it mutates the
  process CWD, which would race peer tests) confirming a parent-less path saves
  relative to the CWD.

## What it must NOT do

This crate is deliberately narrow. It does **not**:

* **Decide where the config lives.** There is no path-discovery, no
  `dirs`/`directories` dependency, no env or XDG logic. The caller (the daemon)
  passes an absolute path into `load` / `save`. See the
  [daemon page](../binaries/yerdd).
* **Scan the filesystem for sites.** Parked-site discovery is a directory scan
  performed by the daemon. `yerd-config` only persists the *parked paths* and the
  *per-path overrides* derived from that scan - it never walks directories
  itself. The only filesystem access in the whole crate is the temp file and
  rename inside `io.rs`.
* **Re-validate domain types.** TLD, `PhpVersion`, and `Site` invariants belong
  to `yerd-core`; `yerd-config` calls those validators and propagates their
  errors as `ConfigError::Core`. See [yerd-core](./yerd-core).
* **Canonicalise paths.** Parked paths and override keys are stored byte-exact.
  Callers wanting equality semantics must normalise before insertion.

## See also

* [Config Schema History](../config-schema-history) - the version-by-version changelog, including exactly how to hand-edit a file down to an older schema version.
* [Configuration Reference](../../reference/configuration) - user-facing field guide
* [yerd-core](./yerd-core) - the domain types this crate validates against
* [The Daemon](../../guide/daemon) - the primary reader/writer of the config
* [Crates Overview](../crates)
* Source: [`crates/yerd-config`](https://github.com/forjedio/yerd/tree/main/crates/yerd-config)

---

---
url: 'https://yerd.app/developer/crates/yerd-tls.md'
---
# yerd-tls

`yerd-tls` is the pure-Rust certificate engine behind Yerd's local HTTPS. It generates a self-signed local **Certificate Authority**, reloads that CA from PEM, computes its SHA-256 fingerprint, and issues per-site **leaf certificates** signed by the CA. It is built on [rcgen](https://github.com/rustls/rcgen) (backed by `ring`) - **no OpenSSL, no shelling out**.

The defining constraint is purity: the crate does **no file or socket I/O, never reads the clock, and never reads the environment**. Callers pass timestamps in via [`Validity`](#validity) and pass/receive certificate material as PEM strings. Persistence lives in the daemon (`yerdd`'s cert store); trust-store installation lives in `yerd-platform` and `yerd-helper`. This crate just turns inputs into bytes.

For the end-to-end HTTPS story - how the CA is installed into system trust stores, how leaves are minted per site, and what users actually run - see [HTTPS & Certificates](../../guide/https). This page is the contributor-facing reference for the crate itself.

::: info Dependency-graph position
`yerd-tls` is a **leaf in the workspace dependency graph**: it has zero internal (`yerd-*`) dependencies. Its only crates are `rcgen`, `pem`, `rustls-pki-types`, `sha2`, `thiserror`, `time`, and `x509-parser`. It is consumed by `yerdd` (the daemon's cert store) and indirectly underpins the `yerd-proxy` HTTPS path.
:::

## Module map

```
crates/yerd-tls/
├── src/
│   ├── lib.rs       - crate root; re-exports the public surface; #![forbid(unsafe_code)]
│   ├── ca.rs        - CertAuthority: generate / from_pem / fingerprint / issue_leaf
│   ├── leaf.rs      - LeafCert: cert_pem / key_pem / chain_pem
│   ├── params.rs    - rcgen CertificateParams builders for CA and leaf (crate-private)
│   ├── validity.rs  - Validity: clock-free NotBefore/NotAfter window
│   └── error.rs     - TlsError + typed *Reason sub-enums; rcgen_detail() mapping
└── tests/           - integration tests (chain, fingerprint, sans, validity, roundtrip, …)
```

The public surface re-exported from `lib.rs` is small:

```rust
pub use ca::CertAuthority;
pub use error::{GenerateErrorReason, ParseErrorReason, TlsError, ValidityErrorReason};
pub use leaf::LeafCert;
pub use validity::Validity;
```

A compile-time test (`re_exports_compile`) asserts all of these stay nameable through the crate root.

## The `CertAuthority` API

`CertAuthority` holds the CA's certificate and key material. Its layout deliberately duplicates a few representations:

```rust
#[non_exhaustive]
pub struct CertAuthority {
    cert_pem: String,   // canonical PEM wire form
    cert_der: Vec<u8>,  // canonical DER wire form (what gets fingerprinted)
    key_pem: String,    // canonical PEM key form
    key_pair: KeyPair,  // live rcgen signing context for issue_leaf
}
```

The duplication is intentional: `cert_pem`/`cert_der` are the canonical wire forms returned by accessors, while `key_pair` is the live signing context used by `issue_leaf`. After `from_pem`, the cached strings and bytes are the caller's input *verbatim*, so the PEM accessors and the fingerprint round-trip losslessly.

### `generate`

```rust
pub fn generate(common_name: &str, validity: Validity) -> Result<Self, TlsError>
```

Generates a fresh CA. The signing algorithm is **explicitly pinned to ECDSA P-256 / SHA-256**:

```rust
fn key_alg() -> &'static rcgen::SignatureAlgorithm {
    &rcgen::PKCS_ECDSA_P256_SHA256
}
```

Pinning the algorithm guards against rcgen changing the default of `KeyPair::generate()`. (`PKCS_ECDSA_P256_SHA256` is a `static`, not a `const`, so the code takes a reference at the call site.) `generate` calls `params::ca_params`, generates the key pair, self-signs, then caches `cert.pem()`, `cert.der()`, and `key_pair.serialize_pem()`.

### `from_pem`

```rust
pub fn from_pem(cert_pem: &str, key_pem: &str) -> Result<Self, TlsError>
```

Reloads a previously-persisted CA. It runs a layered validation gauntlet - each layer maps to a precise [`ParseErrorReason`](#error-model):

1. **Cert PEM tag check** - decode with the `pem` crate and require the tag `"CERTIFICATE"`. Failure → `InvalidCertificatePem`.
2. **Key PEM tag check** - decode and require the tag `"PRIVATE KEY"`. This is a *defensive* layer: rcgen's `from_pem` does not enforce tags itself. Failure → `InvalidPrivateKeyPem`.
3. **Key parse** - `KeyPair::from_pem`. Failure (e.g. a non-PKCS#8 body) → `InvalidPrivateKeyPem`.
4. **SPKI byte-comparison** - parse the cert DER with `x509-parser`, extract `tbs_certificate.subject_pki.raw`, and byte-compare it against `key_pair.public_key_der()`. Mismatch → `KeyDoesNotMatchCertificate`. **This is the primary safeguard**: rcgen does *not* check that the supplied key actually corresponds to the supplied cert, so `from_pem(a.cert, b.key)` would otherwise succeed silently.
5. **rcgen parseability probe** - `CertificateParams::from_ca_cert_der`. This is run eagerly so `issue_leaf` cannot surprise the caller later; it catches multi-AVA RDN subjects, unsupported extensions, and similar. Failure → `InvalidCertificateDer { detail }`.

::: tip Why the eager rcgen probe matters
The same `from_ca_cert_der` call is what `issue_leaf` uses to reconstruct the issuer. Running it at load time converts a *deferred* failure (issuance breaks weeks later) into an *immediate, attributable* one (`from_pem` rejects the bad CA up front).
:::

### Accessors and fingerprint

```rust
pub fn cert_pem(&self) -> &str
pub fn key_pem(&self) -> &str
pub fn cert_der(&self) -> &[u8]
pub fn fingerprint_sha256(&self) -> [u8; 32]
```

`fingerprint_sha256` is a plain SHA-256 over the cached **certificate DER** (not the PEM, not the key). Because the DER is the input PEM decoded exactly once, the fingerprint is **stable across a `from_pem` round-trip** and identical between two `from_pem` calls on the same input - both invariants are pinned by tests. The fingerprint is what the daemon and trust-store layers use to identify "the current CA" without comparing whole certificates.

### `issue_leaf`

```rust
pub fn issue_leaf(&self, names: &[String], validity: Validity) -> Result<LeafCert, TlsError>
```

Issues a leaf certificate whose Subject Alternative Names are exactly `names`. The mechanism is worth understanding:

1. Build leaf `CertificateParams` via `params::leaf_params` (SAN validation happens here).
2. **Reconstruct a synthetic issuer** from the cached cert DER plus the live `key_pair`, via `CertificateParams::from_ca_cert_der(...).self_signed(&self.key_pair)`. The synthetic issuer cert gets a fresh random serial and signature, but the same SPKI / DN / key - which is all rcgen's leaf-signing path reads.
3. Generate a **fresh** key pair for the leaf (same P-256 algorithm).
4. Sign with `leaf_params.signed_by(&PublicKeyHandle(&leaf_key), &issuer_cert, &self.key_pair)`.

`PublicKeyHandle` is a thin newtype that implements rcgen's `PublicKeyData` trait by delegating to the wrapped `KeyPair` - it exists purely to satisfy the `&impl PublicKeyData` argument shape on `signed_by`.

The chain tests verify the result rigorously: the leaf's issuer DN equals the CA subject DN; the leaf's **AKI equals the CA's SKI byte-for-byte** (and that SKI equals `Sha256(SPKI)[..20]` under rcgen's `KeyIdMethod::Sha256`); the leaf signature verifies against the CA public key; and successive issuances carry **distinct serials**. A `from_pem`-reloaded CA produces leaves with the same issuer/AKI alignment.

### Debug redaction

`CertAuthority` has a hand-written `Debug` impl that prints only the hex fingerprint and `key: "(elided)"`:

```rust
CertAuthority { fingerprint_sha256: "ab12…", key: "(elided)" }
```

The default derive would print the full `key_pem`, which `tracing::error!(?ca)` in the daemon would leak into logs. The `debug_redacts_key_material` test asserts the formatted output contains neither `"BEGIN"`, nor `"PRIVATE KEY"`, nor the base64 key body.

`CertAuthority` is also asserted `Send + Sync`.

## `LeafCert`

```rust
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct LeafCert { /* cert_pem, key_pem */ }

impl LeafCert {
    pub fn cert_pem(&self) -> &str;
    pub fn key_pem(&self) -> &str;
    pub fn chain_pem(&self, ca_cert_pem: &str) -> String;
}
```

A `LeafCert` is just the signed leaf certificate plus its private key, both as PEM. Its constructor is `pub(crate)` - user code must always go through `CertAuthority::issue_leaf`, so a leaf can never exist without a real signing operation behind it.

`chain_pem` returns `format!("{leaf_pem}\n{ca_cert_pem}")` - leaf first, then the CA cert, joined by exactly one `\n`. It performs **no validation** of `ca_cert_pem` (a test, `chain_pem_passes_through_arbitrary_ca_string`, pins this no-validation invariant so a future contributor cannot quietly add "smart" validation). This is the form a TLS server hands to a client as its certificate chain.

::: warning PEM block separation
`chain_pem` always inserts a single `\n` between the two blocks. RFC 7468 §3 *permits* but does not *mandate* whitespace tolerance between blocks; `rustls` and the `pem` crate accept this form, but a strict downstream parser might differ.
:::

## Parameter builders (`params.rs`)

`params.rs` is crate-private and owns all the X.509 policy. Two builders.

### CA parameters

`ca_params(common_name, validity)`:

| Field | Value |
| --- | --- |
| `not_before` / `not_after` | from `validity` |
| `is_ca` | `IsCa::Ca(BasicConstraints::Constrained(0))` - CA:TRUE, **path length 0** (no intermediates) |
| `key_usages` | `KeyCertSign`, `CrlSign` |
| `extended_key_usages` | empty |
| `subject_alt_names` | empty (CA carries no SAN) |
| `use_authority_key_identifier_extension` | `false` |
| `distinguished_name` | single `CommonName` = `common_name` |

The common name is validated up front: empty → `EmptyCommonName`; longer than `CN_MAX_BYTES` (**64**, the RFC 5280 §A.1 `ub-common-name` cap) → `CommonNameTooLong { max }`. 64 bytes exactly is accepted.

### Leaf parameters

`leaf_params(names, validity)`:

| Field | Value |
| --- | --- |
| `not_before` / `not_after` | from `validity` |
| `is_ca` | `IsCa::ExplicitNoCa` - CA:FALSE |
| `subject_alt_names` | one `SanType::DnsName` per entry in `names` |
| `key_usages` | `DigitalSignature`, `KeyEncipherment` |
| `extended_key_usages` | `ServerAuth` only |
| `use_authority_key_identifier_extension` | `true` |
| `distinguished_name` | **empty** (no CN - modern browsers want SAN-only) |

An empty `names` slice → `EmptyNameSet`. Each name is validated as an `Ia5String` (ASCII); a non-IA5 entry → `InvalidDnsName { index }`, carrying the **0-based index** of the offending name so the caller can report exactly which name failed (e.g. `föö.test` at index 1). Wildcards like `*.foo.test` pass through and are preserved as DNS-name SANs.

::: info The AKI toggle
`use_authority_key_identifier_extension = true` on leaves is load-bearing: without it rcgen does not emit the Authority Key Identifier extension at all (`rcgen-0.13.2/src/certificate.rs:680-704`). The `leaf_params_enables_aki` test pins this so the AKI→SKI chain link cannot silently disappear.
:::

## `Validity`

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct Validity { /* not_before, not_after: OffsetDateTime */ }

impl Validity {
    pub fn new(not_before: OffsetDateTime, not_after: OffsetDateTime) -> Result<Self, TlsError>;
    pub fn not_before(&self) -> OffsetDateTime;
    pub fn not_after(&self) -> OffsetDateTime;
}
```

`Validity` is the **only timestamp-shaped type in the public surface**, and it is the mechanism that keeps the crate clock-free: every cert-generating call takes one by value, and the crate never reads "now". The daemon reads the clock and constructs the window.

`new` enforces two rules:

* `not_before > not_after` → `NotBeforeAfterNotAfter`. (Equal endpoints are allowed.)
* `not_before.year() > 9998` **or** `not_after.year() > 9998` → `YearAbove9998`.

The year cap reserves a one-year gap below `time`'s representable ceiling (±9999 without the `large-dates` feature) so callers cannot accidentally emit `99991231235959Z` `GeneralizedTime`, which several trust stores treat as "no expiry" or refuse outright. **Pre-1950 timestamps are not rejected** - RFC 5280 §4.2.1.5 permits `GeneralizedTime` for them, and "no certs before the unix epoch" is a policy decision for the daemon, not this crate. Round-trip tests confirm validity windows survive the cert's ASN.1 time encoding to second precision, across the 2049/2050 UTCTime→GeneralizedTime cutover.

## Error model (`error.rs`)

`TlsError` is the single error type returned by every fallible API. It has three variants, each carrying a typed `*Reason` sub-enum so callers match on precise failure modes instead of parsing message strings:

```rust
#[derive(Debug, Error, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum TlsError {
    Generate { reason: GenerateErrorReason },
    Parse    { reason: ParseErrorReason },
    Validity { reason: ValidityErrorReason },
}
```

| Sub-enum | Notable variants |
| --- | --- |
| `GenerateErrorReason` | `EmptyCommonName`, `CommonNameTooLong { max }`, `EmptyNameSet`, `InvalidDnsName { index }`, `KeyGenerationFailed { detail }`, `SelfSignFailed { detail }`, `SignByCaFailed { detail }` |
| `ParseErrorReason` | `InvalidCertificatePem`, `InvalidCertificateDer { detail }`, `InvalidPrivateKeyPem`, `KeyDoesNotMatchCertificate` |
| `ValidityErrorReason` | `NotBeforeAfterNotAfter`, `YearAbove9998` |

Every enum is `#[non_exhaustive]` (semver-safe additions) and the reason enums are `Copy`. Crucially, `TlsError` is `Clone + PartialEq + Eq + Send + Sync`.

### The rcgen `=` pin and the tripwire test

`TlsError` deliberately does **not wrap `rcgen::Error`** - `rcgen::Error` is neither `Clone` nor `Eq`, and wrapping it would forfeit those derives across the whole error type. Instead, the crate-private `rcgen_detail` function maps each `rcgen::Error` variant to a stable `&'static str` tag (`"RingUnspecified"`, `"UnsupportedExtension"`, …), surfaced through the `detail` fields above. Unknown variants fall through to `"Unknown"`.

The risk: `rcgen::Error` is `#[non_exhaustive]` upstream, so a future rcgen release can *add* a variant. If that happened silently, real failures would map to `"Unknown"` and lose diagnostic value. Two mechanisms prevent it:

1. **The `=` version pin.** The workspace `Cargo.toml` pins `rcgen = "=0.13.2"`. The exact-version pin means a maintainer must make a *deliberate edit* to bump rcgen - it cannot drift in via a routine `cargo update`.

2. **The `rcgen_error_detail_table_is_current` tripwire test.** It enumerates every `rcgen::Error` variant present under our feature set and asserts each maps to a tag that is neither `"Unknown"` nor empty. When the rcgen bump lands, this test fires until the maintainer maps the new variant in `rcgen_detail`.

Together they convert a silent upstream addition into a compile-and-test failure exactly at bump time. (`MissingSerialNumber` is cfg-gated to `not(crypto)` upstream and excluded, since the crate enables the `crypto` feature.)

## Purity & dependency invariants

The crate header forbids `tokio`, `std::fs`, `std::time::SystemTime`/`Instant`, and env reads. All random material comes from rcgen's configured backend (`ring`). These properties are not just documented - they're **tested** in `tests/no_runtime_deps.rs`, which walks `cargo metadata` over normal-kind edges from the `yerd-tls` node and asserts:

* no `tokio` in the runtime graph;
* no `anyhow` in the runtime graph;
* exactly one `time` version;
* exactly one `x509-parser` version.

This is a deterministic replacement for earlier grep- and `cargo deny`-based gates.

## Test suite

The integration tests under `tests/` form the behavioural contract:

| File | Covers |
| --- | --- |
| `roundtrip.rs` | PEM/DER/fingerprint byte-identical round-trips through `from_pem`; signing capability recovered |
| `fingerprint.rs` | fingerprint = hand-computed `Sha256(DER)`; differs between independent generations; stable after reload |
| `chain.rs` | issuer DN = CA subject DN; leaf AKI = CA SKI = `Sha256(SPKI)[..20]`; signature verification; unique serials |
| `sans.rs` | every passed name appears as a SAN; wildcard preserved; CA/leaf BasicConstraints, KeyUsage, EKU |
| `validity.rs` | NotBefore/NotAfter round-trip to second precision; post-2050 and pre-2050 encodings; leaf validity independent of CA validity |
| `pem_edge_cases.rs` | multi-block PEM (first block wins); encrypted/non-PKCS#8 key rejected; whitespace-in-label rejected; trailing-newline tolerance |
| `issuance_negative.rs` | every rejected-input path: empty/overlong CN, empty/non-IA5 names, reversed validity, garbage/mismatched/cross-algorithm PEM, wrong tags |
| `no_runtime_deps.rs` | the dependency-graph invariants above |

## Where this fits

```mermaid
flowchart TD
    Caller["caller (yerdd cert store)"]
    TLS["yerd-tls"]
    Gen["CertAuthority::generate / from_pem<br/>(PEM in, PEM out, no I/O)"]
    Issue["CertAuthority::issue_leaf<br/>(LeafCert: cert+key PEM)"]
    FP["fingerprint_sha256<br/>([u8; 32] CA identity)"]
    Config["yerd-config<br/>(persist PEM)"]
    Platform["yerd-platform / yerd-helper<br/>(install CA into trust stores)"]

    Caller -->|"reads clock, Validity::new(...)"| TLS
    TLS --> Gen
    TLS --> Issue
    TLS --> FP
    TLS -->|"PEM strings handed back to callers"| Config
    TLS -->|"PEM strings handed back to callers"| Platform
```

See also: [HTTPS & Certificates](../../guide/https) for the user-facing workflow, the [Crates Overview](../crates) for how `yerd-tls` sits among the other crates, [yerd-platform](./yerd-platform) for trust-store installation, and [yerdd](../binaries/yerdd) for the daemon that drives issuance. Source: [`crates/yerd-tls`](https://github.com/forjedio/yerd/tree/main/crates/yerd-tls).

---

---
url: 'https://yerd.app/developer/crates/yerd-dns.md'
---
# yerd-dns

Authoritative `*.test` DNS responder for Yerd, plus the [hickory-dns](https://github.com/hickory-dns/hickory-dns) server wiring that puts it on the wire.

The crate's `Cargo.toml` describes it precisely:

> Authoritative `*.test` DNS responder + hickory server wiring for Yerd.

The whole point of `yerd-dns` is to resolve names under a configured TLD (by default `.test`) to loopback - `127.0.0.1` for `A`, `::1` for `AAAA` - so a browser request for `https://my-app.test` lands on Yerd's proxy. For how that fits into the wider system and how the OS is pointed at this responder, see [DNS & .test Domains](../../guide/dns).

::: info Scope boundary
This crate answers DNS queries. It does **not** configure the operating system's resolver to send `.test` queries here. That privileged, per-OS work lives behind `yerd_platform::ResolverInstaller` - see [yerd-platform](./yerd-platform) and [Elevation & Privileges](../../guide/elevation). `yerd-dns` only opens loopback sockets and replies to whatever queries arrive.
:::

## Design: a pure core at an I/O edge

The crate follows Yerd's standard split between deterministic pure logic and a thin I/O shell:

```mermaid
flowchart TD
    Q["wire query (UDP / TCP)"] --> H
    subgraph IO["server.rs (LoopbackHandler) - I/O edge"]
        H["decode RecordType to QClass,<br/>strip trailing dot from owner name"]
        E["encode Answer to DNS message (RData, RCODE, AA bit)"]
    end
    subgraph Pure["responder.rs - pure, no I/O"]
        R["Responder::answer(name, qtype, tld)"]
        A["answer.rs::Answer"]
        R --> A
    end
    H --> R
    A --> E
    E --> Reply["wire reply"]
```

* **`responder.rs` / `answer.rs`** are pure: no async, no sockets, no `hickory` types in their visible API. Given a name, a query-type classification, and a TLD, `Responder::answer` returns an [`Answer`](#answer-the-decision-vocabulary) enum. This is the testable decision core.
* **`server.rs`** is the I/O edge: it binds UDP + TCP, decodes inbound queries into the pure vocabulary, calls the responder, and re-encodes the decision onto the wire via `hickory-server`.
* **`error.rs`** defines the single `DnsError` exposed by the fallible I/O surface.

The purity boundary is enforced mechanically - see [The purity tripwire](#the-purity-tripwire).

## Module / file map

| File | Role | Public exports |
| --- | --- | --- |
| `src/lib.rs` | Crate root, module wiring, constants | `Answer`, `Responder`, `Bound`, `DnsError`, `BindProto`, `ANSWER_TTL_SECS` |
| `src/answer.rs` | Output vocabulary + internal query classification | `Answer` (`QClass` is `pub(crate)`) |
| `src/responder.rs` | Pure `(name, qtype, tld) → Answer` mapping | `Responder` |
| `src/server.rs` | hickory bind/serve wiring + wire encoding | `Bound` |
| `src/error.rs` | Error type for the I/O surface | `DnsError`, `BindProto` |
| `tests/pure_responder_no_io.rs` | Source-byte purity tripwire | - |
| `tests/server_smoke.rs` | End-to-end UDP + TCP wire-shape test | - |

Two crate-level constants live in `lib.rs`:

```rust
/// TTL on every A/AAAA record we hand out.
pub const ANSWER_TTL_SECS: u32 = 60;

/// Number of UDP/TCP port-pair attempts on the ephemeral path.
pub(crate) const RETRY_BUDGET: usize = 5;
```

`#![forbid(unsafe_code)]` is set crate-wide.

## `Answer`: the decision vocabulary

`Answer` is the pure crate's output type. Wire-level encoding lives in `server.rs`; this enum is what the responder produces. It is `Copy` and `#[non_exhaustive]`:

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Answer {
    /// Matched, qtype = A → 127.0.0.1 with TTL ANSWER_TTL_SECS.
    Loopback4,
    /// Matched, qtype = AAAA → ::1 with TTL ANSWER_TTL_SECS.
    Loopback6,
    /// Name belongs to the configured TLD but the qtype is not A/AAAA.
    /// Wire: NOERROR with empty answer + no SOA in authority.
    NoData,
    /// Name is within the configured TLD but does not exist.
    /// Wire: authoritative NXDOMAIN + no SOA.
    NxDomain,
    /// Name is outside the configured TLD - we are not authoritative.
    /// Wire: REFUSED with the AA bit cleared.
    Refused,
}
```

Each variant maps deterministically to a wire response - RCODE, answer records, and the authoritative (AA) bit - in `server.rs`:

| `Answer` | RCODE | Answer records | AA bit |
| --- | --- | --- | --- |
| `Loopback4` | `NoError` | one `A` → `127.0.0.1`, TTL 60 | set |
| `Loopback6` | `NoError` | one `AAAA` → `::1`, TTL 60 | set |
| `NoData` | `NoError` | none | set |
| `NxDomain` | `NXDomain` | none | set |
| `Refused` | `Refused` | none | **cleared** |

The `Refused` variant exists for a specific reason. If a resolver is misconfigured and routes a non-`.test` query to this responder, replying `REFUSED` with the AA bit cleared signals "ask someone else" rather than authoritatively denying a domain Yerd does not own.

Alongside `Answer`, `answer.rs` defines the crate-internal `QClass`, kept out of the responder's view of the upstream record-type enum so `responder.rs` stays free of the `hickory` dependency:

```rust
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum QClass {
    A,
    Aaaa,
    /// MX, TXT, SOA, NS, ANY (per RFC 8482 §4.3), …
    Other,
}
```

`server.rs` is the only file that translates a wire `RecordType` into a `QClass`.

## `Responder`: the pure answer logic

`Responder` wraps a single TLD (a `yerd_core::Tld`) and classifies queries with no I/O:

```rust
use yerd_core::Tld;

pub struct Responder {
    tld: Tld,
}

impl Responder {
    #[must_use]
    pub fn new(tld: Tld) -> Self { /* … */ }

    pub(crate) fn answer(&self, name: &str, qtype: QClass) -> Answer { /* … */ }
}
```

::: info `answer` is `pub(crate)`
`Responder::new` is the only public method. `answer` takes a `pub(crate)` `QClass`, so it is not callable from outside the crate - the sole caller is `LoopbackHandler` in `server.rs`. External consumers (the daemon) construct a `Responder` and hand it to `Bound::serve`; the responder's logic is exercised in tests via the `tests/` integration suite and the in-module unit tests.
:::

The classification algorithm, copied from the source, runs in order:

```rust
let bytes = name.as_bytes();

// 1. Strip one trailing '.' (FQDN form).
let bytes = match bytes.split_last() {
    Some((&b'.', rest)) => rest,
    _ => bytes,
};

let tld_bytes = self.tld.as_str().as_bytes();

// 2. Is the name inside our zone? (apex, or *.<tld>) - case-insensitive.
let is_apex = bytes.len() == tld_bytes.len() && bytes.eq_ignore_ascii_case(tld_bytes);
let ends_in_dot_tld = bytes.len() > tld_bytes.len()
    && bytes.get(bytes.len() - tld_bytes.len() - 1) == Some(&b'.')
    && bytes
        .get(bytes.len() - tld_bytes.len()..)
        .is_some_and(|s| s.eq_ignore_ascii_case(tld_bytes));

// 3. Outside our zone ⇒ REFUSED.
if !is_apex && !ends_in_dot_tld {
    return Answer::Refused;
}

// 4. Apex (bare TLD) ⇒ NoData (no A/AAAA at the apex).
if is_apex {
    return Answer::NoData;
}

// 5. In-zone subdomain. Malformed label ⇒ authoritative NXDOMAIN.
if bytes.first() == Some(&b'.') {
    return Answer::NxDomain;
}
if bytes.windows(2).any(|w| w == b"..") {
    return Answer::NxDomain;
}

match qtype {
    QClass::A => Answer::Loopback4,
    QClass::Aaaa => Answer::Loopback6,
    QClass::Other => Answer::NoData,
}
```

Several decisions are worth noting:

* **Zone membership is decided before validity.** A name is in-zone when it is the bare TLD (apex) or ends in `.<tld>`. This ordering is what makes `app.testify` (TLD `test`) resolve to `Refused` rather than being treated as a `.test` name - the byte before the TLD suffix must be a literal `.`.
* **Case-insensitive matching.** Both apex and suffix comparisons use `eq_ignore_ascii_case`, so `APP.TEST` resolves the same as `app.test`.
* **Multi-label TLDs work.** The TLD is a single `yerd_core::Tld` string, so `dev.local` is a valid TLD: `app.dev.local` → `Loopback4`, `dev.local` (apex) → `NoData`, and `local` → `Refused`.
* **Malformed in-zone names are NXDOMAIN, not REFUSED.** `.test`, `x..test`, and `app..test` are within the `.test` zone but have an empty or doubled label, so they are authoritatively non-existent.

These rows are pinned exactly by the `answer_table` unit test in `responder.rs`, which asserts each `(name, qtype, tld) → Answer` pairing including the multi-label `dev.local` cases.

## `Bound`: the hickory server wrapper

`Bound` is a bound UDP + TCP socket pair on a single `SocketAddr`. It is constructed via `Bound::bind` and consumed by `Bound::serve` - a deliberate two-stage lifecycle.

```rust
pub struct Bound { /* udp, tcp, local_addr */ }

impl Bound {
    pub async fn bind(addr: SocketAddr) -> Result<Self, DnsError>;

    #[must_use]
    pub fn local_addr(&self) -> SocketAddr;

    pub async fn serve<S>(self, responder: Responder, shutdown: S) -> Result<(), DnsError>
    where
        S: Future<Output = ()> + Send + 'static;
}
```

### Why bind and serve are separate

The daemon needs the resolved `SocketAddr` - including the kernel-assigned port when the requested port was `0` - *before* it starts serving, so it can hand that address to `yerd_platform::ResolverInstaller::install`. Splitting `bind` from `serve` lets the daemon bind the sockets up front (alongside its HTTP/HTTPS listeners), read `local_addr()`, and only later spawn the serve loop.

In practice the daemon (`yerdd`) binds at the fixed configured `dns_port` so an installed resolver config keeps pointing at the same address across restarts; the ephemeral (`port == 0`) path is primarily for tests like `tests/server_smoke.rs`, which bind `127.0.0.1:0`.

### `bind` and the UDP/TCP port-pairing problem

DNS needs UDP **and** TCP on the *same* port. With an explicit port this is straightforward - bind UDP, bind TCP, return any failure as `DnsError::Bind`. With an ephemeral port (`addr.port() == 0`) the kernel picks the UDP port, and TCP must then match it:

1. Bind UDP at `addr`; read back `udp.local_addr()` to learn the kernel-assigned port.
2. Try to bind TCP at the *same* IP and port.
3. On TCP success, return the `Bound` pair.
4. On TCP failure with an ephemeral request, drop the UDP socket and retry - up to `RETRY_BUDGET` (5) attempts. After exhaustion, return `DnsError::PortPairMismatch`.
5. With an explicit (non-zero) port there is no retry; a TCP bind failure surfaces immediately as `DnsError::Bind`.

::: warning Loopback contract is documented, not enforced
`bind` documents that `addr.ip().is_loopback()` should hold (`127.0.0.0/8` or `::1`). Binding to `0.0.0.0` / `::` would expose the responder to the LAN. `yerd-dns` does **not** enforce this - the daemon validates inputs before opening sockets. Callers report `local_addr()` (the actual bound port) in operator logs, never the input `addr`.
:::

### `serve` and graceful shutdown

`serve` consumes the `Bound`, builds a `LoopbackHandler`, registers the UDP socket and TCP listener with a `hickory_server::ServerFuture`, and runs until the caller-supplied `shutdown` future resolves:

```rust
let handler = LoopbackHandler { responder };
let mut server = ServerFuture::new(handler);
server.register_socket(self.udp);
server.register_listener(self.tcp, std::time::Duration::from_secs(5));

tokio::pin!(shutdown);
tokio::select! {
    res = server.block_until_done() => res
        .map_err(|source| DnsError::ServerTask { source }),
    () = &mut shutdown => server.shutdown_gracefully().await
        .map_err(|source| DnsError::ServerTask { source }),
}
```

When `shutdown` fires, the responder calls hickory's `shutdown_gracefully` to drain in-flight requests and returns `Ok(())` once the drain completes. The TCP listener is registered with a 5-second per-connection timeout.

The `S: Send + 'static` bound is load-bearing: the daemon `tokio::spawn`s the future returned by `serve`, which captures `shutdown` across `.await` points. A `Send + 'static` static assertion in `server.rs` guards both `Bound` and `Responder` at type-check time, so an accidental borrowed field on either would fail to compile rather than silently break the daemon's spawn site.

### `LoopbackHandler`: wire ↔ pure translation

`LoopbackHandler` implements `hickory_server::server::RequestHandler`. Per request it:

1. Reads the single query (`request.query()`). Hickory's parser pre-handler has already `FORMERR`'d malformed packets - zero or more than one query - before this code runs, so the handler always sees exactly one query.
2. Maps the wire `RecordType` to a `QClass` (`A`, `AAAA`, or `Other`).
3. Stringifies the owner name and **strips the trailing dot** with `trim_end_matches('.')`. Hickory writes a trailing dot for FQDN-flagged names; trimming it lets the responder's exact-match path see the bare TLD. The comment flags this trim as "load-bearing."
4. Calls `self.responder.answer(name, qclass)`.
5. Encodes the resulting `Answer` into a response: it copies the request header (setting `QR=1`), sets the AA bit (cleared only for `Refused`), sets the RCODE, and attaches `A`/`AAAA` records for the loopback cases.

The response is built with **no SOA** record in the authority section (a deliberate RFC 2308 §3 decision for the `NoData`/`NXDOMAIN` cases) and no NS or additional records:

```rust
let response = builder.build(
    header,
    answers.iter(),
    std::iter::empty::<&Record>(), // name_servers - no NS records
    std::iter::empty::<&Record>(), // soa - RFC 2308 §3: deliberately no SOA
    std::iter::empty::<&Record>(), // additionals
);
```

## `DnsError`

`DnsError` is the single error type for every fallible public API in the crate. It is `#[non_exhaustive]` and, unlike `yerd-tls`'s `TlsError`, is **not** `Clone + Eq` - it carries `std::io::Error` and `hickory_proto::error::ProtoError` via `#[source]`. The daemon either logs it or maps it to a `yerd_ipc::ErrorCode` at the IPC boundary.

| Variant | Meaning |
| --- | --- |
| `Bind { proto, addr, source }` | UDP or TCP bind failed. `proto` is a `BindProto` (`Udp` / `Tcp`). |
| `PortPairMismatch { udp_addr, attempts, source }` | Ephemeral path only: UDP bound but TCP could not match the port after `RETRY_BUDGET` attempts. |
| `ServerTask { source }` | The `hickory_server::ServerFuture` task returned a `ProtoError`. |

`BindProto` is a small `Copy` enum (`Udp` / `Tcp`) with a `Display` impl rendering `UDP` / `TCP`. It is intentionally *not* `#[non_exhaustive]`: this crate services only unencrypted UDP/TCP, and `DoT` / `DoH` / `DoQ` would be separate crates entirely.

## Tests and invariants

### The purity tripwire

`tests/pure_responder_no_io.rs` is a source-byte scan that fails the build if `src/responder.rs` or `src/answer.rs` contains any I/O-shaped substring:

```rust
const FORBIDDEN: &[&[u8]] = &[
    b"tokio", b"hickory", b"std::net", b"std::io", b"std::fs",
    b"std::env", b"std::process", b"std::time::Instant", b"std::time::SystemTime",
];

const SCANNED: &[&str] = &["src/responder.rs", "src/answer.rs"];
```

The scan includes comments, which is why the pure modules avoid even *naming* the forbidden crates in commentary. It is a smoke check, not a purity proof - a determined contributor can alias their way past it - but it reliably catches the realistic regression: an accidental `use tokio::…` line.

A second compile-time guard lives in `answer.rs`: `answer_match_is_exhaustive` forces a `match` over every `Answer` variant, so adding a variant without updating the encoding table in `responder.rs`/`server.rs` breaks the build.

### End-to-end wire shape

`tests/server_smoke.rs` binds a real `Bound` on `127.0.0.1:0`, spawns `serve`, and drives it with `hickory-client` over both UDP and TCP. It runs for both a single-label TLD (`test`) and a multi-label TLD (`dev.local`) and asserts:

* `<site> A` → `NoError`, exactly one answer, TTL `ANSWER_TTL_SECS`, RData `127.0.0.1`.
* `<site> AAAA` → `NoError`, one answer, RData `::1`.
* `<site> MX` → `NoError`, **zero** answers and **zero** authority records (pins the no-SOA `NoData` decision).
* `unrelated.com A` → `Refused` with the AA bit **cleared**.
* `<apex> A` → `NoError`, zero answers (apex carve-out).
* The same `<site> A` query over **TCP** returns the loopback `A` record, exercising the TCP listener path.
* A hand-crafted malformed UDP packet (`QDCOUNT=0`) gets a `FORMERR` reply from hickory's pre-handler - never reaching `LoopbackHandler` - with the request ID echoed.
* Shutdown completes within a bounded 5-second timeout.

`error.rs` additionally unit-tests `Display` output per `DnsError` variant and the `BindProto` rendering.

## Where this crate sits

* **Consumed by:** `yerdd` (the daemon). It binds `Bound` during startup at `SocketAddr::new(DNS_IP, config.dns_port)`, reads `local_addr()`, and spawns `Bound::serve(Responder::new(tld), shutdown)` on the runtime. See [yerdd (daemon)](../binaries/yerdd).
* **Depends on:** [`yerd-core`](./yerd-core) for the `Tld` newtype; `hickory-proto` / `hickory-server` for the wire layer; `tokio` for the sockets.
* **Does not depend on:** [`yerd-platform`](./yerd-platform). Pointing the OS resolver at this responder is a separate, privileged concern handled by `ResolverInstaller`.

For the operator's-eye view of how `.test` resolution is set up and verified, see [DNS & .test Domains](../../guide/dns) and [Elevation & Privileges](../../guide/elevation). For the surrounding architecture, see the [Crates Overview](../crates) and [Architecture](../architecture).

Source: [`crates/yerd-dns`](https://github.com/forjedio/yerd/tree/main/crates/yerd-dns).

---

---
url: 'https://yerd.app/developer/crates/yerd-proxy.md'
---
# yerd-proxy

`yerd-proxy` is the hand-rolled reverse proxy that terminates `*.test` HTTP/HTTPS traffic and forwards each routed request to its site backend. It is built directly on **hyper** (HTTP/1.1) and **tokio-rustls** (TLS termination) - there is no Caddy, no nginx, no embedded web server. The crate owns the accept loops, TLS handshake, request routing, the FastCGI client that talks to PHP-FPM, and the HTTP/1.1 client that talks to FrankenPHP workers.

Its source description is concise:

> HTTP/HTTPS reverse proxy for Yerd's `*.test` traffic.

The crate is deliberately decoupled from the rest of the workspace. It depends only on [`yerd-core`](./yerd-core) (for the `Site` / `SiteRouter` types) plus the async/HTTP/TLS stack. It does **not** depend on [`yerd-tls`](./yerd-tls) or [`yerd-php`](./yerd-php) - those couplings are inverted through two trait seams (`CertStore`, `BackendResolver`) injected by the daemon. See the [Crates Overview](../crates) for how it sits in the dependency graph and [The Daemon](../../guide/daemon) for the runtime that drives it.

::: info `#![forbid(unsafe_code)]`
The whole crate is `#![forbid(unsafe_code)]`. A compile-time guard in `lib.rs` also asserts `ProxyError: Send + Sync + 'static` so the error can cross hyper service boundaries and `tokio::spawn` sites cleanly.
:::

## Module map

```
crates/yerd-proxy/src/
├── lib.rs           # re-exports + Send/Sync compile guard
├── backend.rs       # Backend enum - where a routed request is forwarded
├── error.rs         # ProxyError
├── traits.rs        # CertStore + BackendResolver (daemon-injected seams)
├── tls.rs           # rustls ServerConfig build + SNI cert resolution
├── server.rs        # ProxyServer::serve - accept loops, dispatch
├── pure/            # synchronous, runtime-free, I/O-free helpers
│   ├── mod.rs
│   ├── cgi_params.rs   # build the CGI/1.1 param list for FastCGI
│   ├── fcgi_codec.rs   # FastCGI record framing (encode/decode)
│   ├── try_files.rs    # static-file/directory-index candidate resolution + MIME map
│   └── redirect.rs     # HTTP → HTTPS redirect URI builder
└── forward/         # async per-backend forwarding I/O
    ├── mod.rs          # BoxBody + body helpers
    ├── static_file.rs  # serve a real static file, or a directory's index.html/.htm
    ├── script_file.rs  # resolve a real, on-disk PHP script to execute directly (WordPress-gated)
    ├── fcgi.rs         # FastCGI forwarder (PHP-FPM)
    ├── http.rs         # plain HTTP/1.1 forwarder (FrankenPHP)
    └── upgrade.rs      # Connection: Upgrade tunnel (WebSocket etc.)
```

The split between `pure/` and `forward/` is the central design seam: **`pure/` is synchronous, allocation-only, I/O-free, and exhaustively table-tested**; `forward/` owns the actual socket reads and writes and the tokio runtime.

## The `pure/` layer

Everything in `pure/` is deterministic and unit-testable without a runtime, sockets, or a backend. This is where the fiddly protocol logic lives.

### `fcgi_codec` - FastCGI record framing

A from-scratch FastCGI codec. It does **encode/decode of records only** - the forwarder owns the socket. Constants pin the protocol shape:

```rust
pub const FCGI_VERSION: u8 = 1;
pub const FCGI_RESPONDER: u16 = 1;
pub const FCGI_MAX_PAYLOAD: usize = 65_535; // content_length is a u16
pub const FCGI_REQUEST_COMPLETE: u8 = 0;
```

The 8-byte record header round-trips through `Header::encode`/`Header::decode`:

```rust
pub struct Header {
    pub version: u8,
    pub record_type: RecordType,
    pub request_id: u16,
    pub content_length: u16,
    pub padding_length: u8,
}
```

`RecordType` is a `#[repr(u8)]` enum covering `BeginRequest` (1) through `UnknownType` (11), with `from_u8` for decode. Name/value pairs use FastCGI's length-prefix scheme via `encode_name_value`: lengths `<= 127` take one byte; longer lengths take four bytes with the high bit set on the first. `encode_begin_request_body(role, keep_conn)` produces the 8-byte BEGIN\_REQUEST body (`role` big-endian, then a `FCGI_KEEP_CONN` flag byte). `EndRequest::decode` pulls the `app_status` (u32) and `protocol_status` (u8) out of the END\_REQUEST body.

Decode is strict: `Header::decode` returns `FcgiError::BadVersion` when the version byte is not 1, `FcgiError::Short` when the slice is not exactly 8 bytes, and `FcgiError::UnknownRecordType` for unknown type bytes. The tests pin the wire layout exactly - e.g. encoding a 200-byte name yields a four-byte length of `[0x80, 0x00, 0x00, 0xC8]` (`200 | 0x80000000`).

### `cgi_params` - building the CGI/1.1 variable list

`build_params` turns an HTTP request into the `Vec<(Vec<u8>, Vec<u8>)>` of CGI variables sent in FastCGI `PARAMS` records:

```rust
pub fn build_params(
    method: &str,
    path_and_query: &str,
    headers: &http::HeaderMap,
    document_root: &Path,
    https: bool,
    remote_addr: SocketAddr,
    server_addr: SocketAddr,
) -> Vec<(Vec<u8>, Vec<u8>)>
```

::: info Front-controller routing for dynamic requests
For requests that reach FastCGI, the policy is Caddy-style front-controller routing - the request is mapped to the served root's `index.php`:

* `SCRIPT_FILENAME = document_root / "index.php"`
* `SCRIPT_NAME     = "/index.php"`
* `PATH_INFO       = <original path>`
* `REQUEST_URI     = <original path_and_query>`

Static files are handled *before* this, by a `try_files`-style short-circuit (see [`try_files`](#try_files-static-file-resolution) and [`static_file`](#static_file-serving-real-files)): a request that resolves to a real, non-PHP file under the served root is returned directly. A directory-style request (trailing slash, including the site root) with no `index.php` falls back to that directory's `index.html`/`index.htm` next, so a plain static site works without a front controller at all. Only everything else falls through to FastCGI. Arbitrary on-disk `.php` scripts are still routed through `index.php` (and PHP source is never served as a static file, directly or via a directory index).
:::

::: info `document_root` here is the site's *served web root*
The `document_root` parameter is the directory actually served, which is the site's web root - not necessarily its project root. The daemon passes `site.served_root()` (e.g. `<project>/public` for Laravel), so `SCRIPT_FILENAME` / `DOCUMENT_ROOT` resolve under the framework's front-controller directory. `build_params` itself is web-root-agnostic - it just joins `index.php` onto whatever root it's given. See [Sites → Web root](../../guide/sites#web-root-the-served-directory).
:::

Beyond the script vars, `build_params` emits the standard CGI/1.1 set (`GATEWAY_INTERFACE`, `SERVER_PROTOCOL`, `REQUEST_METHOD`, `QUERY_STRING`, `DOCUMENT_ROOT`, `REMOTE_ADDR`/`REMOTE_PORT`, `SERVER_ADDR`/`SERVER_PORT`, `SERVER_SOFTWARE = yerd`). `HTTPS=on` is added only when the request arrived on the TLS listener. `Host` is surfaced as both `SERVER_NAME` and `HTTP_HOST`; `Content-Type` and `Content-Length` are emitted un-prefixed (FPM expects them that way). Every other header is translated to the generic `HTTP_*` form (uppercased, `-` → `_`), with `Host`/`Content-Type`/`Content-Length` explicitly skipped so they are not double-emitted.

### `redirect` - HTTP → HTTPS upgrade URI

`build_redirect_uri(host, path_and_query, https_port)` constructs the `Location` for the permanent redirect used when a secure site is hit on the plain-HTTP listener:

```rust
pub fn build_redirect_uri(host: &str, path_and_query: &str, https_port: u16) -> String
```

It strips any inbound port from `host` (handling both `host:80` and bracketed IPv6 `[::1]:80`), lowercases the host, defaults an empty path to `/`, and appends `:port` only when the HTTPS port is not 443. The `strip_port` helper is careful about IPv6: a bracketed literal keeps everything up to and including the `]`, and a plain host is only split when it contains exactly one colon (so an unbracketed IPv6 address is left intact). All of this is exercised by a table test (`build_table`) covering `app.test:80`, `[::1]:80`, `[2001:db8::1]:80`, and the 443-vs-8443 port cases.

### `try_files` - static-file resolution {#try\_files-static-file-resolution}

`try_files` decides, purely, whether a request *could* be a static file and what its safe relative path and MIME type would be. It does no I/O - the [`static_file`](#static_file-serving-real-files) forwarder does the actual stat/read.

* **`static_candidate(path)`** maps a URL path to a safe relative `PathBuf`, or `None` when the request must go to the front controller instead. It returns `None` for `/`, for a directory-style request (trailing slash), and for any traversal attempt. It percent-decodes the path and rejects encoded slashes and NUL bytes, so a decoded segment can never escape the served root.
* **`directory_candidate(path)`** is `static_candidate`'s counterpart for directory-index resolution: it maps a *directory-style* URL path (trailing slash, or the bare root `/`) to a safe relative directory `PathBuf`, or `None` for anything else. Same percent-decoding and traversal rules as `static_candidate` - the two intentionally partition every URL shape between them (a path never satisfies both).
* **`is_php_source(path)`** flags PHP source extensions (`php`, `phtml`, `php3`/`php4`/`php5`/`php7`, `phps`, `pht`) so they are *never* served as static bytes - they fall through to FastCGI.
* **`content_type_for(path)`** maps a file extension to a `Content-Type` for the response (a small MIME table, defaulting to `application/octet-stream`).

## The `Backend` enum

`Backend` (in `backend.rs`) is the single description of where a routed request goes:

```rust
#[non_exhaustive]
pub enum Backend {
    /// FastCGI over a Unix domain socket. Unix-only.
    PhpFpm { socket: PathBuf },
    /// FastCGI over TCP loopback. Required on Windows; allowed elsewhere.
    PhpFpmTcp { addr: SocketAddr },
    /// Plain HTTP/1.1 to a FrankenPHP worker.
    FrankenPhp { addr: SocketAddr },
}
```

Its `Display` impl produces the stable labels used in logs and `ProxyError`: `fpm-unix:<path>`, `fpm-tcp:<addr>`, `franken:<addr>`.

Crucially, **`From<yerd_php::Listen>` is intentionally not implemented**. The daemon's `BackendResolver` does that translation, keeping `yerd-proxy` free of any `yerd-php` dependency.

::: info FrankenPHP is wired in the proxy but not yet driven
The `FrankenPhp` variant and its HTTP/upgrade forwarders are fully implemented in this crate, but the daemon's resolver currently produces PHP-FPM backends. Treat the FrankenPHP path as forward-looking plumbing rather than a user-facing feature today.
:::

## Trait seams: `CertStore`, `BackendResolver`, `LoginTokenConsumer`

These three traits (`traits.rs`) are how the daemon injects behaviour without `yerd-proxy` depending on `yerd-tls`, `yerd-php`, or any concrete daemon state.

```rust
pub trait CertStore: std::fmt::Debug + Send + Sync + 'static {
    fn certified_key(&self, sni_host: &str) -> Option<Arc<rustls::sign::CertifiedKey>>;
}

#[async_trait]
pub trait BackendResolver: Send + Sync + 'static {
    async fn backend_for(&self, site: &yerd_core::Site) -> Result<Backend, ProxyError>;

    /// Whether `site` allows `script_file::resolve_script`'s direct-real-file-
    /// execution policy - defaults to `false`.
    async fn allows_direct_script_execution(&self, site: &yerd_core::Site) -> bool {
        false
    }
}

pub trait LoginTokenConsumer: Send + Sync + 'static {
    fn consume(&self, site: &str, token: &str) -> Option<String>;
}
```

* **`CertStore` is synchronous** because rustls's `ResolvesServerCert::resolve` is synchronous - it is called inside the TLS handshake. The daemon's impl is expected to hold the active cert material in an in-memory map and refresh it out-of-band. See [HTTPS & Certificates](../../guide/https).
* **`BackendResolver` is async** and consulted once per request, mapping the routed `&Site` to a concrete `Backend`. The daemon's impl typically calls `yerd_php::PhpManager::ensure(site.php())` and translates the returned `Listen` into a `Backend`. The implementer note in the source is load-bearing: copy out the `Site` fields you need before any `.await`, so the per-request closure doesn't hold a router guard across an await point.
* **`allows_direct_script_execution` is a default method** (defaulting to `false`) gating [`script_file::resolve_script`](#script_file-direct-script-execution) - a real, on-disk `.php` script under the served root is only directly URL-executable for sites the resolver opts in. WordPress needs this for its multiple front controllers (`wp-login.php`, `wp-admin/index.php`, ...); a framework with a single front controller (Laravel, plain PHP) does not, and leaving it on for those would make any stray script under the document root (a debug `phpinfo.php`, an old admin tool) directly URL-executable where it previously wasn't. The daemon's impl (`DaemonBackendResolver`, see [`yerdd`](../binaries/yerdd#backend-resolver-backend-resolver-rs)) checks its `wordpress_sites` cache.
* **`LoginTokenConsumer` is synchronous** and backs the one-click WordPress admin login flow - see [One-click WordPress admin login](#one-click-wordpress-admin-login) below. `consume` must check and invalidate atomically, so a token can never be consumed twice even under concurrent requests for the same token.

Foreign errors (e.g. `PhpError`) are boxed into `ProxyError::BackendResolver { host, source }`, so the proxy never names `yerd-php` in its type signatures.

## TLS and per-SNI cert selection

`tls.rs` wires `CertStore` into rustls. `build_server_config` constructs a `rustls::ServerConfig` with no client auth and an `SniResolver` as the cert resolver:

```rust
pub fn build_server_config<C: CertStore>(store: Arc<C>) -> Arc<ServerConfig> {
    init_crypto_once();
    let resolver = Arc::new(SniResolver::new(store));
    let config = ServerConfig::builder()
        .with_no_client_auth()
        .with_cert_resolver(resolver);
    Arc::new(config)
}
```

`SniResolver::resolve` reads the SNI host from the `ClientHello` and delegates to `CertStore::certified_key`. **A miss is a hard refusal**: it returns `None` (logged at debug as "SNI miss - dropping connection"), which aborts the handshake rather than presenting a default certificate.

`init_crypto_once` installs the ring `CryptoProvider` as the process default exactly once (via `OnceLock`). This is required because the workspace pins rustls 0.23 with no preinstalled global provider; without it, the first `ServerConfig::builder()` call would panic. The function is idempotent and tolerates another provider already being installed (multi-process tests, multi-binary daemons) - it only needs *some* provider in place. `ProxyServer::serve` calls it before binding anything.

## Binding: never bind privileged ports directly

`yerd-proxy` does **not** bind ports itself. The caller binds via [`yerd-platform`](./yerd-platform)'s `PortBinder` and hands the listeners in already-bound. This keeps all privileged-socket logic - and the rootless fallback - out of the proxy and in the platform layer. See [Elevation & Privileges](../../guide/elevation).

`HttpsBinding` documents the contract precisely:

```rust
pub struct HttpsBinding<C: CertStore> {
    /// The bound TCP listener (caller obtained from `PortBinder::bind_pair`
    /// and converted via `tokio::net::TcpListener::from_std`).
    pub listener: TcpListener,
    /// Public port the HTTP→HTTPS redirect should target - not
    /// necessarily what `listener.local_addr()` reports. Shared so the
    /// daemon can flip it live, without restarting the proxy.
    pub public_port: Arc<AtomicU16>,
    /// Cert lookup. Arc-wrapped so the SNI resolver can clone cheaply.
    pub cert_store: Arc<C>,
}
```

`public_port` is separate from the listener's local port on purpose: in rootless mode the daemon may `bind_pair((80, 443), (8080, 8443))` and end up listening on 8443, but the redirect target must reflect the port clients actually use. The daemon's `bind_pair` atomically binds the desired HTTP/HTTPS pair, falling back to `(8080, 8443)` when `80`/`443` require elevation, then converts each `std` listener with `TcpListener::from_std` before passing it in.

It's an `Arc<AtomicU16>` rather than a plain `u16` because the fallback story doesn't end at startup: on macOS, `yerd elevate ports` installs a `pf` redirect (`80`/`443` → the bound rootless pair) that goes live immediately, with no daemon restart - see [Elevation & Privileges](../../guide/elevation). If the redirect target stayed a fixed `u16` captured once in `ProxyServer::serve`, a browser would keep getting bounced to `https://site.test:8443` even after elevation made the plain `https://site.test` reachable. Instead, the daemon owns a shared cell (`DaemonState::redirect_https_port`, see [`yerdd`](../binaries/yerdd)) that a background prober flips between the rootless and well-known port as `yerd_platform::PortRedirector::is_active` changes, and `dispatch` loads the current value on every redirect it builds. `yerd-proxy` itself has no opinion on *why* the port changes - it just reads whatever the cell holds at request time.

## The server: `ProxyServer::serve`

`server.rs` is the runtime entry point:

```rust
pub async fn serve<R, C, S, L>(
    http_listener: TcpListener,
    https: Option<HttpsBinding<C>>,
    router: SharedRouter,
    backend_resolver: Arc<R>,
    login_tokens: Arc<L>,
    login_prepend_script: Option<PathBuf>,
    shutdown: S,
) -> Result<(), ProxyError>
where
    R: BackendResolver,
    C: CertStore,
    S: Future<Output = ()> + Send + 'static,
    L: LoginTokenConsumer,
```

`login_tokens` and `login_prepend_script` back the one-click WordPress admin login flow (see [below](#one-click-wordpress-admin-login)) - `login_prepend_script` is `None` when the daemon couldn't write its auto-login bootstrap script at startup, in which case a presented token is simply never consumed and the request falls through unauthenticated.

`SharedRouter` is `Arc<tokio::sync::RwLock<yerd_core::SiteRouter>>`. Reads are brief: each request takes a read guard only long enough to `resolve(&host)` and clone the matched `Site` (cheap - small strings and `PathBuf`s), then drops the guard before any `.await`. The daemon is the only writer and swaps the whole router under a write guard when a site is parked/linked/unlinked or its PHP version changes.

### Lifecycle

1. `init_crypto_once()`.
2. A shutdown task awaits the `shutdown` future, then calls `notify_waiters()` on an internal `Notify`.
3. Two accept loops are spawned: one HTTP, one HTTPS (only if `https` is `Some`). Each loop is a `tokio::select! { biased; … }` that breaks on the notify and otherwise accepts connections. `biased` makes shutdown take priority over a ready accept.
4. Each accepted connection is handled in its own `tokio::spawn`. The HTTPS path first runs `TlsAcceptor::accept`; handshake failures are logged at debug and the connection is dropped.
5. Connections are served with `hyper::server::conn::http1::Builder::new().serve_connection(io, svc).with_upgrades()` - `with_upgrades()` is required for the WebSocket tunnel path.

On shutdown, accept loops stop immediately; in-flight requests run to hyper's default timeouts. `serve` returns once both accept tasks and the shutdown task have joined.

### Per-request dispatch

The hyper service is **infallible** - internal errors are logged and turned into a `500` so hyper's connection loop survives. `dispatch` does the real work, in order:

1. **Host header.** Missing or non-UTF-8 → `400 Bad Request` ("Missing or invalid Host header.").
2. **Route** via `resolve_request`, producing a `Routed::Site { site, unbound }` or a ready-made `Routed::Respond`. Normal `Host` resolution (`router.resolve(&host)`) is tried first; on a miss, if the host is loopback, an "unbound" (resolver-off) fallback applies - a pinned-site cookie, an `X-Yerd-Site` header, or a same-origin site picker page, none of which are covered here. Anything else on a miss is `404 Not Found` ("No site matches this Host."). The matched `Site` is cloned and the router guard dropped before any further `.await`; the request is served from `site.served_root()` (the site's web root, e.g. `<project>/public`).
3. **HTTP → HTTPS redirect.** On the HTTP listener, unless the request resolved via the unbound fallback, if `site.secure()` is true and a `redirect_port` is set, return `301 Moved Permanently` with `Location` built by `build_redirect_uri`. This runs **before** the one-click login token is ever looked at (see below), so a secure site's token is never burned by the 301 itself.
4. **Resolve backend** via `BackendResolver::backend_for(&site)`. Errors already in the connect/protocol/resolver family pass through; any other variant is wrapped in `ProxyError::BackendResolver { host, source }`.
5. **Upgrade dispatch.** If `upgrade::is_upgrade(headers)`, forward to `upgrade::forward` for `FrankenPhp`, or return `501 Not Implemented` for FastCGI backends (FastCGI cannot model a duplex byte stream).
6. **Normal dispatch.** `FrankenPhp` → `http::forward` directly. `PhpFpm`/`PhpFpmTcp` → `serve_php_fpm`, which runs four steps in order:
   1. **One-click login token.** `consume_login_token_if_present` (see [below](#one-click-wordpress-admin-login)).
   2. **Static-file short-circuit.** `static_file::try_serve`: a GET/HEAD request that resolves to a real, non-PHP file under the served root - allowing symlinks that resolve anywhere within the site's `document_root`, not just the served subdirectory - is returned directly with a guessed `Content-Type`. A candidate that resolves outside `document_root` gets an explicit `403 Forbidden` from yerd-proxy instead of falling through.
   3. **Directory-index short-circuit.** If the static short-circuit didn't match, `static_file::try_serve_index` is tried next - a GET/HEAD directory-style request (trailing slash, including the site root) with no `index.php` in that directory serves its `index.html`/`index.htm` directly, so plain static sites work with no PHP front controller at all. Same `document_root` containment and `403` behavior as `try_serve`.
   4. **Real-script resolution**, gated by `allows_direct_script_execution` - see [script\_file: direct script execution](#script_file-direct-script-execution) - then `fcgi::forward` regardless of what was resolved (a script path, or `None` to fall back to the site root's `index.php`).

`FrankenPhp` serves its own static files and has no equivalent script-resolution step, so steps 6.2-6.4 only apply to the FastCGI backends. The `Listener::{Http, Https}` discriminator is threaded through so the redirect rule and the `HTTPS=on` CGI var both know which listener the connection arrived on.

## One-click WordPress admin login {#one-click-wordpress-admin-login}

`consume_login_token_if_present` (`server.rs`) checks a request for the one-click WordPress admin login token the daemon minted via `Request::MintWordpressLoginToken` (see [`yerdd`](../binaries/yerdd)'s `wordpress_login` module):

```rust
const LOGIN_TOKEN_PARAM: &str = "yerd_login_token";

fn consume_login_token_if_present<B, L: LoginTokenConsumer>(
    req: &mut Request<B>,
    site_name: &str,
    login_tokens: &L,
) -> Option<String>
```

* Only ever considered on a `/wp-admin` path prefix - every other request skips the check entirely without touching `login_tokens`.
* Consumes the token via `LoginTokenConsumer::consume(site_name, token)`, which must be atomic (check-and-invalidate in one step) so concurrent requests can't both succeed against the same token.
* On success, strips `yerd_login_token` from the forwarded URI (via `pure::query::strip_param`) so it never reaches PHP or request logging, and returns `Some(target_user)` (`""` meaning no preference - the caller falls back to the earliest-created administrator).
* **Ordering is load-bearing**: `serve_php_fpm` calls this *after* `dispatch`'s HTTP→HTTPS redirect check has already run (step 3 above), so a secure site's token is never burned by the 301 itself - a browser presenting the token over plain HTTP gets redirected first, with the token intact in the `Location`, and only consumes it on the follow-up HTTPS request.

On success, `serve_php_fpm` builds a `cgi_params::AutoLoginParams { prepend_script, target_user }` and passes it through to `fcgi::forward`, which adds it as a per-request `auto_prepend_file` FastCGI param (plus a `YERD_LOGIN_USER` param) - so the injected bootstrap script only ever loads for this one already-token-validated request, never for an ordinary one. `auto_login` is only built when `login_prepend_script` is `Some` *and* a token was just consumed - the daemon's own `mint_wordpress_login_token` handler already refuses to mint a token at all when the prepend script is unavailable (see [`yerdd`](../binaries/yerdd)), so in practice the proxy never sees a valid token to consume while `login_prepend_script` is `None`.

## The `forward/` layer

All response bodies share one type so every path returns the same `Response`:

```rust
pub type BoxBody = http_body_util::combinators::BoxBody<bytes::Bytes, std::io::Error>;
```

with `empty_body()` (for 301/404/501/101) and `bytes_body(&'static [u8])` helpers.

### `static_file` - serving real files {#static\_file-serving-real-files}

Both lookup functions return a `StaticOutcome`: `Served(Response)`, `NotFound` (fall through to the front controller, same as a bare `None` before this type existed), or `SymlinkEscape { requested_path, resolved, allowed_root }` (the candidate resolved via symlink to somewhere outside the site's `document_root` - the caller turns this into a `403` via `symlink_escape_response`, never a silent fallthrough). The `403` body names only `requested_path`; `resolved` and `allowed_root` go to a `tracing::warn!` (target `yerd_proxy::static_file`) instead, since a site can be exposed beyond loopback via `yerd-tunnel` and absolute local paths shouldn't reach a remote client.

`static_file::try_serve` is the static short-circuit for the FastCGI backends. Given the served root, the site's `document_root`, and the request, it:

1. asks [`try_files::static_candidate`](#try_files-static-file-resolution) for a safe relative path (`NotFound` for `/`, directory requests, traversal, or a non-GET/HEAD method);
2. refuses PHP source (`is_php_source`) so a `.php` file is never returned as bytes;
3. joins the candidate onto the served root, **canonicalises**, and verifies the result is still inside the site's `document_root` - not just the served subdirectory, so e.g. Laravel's `public/storage -> ../storage/app/public` symlink is served normally even though it points outside `public/`. A candidate that canonicalises fine but lands outside `document_root` entirely is a `SymlinkEscape`; a candidate that simply doesn't exist is `NotFound`, unchanged;
4. on a hit, reads the file and returns `200 OK` with the `Content-Type` from `content_type_for` and the `Server: <PROXY_SERVER_ID>` header (a `HEAD` returns an empty body).

`static_file::try_serve_index` is the directory-index counterpart, tried next when `try_serve` misses. Given the same served root, `document_root`, and the request, it:

1. asks [`try_files::directory_candidate`](#try_files-static-file-resolution) for a safe relative directory path (`NotFound` for anything that isn't a directory-style request, or a non-GET/HEAD method);
2. joins the candidate onto the served root, canonicalises, and verifies it's still inside `document_root` and is actually a directory - an escaped directory candidate is reported immediately, since there's no other candidate to fall back to;
3. defers to the front controller (`NotFound`) if that directory contains `index.php` - the front controller always wins when present;
4. otherwise probes `index.html`, then `index.htm`: each candidate is joined onto the (already-canonical) directory and **re-canonicalised in its own right** against `document_root` before being served. If one candidate escapes but the other is servable, the servable one still wins - a `SymlinkEscape` is only reported once every candidate has been tried and none served.
5. on a hit, serves the file exactly like `try_serve` (same `Content-Type` lookup, `HEAD` handling, headers).

A `NotFound` result here means no index file exists (or `index.php` won) and the request falls through to `fcgi::forward` exactly as it did before this short-circuit existed.

### `script_file` - direct script execution {#script\_file-direct-script-execution}

`script_file::resolve_script` extends `cgi_params`'s "everything to `index.php`" front-controller policy with the `try_files $uri $uri/index.php` half of the classic WordPress/nginx policy: a real, more specific script wins over the site root's `index.php` when one exists.

```rust
pub async fn resolve_script(
    uri_path: &str,
    served_root: &Path,
    allowed_root: &Path,
) -> Option<PathBuf>
```

* Only called at all when `BackendResolver::allows_direct_script_execution(site)` returns `true` (see [`resolve_script_if_allowed`](#per-request-dispatch), which skips the filesystem check entirely otherwise) - a Laravel or plain-PHP site never reaches this function.
* Checks, in order: an exact non-directory match (`/wp-login.php` → `wp-login.php`), then - for a directory-style request - that directory's own index (`/wp-admin/` → `wp-admin/index.php`).
* Unlike `static_file`, this applies to **every HTTP method**, not just GET/HEAD - a real script like `wp-login.php` handles POST too. It never reads or serves file *content*, only decides which path FastCGI should be told to execute.
* Same canonicalise-and-check-containment discipline as `static_file`: a symlinked script that resolves outside `allowed_root` (`document_root`) is treated as not found (falls back to the root `index.php` policy) rather than handed to FastCGI.
* `None` (fall back to the site root's `index.php`, today's behavior for every framework with only one front controller) whenever there's no real, on-disk, non-directory `.php` file at the resolved path.

### `fcgi` - the PHP-FPM forwarder

`fcgi::forward` drives the full FastCGI exchange against PHP-FPM:

1. **Connect.** `open_backend` opens a `UnixStream` for `PhpFpm { socket }` (Unix only - non-Unix returns `ErrorKind::Unsupported`) or a `TcpStream` for `PhpFpmTcp { addr }`. The two are unified behind a `BackendStream` enum that implements `AsyncRead`/`AsyncWrite`. (`FrankenPhp` reaching this path is a `#[cold]` "dispatch bug" error.)
2. **BEGIN\_REQUEST** with `FCGI_RESPONDER`, `keep_conn = false`, `request_id = 1`.
3. **PARAMS** from `build_params`, chunked at `FCGI_MAX_PAYLOAD`, followed by a zero-length PARAMS terminator. The prelude is flushed before the body is drained.
4. **STDIN.** The request body is streamed frame-by-frame, chunked at `FCGI_MAX_PAYLOAD`, then a zero-length STDIN terminator. HTTP trailers are dropped (FastCGI cannot represent them).
5. **Read STDOUT/STDERR** until `END_REQUEST`. Each record's content and padding are read with `read_exact`; a `request_id != 1` yields `FcgiError::UnexpectedRequestId`. Any non-empty STDERR is logged at warn ("FPM stderr").
6. **Synthesise the response.** `parse_cgi_response` splits the CGI header block at the first `\r\n\r\n` or `\n\n`, translates `Status: NNN [Reason]` into the HTTP status (defaulting to `200 OK`), and copies the rest as the body. Headers that fail `HeaderName`/`HeaderValue` validation are silently skipped.

`upgrade_not_supported()` is the `501` response for upgrade attempts on a FastCGI backend.

### `http` - the FrankenPHP forwarder

`http::forward` connects to the FrankenPHP worker over TCP and uses **raw `hyper::client::conn::http1::handshake`** rather than `hyper-util`'s pooled `legacy` client - the comment notes the pooled client has historical upgrade gotchas and doesn't expose the upgraded socket cleanly. The driver connection runs in a detached task; the response body is re-boxed into `BoxBody` (mapping the hyper body error into `io::Error`).

### `upgrade` - the WebSocket/Upgrade tunnel

`upgrade::is_upgrade` detects `Connection: Upgrade` per RFC 9110 §7.8, handling comma-separated, case-insensitive tokens (`keep-alive, Upgrade`) and requiring the `Upgrade` header to be present.

`upgrade::forward` implements the hyper-1 upgrade dance:

1. Capture the client's upgrade future (`hyper::upgrade::on(&mut req)`) **before** moving the request upstream.
2. Open the backend connection with raw `http1::handshake().with_upgrades()`.
3. Rebuild the upstream request with an `Empty` body (bytes flow through the upgraded socket, not the body) and send it.
4. Capture the backend's upgrade future from the response.
5. Strip hop-by-hop headers (`strip_hop_by_hop` removes the fixed set - `connection`, `proxy-connection`, `keep-alive`, `te`, `transfer-encoding`, `trailer` - plus any tokens listed in `Connection:`, while preserving `Upgrade`, then re-inserts a fresh `Connection: upgrade`).
6. Return the `101` to the service so hyper flushes it to the client, then in a detached task `try_join!` both upgrade futures and `copy_bidirectional` the two `Upgraded` streams (each wrapped in `TokioIo`).

## Errors

`ProxyError` (`error.rs`) is `#[non_exhaustive]` and intentionally not `Clone`/`Eq` (it wraps `io::Error`, `hyper::Error`, `rustls::Error`, and a boxed `dyn Error`). Variants: `Accept`, `BackendResolver { host, source }`, `BackendConnect { backend, source }`, `BackendProtocol`, `Upgrade`, `Fcgi` (`#[from] FcgiError`), `Hyper`, and `Tls`. The daemon translates these to a stable code when crossing the IPC wire - see the [IPC Protocol](../../developer/ipc-protocol).

## Tests and invariants

* **`pure/` unit tests** pin the wire format and policy: `fcgi_codec` round-trips headers and verifies short/long name-value encoding; `cgi_params` asserts the Caddy-style mapping, the `HTTPS=on` rule, and `HTTP_*` translation; `redirect` runs the full host/port table.
* **`tests/integration_http.rs`** drives `ProxyServer::serve` against a fake FastCGI listener and a hyper client, asserting both the round-trip body (`hello`) and the captured CGI params (`REQUEST_METHOD`, `REQUEST_URI`, `SCRIPT_NAME`, `PATH_INFO`, `QUERY_STRING`, `SERVER_NAME`). It also covers the `404` (unknown host) and `400` (missing Host) paths, plain static-file serving, and the directory-index fallback end to end: `index.html`/`index.htm` served when there's no `index.php`, `index.php` winning when both are present (asserted via the captured `SCRIPT_NAME`, not just the response body), a directory with no index of any kind and a nonexistent directory both still falling through to FastCGI, `HEAD` returning an empty body, and a symlinked `index.html` escaping the served root being refused rather than served.
* **`tests/integration_https.rs`** issues a real CA + leaf from [`yerd-tls`](./yerd-tls), serves over TLS with a single-host `CertStore`, and drives a rustls hyper client through the full SNI handshake to the fake backend.
* **`tests/no_runtime_deps.rs`** is a dependency-graph guard: it walks `cargo metadata` and asserts the runtime graph never pulls `anyhow`, the OpenSSL/native-tls family, `hyper-tls`, `tokio-native-tls`, or `webpki-roots`, and that `hyper`, `rustls`, `tokio`, and `time` each resolve to a single version. This keeps the proxy on a pure-Rust, rustls-only TLS stack.

## See also

* [yerd-tls](./yerd-tls) - the CA and leaf issuance that backs the daemon's `CertStore`.
* [yerd-php](./yerd-php) - the PHP-FPM supervisor whose `Listen` the daemon translates into a `Backend`.
* [yerd-platform](./yerd-platform) - `PortBinder`/`bind_pair` and the rootless port fallback.
* [yerdd (daemon)](../binaries/yerdd) - the binary that binds the ports, builds the `CertStore`/`BackendResolver`, and calls `ProxyServer::serve`.
* Source: [github.com/forjedio/yerd](https://github.com/forjedio/yerd)

---

---
url: 'https://yerd.app/developer/crates/yerd-supervise.md'
---
# yerd-supervise

`yerd-supervise` is the **process-agnostic supervision substrate** shared by
[`yerd-php`](./yerd-php) (FPM pools) and [`yerd-services`](./yerd-services)
(database / cache daemons). It holds the parts of process supervision that are
*not* specific to any particular supervised program:

* the **trait seams** the supervisor depends on (`ProcessSpawner`, `ChildHandle`,
  `Clock`, `HealthProbe`, `Downloader`);
* the production tokio-backed implementations of the infrastructure traits
  (`SystemClock`, `TokioProcessSpawner`, `TokioChild`);
* the generic [`Listen`](#the-listen-enum) address (Unix socket vs TCP loopback);
* and the **pure** supervision state machine (`supervisor`).

It depends on **nothing internal** - it sits at the bottom of the crate graph
next to [`yerd-core`](./yerd-core). It was extracted from `yerd-php` once a second
consumer (`yerd-services`) needed the same restart/health/backoff machinery with
*different* timing, so the state machine is parameterised by a per-call
[`SupervisorPolicy`](#supervisorpolicy) rather than baking constants in.

::: info Crate metadata
`description`: *Process-agnostic supervision substrate for Yerd.*
`#![forbid(unsafe_code)]`. No internal `yerd-*` dependencies. External deps:
`thiserror`, `async-trait`, `tokio` (process/net/rt/time/io-util/macros/sync), and
Unix-only `nix` (process-group signalling). The only async runtime is `tokio`
(supervision is intrinsically async).
:::

See also the [Crates overview](../crates), [`yerd-php`](./yerd-php), and
[`yerd-services`](./yerd-services).

## Module map

```text
src/
├── lib.rs          # re-exports + a compile-time Send+'static guard
├── error.rs        # DownloadError, ExitReason, SpawnFailureReason
├── listen.rs       # Listen enum (Unix socket vs TCP loopback)
├── traits.rs       # ProcessSpawner, ChildHandle, Clock, HealthProbe, Downloader
├── supervisor.rs   # the pure state machine (PoolState/Event/Action + SupervisorPolicy)
└── real.rs         # SystemClock, TokioProcessSpawner, TokioChild (prod impls)
```

`supervisor`, `listen`, and `error` are **pure**; `real` (and the trait impls)
own all I/O.

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## The trait seams

Every effect a supervisor needs is injected so the driving crate can be tested
with fakes - no real process spawns, no real sockets, no real clock. The
*definitions* live here; the production impls live in `real.rs`, while the
program-specific impls (`HealthProbe`, `Downloader`) live in the consuming crate
or in the daemon.

```rust
pub trait ProcessSpawner: Send + Sync + 'static {
    type Child: ChildHandle;
    fn spawn(&self, cmd: std::process::Command) -> Result<Self::Child, io::Error>;
}

#[async_trait]
pub trait ChildHandle: Send + 'static {
    fn id(&self) -> u32;
    fn try_wait(&mut self) -> Result<Option<ExitReason>, io::Error>;
    async fn wait(&mut self) -> Result<ExitReason, io::Error>;
    async fn kill(&mut self, signal: KillSignal, protocol: StopProtocol) -> Result<(), io::Error>;
}

pub trait Clock: Send + Sync + 'static {
    fn now(&self) -> std::time::Instant;
}

#[async_trait]
pub trait HealthProbe: Send + Sync + 'static {
    async fn probe(&self, listen: &Listen) -> Result<(), io::Error>;
}

#[async_trait]
pub trait Downloader: Send + Sync + 'static {
    async fn download(&self, url: &str) -> Result<Vec<u8>, DownloadError>;
}
```

`ProcessSpawner::spawn` takes a `std::process::Command` (not a tokio one) so the
trait itself stays runtime-free; the production impl converts internally.

::: warning Process-group signalling (Unix)
`ChildHandle::kill` takes a [`StopProtocol`](#stopprotocol) so a supervisor can
choose between signalling the **process group** (the default - reaps workers
along with the master) and signalling the master process only. `TokioProcessSpawner`
sets `process_group(0)` at spawn time, so the child's PID is also the
process-group ID. `real::TokioChild::kill` then uses `nix` `killpg` for a group
signal. On Windows both signals collapse to `tokio::process::Child::kill`, and
children are taken down by tokio's `kill_on_drop(true)`.
:::

::: tip The `Downloader` seam keeps `reqwest` out of the libraries
`Downloader` is transport-agnostic - only `async-trait`, no `reqwest`. The real
`reqwest`-backed implementation lives in the daemon (`bin/yerdd`); tests inject a
fake. `DownloadError` carries a flattened message string rather than wrapping a
transport type, so a test fake can construct it without pulling in `reqwest`.
**Checksum verification of the fetched bytes is the caller's job, not the
downloader's.**
:::

## The pure state machine (`supervisor`)

`supervisor` is the heart of the crate: a pure transition function plus the data
types around it. Time enters as `Elapsed(Duration)` rather than `Instant::now()`,
so a test can construct any state without a real clock.

```rust
#[must_use]
pub fn transition(
    state: PoolState,
    event: Event,
    policy: &SupervisorPolicy,
) -> (PoolState, Action)
```

The timing/restart knobs are **not** baked in - they are supplied per call via
`policy`, so an FPM pool (fast to start, cheap to retry) and a database (slow
cold-boot, expensive to retry) drive the same logic with different tuning.

The five pool states:

```rust
pub enum PoolState {
    Stopped,
    Starting { attempts: u32, pid: Option<u32> },
    Running  { pid: u32 },
    Failed   { last_exit: ExitReason, attempts: u32 },
    Stopping { sigkilled: bool },
}
```

The driver feeds back `Event`s (`EnsureRequested`, `SpawnSucceeded`,
`HealthCheckOk`, `HealthCheckTick`, `Crashed`, `StopRequested`, `StopComplete`,
`StopTick`, `BackoffElapsed`) and receives one `Action` to execute (`None`,
`Spawn`, `HealthCheck`, `Backoff { wait }`, `Kill { signal }`,
`EmitError(ErrorTag)`).

### SupervisorPolicy

`SupervisorPolicy` carries the tunable knobs and ships two named profiles:

| Field | `fpm()` | `database()` | Meaning |
| --- | --- | --- | --- |
| `health_check_window` | 5 s | 60 s | Max total time `Starting` may persist before health-check timeout. |
| `backoff_initial` | 100 ms | 250 ms | First retry wait. |
| `backoff_max` | 10 s | 10 s | Cap; exponential doubling saturates here. |
| `max_restart_attempts` | 3 | 3 | Consecutive failures before `PermanentFailure`. |
| `stop_grace` | 2 s | 10 s | Window between SIGTERM and SIGKILL. |

`SupervisorPolicy::fpm()` is used by `yerd-php`; `SupervisorPolicy::database()`
by `yerd-services` (databases cold-boot slowly and are expensive to retry, so the
health window and stop grace are far wider).

`backoff_for(attempts, policy)` computes
`min(backoff_initial * 2^(attempts-1), backoff_max)`, saturating.

### StopProtocol

`StopProtocol` (default `GroupTerm`) selects how a stop is delivered:

* **`GroupTerm`** - SIGTERM to the whole process group (the usual case; reaps the
  master and its workers together). Used by FPM and by Redis/MySQL/MariaDB.
* **`MasterInterrupt`** - SIGINT to the master process only. Used by
  [`yerd-services`](./yerd-services) for PostgreSQL, whose postmaster treats SIGINT
  as a *fast shutdown*; a group signal would be wrong.

### Invariants

Several invariants are encoded directly in the transition table and asserted by
tests:

* A `HealthCheckOk` arriving **before** `SpawnSucceeded` is an out-of-order event
  and is ignored (state unchanged, `Action::None`).
* An operator `EnsureRequested` on a `Failed { MAX }` pool **resets the restart
  budget** to a fresh `Starting { 1, None }`.
* A `StopRequested` from `Failed` short-circuits straight to `Stopped` with no
  kill (there is no live child to signal).
* A catch-all arm maps every unhandled `(state, event)` pair to
  `(state, Action::None)` so the machine never panics.

## The `Listen` enum

A supervised process listens on either a Unix domain socket or a TCP loopback
address. `Listen` is the shared address type:

```rust
pub enum Listen {
    UnixSocket(PathBuf),     // Unix only
    TcpLoopback(SocketAddr), // always valid; required on Windows
}
```

Unlike most Yerd enums it is deliberately **not** `#[non_exhaustive]` -
exhaustive matching on the two cases is intended at every call site.

## Production impls (`real.rs`)

* **`SystemClock`** wraps `Instant::now()`.
* **`TokioProcessSpawner`** converts the std `Command` to a tokio one, sets
  `kill_on_drop(true)` (so a daemon crash takes its children with it), spawns, and
  reads the PID once.
* **`TokioChild`** wraps `tokio::process::Child`; its `try_wait` / `wait`
  translate `ExitStatus` into [`ExitReason`](#error-model) via
  `ExitReason::from_status`. Its `kill` honours both `KillSignal` (`Term` / `Kill`)
  and `StopProtocol`: on Unix it uses `nix` `killpg`/`kill` (group SIGTERM/SIGKILL,
  or master-only SIGINT for `MasterInterrupt`); the Windows path is a Phase-2 TODO
  that collapses to `Child::kill`.

## Error model

The crate owns three small, transport-free error/reason types reused by both
consumers:

* **`DownloadError`** (`#[non_exhaustive]`) - `Transport { url, reason }`, a
  flattened message so fakes need no `reqwest`.
* **`SpawnFailureReason`** (`#[non_exhaustive]`) - `BinaryNotFound`,
  `PermissionDenied`, `WaitFailed`, `Other`, plus `from_kind` to classify an
  `io::ErrorKind` (`NotFound → BinaryNotFound`, `PermissionDenied → PermissionDenied`,
  else `Other`).
* **`ExitReason`** (`#[non_exhaustive]`, `Hash`) - `Code(i32)`, `Signal(i32)`,
  `Unknown`, plus `from_status` (maps a Unix termination signal to `Signal`,
  otherwise the exit code, otherwise `Unknown`).

## Consumers

| Crate | Policy | Stop protocol | HealthProbe impl |
| --- | --- | --- | --- |
| [`yerd-php`](./yerd-php) | `fpm()` | `GroupTerm` | `FastCgiProbe` (FastCGI `GET_VALUES`) |
| [`yerd-services`](./yerd-services) | `database()` | `GroupTerm`, plus `MasterInterrupt` for Postgres | `ServiceProbes` (Redis PING, MySQL/MariaDB handshake, Postgres startup) |

Both crates include a compile-time `Send + 'static` guard over their production
manager instantiation, mirroring the guard in this crate's `lib.rs`.

---

---
url: 'https://yerd.app/developer/crates/yerd-php.md'
---
# yerd-php

`yerd-php` owns two responsibilities for the daemon:

1. **PHP-FPM pool supervision** - spawn one FPM master per installed PHP version, health-check it, restart it on crash with backoff, and tear it down cleanly.
2. **Version & release management** - discover the bundled PHP installs on disk and resolve which prebuilt static-PHP artifact to download for a requested major.minor.

The crate is consumed almost entirely by [`yerdd`](../binaries/yerdd) (the long-running daemon). It is structured so that every decision is unit-testable in memory and every byte of I/O lives behind an injected trait, which is why the test suite runs identically on every CI target - including ones with no live FPM binary.

::: info Crate metadata
`description`: *PHP-FPM pool supervision and version management for Yerd.*
`#![forbid(unsafe_code)]`. Default runtime graph deliberately excludes `anyhow`, `reqwest`, and any OpenSSL / `native-tls` variant - see [No runtime deps](#no-runtime-deps-test). The only async runtime is `tokio` (the supervisor is intrinsically async).
:::

See also the [Crates overview](../crates), [`yerd-platform`](./yerd-platform) (for `PlatformDirs` / `PortBinder`), and the user-facing [PHP Versions guide](../../guide/php-versions).

## Module map

The crate mirrors the `pure` / `io` split used across the Yerd workspace: all *decisions* are synchronous and runtime-free; all *effects* (sockets, processes, filesystem) sit behind a thin I/O layer or an injected trait.

```text
src/
├── lib.rs            # re-exports + a compile-time Send+'static guard
├── error.rs          # PhpError (re-exports ExitReason/etc. from yerd-supervise)
├── traits.rs         # re-export shim → yerd_supervise::traits::*
├── listen.rs         # AllocatedListen::plan (Listen itself comes from yerd-supervise)
├── pool.rs           # PoolConfig, ProcessManagerMode, dev_defaults
├── manager.rs        # PhpManager - the driver that runs the state machine
├── real.rs           # re-export shim → yerd_supervise (SystemClock, TokioProcessSpawner…)
├── release.rs        # artifact URL resolution from the distribution listing
├── version.rs        # discover_bundled - scan the on-disk install root
├── pure/
│   ├── fpm_conf.rs   # render_fpm_conf - PoolConfig → php-fpm.conf text
│   ├── supervisor.rs # re-export shim → yerd_supervise::supervisor::*
│   └── env_scrub.rs  # allowlist filter over an env snapshot
└── io/
    ├── atomic_write.rs   # tempfile + rename
    └── fastcgi_probe.rs  # FastCgiProbe - the production HealthProbe
```

::: info The supervision substrate moved to `yerd-supervise`
The trait seams (`ProcessSpawner`, `ChildHandle`, `Clock`, `HealthProbe`,
`Downloader`), the production tokio impls (`SystemClock`, `TokioProcessSpawner`,
`TokioChild`), the `Listen` type, and the **pure state machine** now live in
[`yerd-supervise`](./yerd-supervise) so [`yerd-services`](./yerd-services) can
reuse them. `yerd-php`'s `traits.rs` re-exports them, and `manager.rs` drives the
shared machine under `SupervisorPolicy::fpm()`. `yerd-php` itself now owns only the
PHP-specific pieces: FPM config rendering, the FastCGI health probe, release
resolution, and the manager.
:::

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## The `pure/` layer

Everything under `pure/` is synchronous, I/O-free, and trivially unit-testable. The driver in `manager.rs` and the helpers under `io/` are the only places that touch tokio, sockets, or the filesystem.

### `fpm_conf` - config rendering

`render_fpm_conf(&PoolConfig) -> String` produces the text of a `php-fpm.conf` file. The caller writes the returned string to disk (the function does no I/O).

```rust
#[must_use]
pub fn render_fpm_conf(cfg: &PoolConfig) -> String
```

The layout is a `[global]` block followed by one `[yerd-<version>]` pool block. A canonical render (pinned byte-for-byte by [`fpm_conf_golden`](#fpm-conf-golden-test)):

```ini
[global]
pid = /yerd/state/fpm-8.3-1234.pid
error_log = /yerd/state/fpm-8.3-1234.log
daemonize = no

[yerd-8.3]
listen = /yerd/run/fpm-8.3-1234.sock
pm = ondemand
pm.max_children = 16
clear_env = no
catch_workers_output = yes
```

Design decisions baked into the template:

| Key | Value | Rationale |
| --- | --- | --- |
| `daemonize` | `no` | Yerd supervises FPM in the foreground. `--nodaemonize` is **not** also passed on the CLI - the config file is the single source of truth. |
| `clear_env` | `no` | Deliberate: the manager pre-scrubs the environment via [`env_scrub::allowlist`](#env_scrub-the-security-boundary) before spawn, rather than letting FPM do its own (more aggressive) scrub. The allowlist is the security boundary. |
| `catch_workers_output` | `yes` | Worker stdout/stderr is captured into `error_log` for diagnostics. |
| pool name | `yerd-<version>` | Disambiguates pools by version (e.g. `[yerd-8.3]`). |

The `listen` value is rendered by `render_listen`: a `Listen::UnixSocket` writes its path verbatim; a `Listen::TcpLoopback` writes the `127.0.0.1:<port>` literal. The `pm` value comes from `render_pm`: `Static -> "static"`, `Dynamic -> "dynamic"`, `OnDemand -> "ondemand"`.

After the standard pool keys, `render_fpm_conf` appends global PHP ini directives from `cfg.ini`. Each `(key, value)` is **re-validated defensively** even though the daemon already validates on set:

```rust
for (key, value) in &cfg.ini {
    if let Some(directive) = yerd_core::php_settings::directive(key) {
        if yerd_core::php_settings::validate_value(key, value).is_ok() {
            let _ = writeln!(out, "{directive}[{key}] = {value}");
        }
    }
}
```

`directive()` picks `php_value` vs `php_flag`. Because this module is *pure*, it cannot log - so an unsupported key or unsafe value is silently skipped rather than written raw into the FPM master config. The tests confirm `php_value[memory_limit] = 512M` / `php_flag[display_errors] = On` rendering and that `not_a_setting` (unsupported) and `256M; evil` (unsafe value) never reach the output.

### `supervisor` - the pool state machine

The supervisor state machine is the heart of supervision, but it now lives in [`yerd-supervise`](./yerd-supervise) (`yerd_supervise::supervisor`) so the services crate can reuse it. It is a pure transition function plus the data types around it. Time enters as `Elapsed(Duration)` rather than `Instant::now()`, so a test can construct any state without a real clock. The timing/restart knobs are passed per call via a `SupervisorPolicy`, and `yerd-php` always supplies `SupervisorPolicy::fpm()`.

```rust
#[must_use]
pub fn transition(
    state: PoolState,
    event: Event,
    policy: &SupervisorPolicy,
) -> (PoolState, Action)
```

The five pool states:

```rust
pub enum PoolState {
    Stopped,
    Starting { attempts: u32, pid: Option<u32> },
    Running  { pid: u32 },
    Failed   { last_exit: ExitReason, attempts: u32 },
    Stopping { sigkilled: bool },
}
```

The driver feeds back `Event`s (`EnsureRequested`, `SpawnSucceeded`, `HealthCheckOk`, `HealthCheckTick`, `Crashed`, `StopRequested`, `StopComplete`, `StopTick`, `BackoffElapsed`) and receives one `Action` to execute (`None`, `Spawn`, `HealthCheck`, `Backoff { wait }`, `Kill { signal }`, `EmitError(ErrorTag)`).

The `SupervisorPolicy::fpm()` profile `yerd-php` uses:

| Field | Value | Meaning |
| --- | --- | --- |
| `health_check_window` | 5 s | Max total time `Starting` may persist before health-check timeout. |
| `backoff_initial` | 100 ms | First retry wait. |
| `backoff_max` | 10 s | Cap; exponential doubling saturates here. |
| `max_restart_attempts` | 3 | Consecutive failures before `PermanentFailure`. |
| `stop_grace` | 2 s | Window between SIGTERM and SIGKILL. |

(The other profile, `SupervisorPolicy::database()`, has a far wider 60 s window and 10 s stop grace - that one is used by [`yerd-services`](./yerd-services).)

`backoff_for(attempts, policy)` computes `min(backoff_initial * 2^(attempts-1), backoff_max)`, saturating. The table test pins the fpm profile: `1→100ms, 2→200ms, 3→400ms, … 7→6.4s, 8→10s, 100→10s`.

A walk through the key transitions:

```mermaid
stateDiagram-v2
    [*] --> Stopped
    Stopped --> Starting: "EnsureRequested / Spawn"
    Starting --> Starting: "SpawnSucceeded(pid) / HealthCheck"
    Starting --> Running: "HealthCheckOk / None (terminal)"
    Starting --> Starting: "HealthCheckTick under 5s / HealthCheck"
    Starting --> Starting: "HealthCheckTick at or over 5s / Kill(Term)"
    Starting --> Failed: "Crashed(r) / Backoff"
    Running --> Failed: "Crashed(r) / Backoff"
    Running --> Running: "EnsureRequested / None (idempotent)"
    Failed --> Starting: "BackoffElapsed when attempts under MAX / Spawn"
    Failed --> Failed: "BackoffElapsed at MAX / EmitError(PermanentFailure)"
    Failed --> Starting: "EnsureRequested / Spawn (operator reset)"
    Running --> Stopping: "StopRequested / Kill(Term)"
    Starting --> Stopping: "StopRequested / Kill(Term)"
    Failed --> Stopped: "StopRequested / None (no live child)"
    Stopping --> Stopping: "StopTick at or over 2s / Kill(Kill)"
    Stopping --> Stopped: "StopComplete / None (terminal)"
```

Several invariants are encoded directly in the table and asserted by tests:

* A `HealthCheckOk` arriving **before** `SpawnSucceeded` is treated as an out-of-order event and ignored (state unchanged, `Action::None`).
* An operator `EnsureRequested` on a `Failed{MAX}` pool **resets the restart budget** to a fresh `Starting{1, None}`.
* A `StopRequested` from `Failed` short-circuits straight to `Stopped` with no kill (there is no live child to signal).
* A catch-all arm maps every unhandled `(state, event)` pair to `(state, Action::None)` so the machine never panics. The `no_accidental_transitions` test pins two of these (e.g. `Stopped + HealthCheckTick` stays `Stopped`).

### `env_scrub` - the security boundary

Because the FPM config sets `clear_env = no`, the manager is responsible for handing FPM an already-scrubbed environment. `env_scrub::allowlist` is pure - it takes a snapshot slice and never reads `std::env` itself (the caller snapshots before invoking).

```rust
#[must_use]
pub fn allowlist(snapshot: &[(String, String)]) -> Vec<(String, String)>
```

Retained keys:

* **Exact:** `PATH`, `HOME`, `USER`, `LANG`
* **Prefix:** `LC_`, `XDEBUG_`, `PHP_`

Everything else (e.g. `AWS_SECRET_ACCESS_KEY`, `SECRET_KEY`) is dropped. Matching is case-sensitive - `xdebug_lower` and `LANG_OVERRIDE` are *not* kept. The output preserves the input ordering.

## The `io/` layer

These helpers do filesystem and socket work and are therefore deliberately *not* in `pure/`.

### `atomic_write`

```rust
pub fn write(path: &Path, bytes: &[u8]) -> io::Result<()>
```

Writes via a `tempfile::NamedTempFile` in the same directory followed by `persist` (rename). If `path`'s parent does not exist it returns `io::ErrorKind::NotFound` rather than attempting `create_dir_all` - directory creation is the caller's contract. (It is inlined here rather than reused from `yerd-config` because that crate's equivalent is `pub(crate)`.)

### `fastcgi_probe` - the production `HealthProbe`

`FastCgiProbe` is the real liveness check. It opens a stream to the pool's listen address, writes a single 8-byte `FCGI_GET_VALUES` request (an empty-body FastCGI record), and reads back exactly one 8-byte record header. The reply is accepted only if its version byte equals `FCGI_VERSION_1` (`1`):

```rust
const FCGI_VERSION_1: u8 = 1;
const FCGI_GET_VALUES: u8 = 9;
// request header: [version, type, idB1, idB0, lenB1, lenB0, padLen, reserved]
let header: [u8; 8] = [FCGI_VERSION_1, FCGI_GET_VALUES, 0, 0, 0, 0, 0, 0];
```

Validating the version byte is what lets the probe distinguish *"FPM answered"* from *"a TCP accept queue with nothing behind it"* - a Windows edge case where a connection can succeed without an FPM master. A short read surfaces as `UnexpectedEof`; a wrong version byte surfaces as `io::ErrorKind::Other`. On a non-Unix target a `Listen::UnixSocket` is rejected as `Unsupported`.

## The trait seams

Every effect the supervisor needs is injected so the driver can be tested with fakes - no real process spawns, no real sockets, no real clock. The trait *definitions* live in [`yerd-supervise`](./yerd-supervise) and are re-exported by `yerd-php`'s `traits.rs`; `yerd-php`'s production impls are the `FastCgiProbe` `HealthProbe` and (from `yerd-supervise`) `TokioProcessSpawner` / `SystemClock`.

```rust
pub trait ProcessSpawner: Send + Sync + 'static {
    type Child: ChildHandle;
    fn spawn(&self, cmd: std::process::Command) -> Result<Self::Child, io::Error>;
}

#[async_trait]
pub trait ChildHandle: Send + 'static {
    fn id(&self) -> u32;
    fn try_wait(&mut self) -> Result<Option<ExitReason>, io::Error>;
    async fn wait(&mut self) -> Result<ExitReason, io::Error>;
    async fn kill(&mut self, signal: KillSignal, protocol: StopProtocol) -> Result<(), io::Error>;
}

pub trait Clock: Send + Sync + 'static {
    fn now(&self) -> std::time::Instant;
}

#[async_trait]
pub trait HealthProbe: Send + Sync + 'static {
    async fn probe(&self, listen: &Listen) -> Result<(), io::Error>;
}

#[async_trait]
pub trait Downloader: Send + Sync + 'static {
    async fn download(&self, url: &str) -> Result<Vec<u8>, DownloadError>;
}
```

`ChildHandle::kill` takes a `StopProtocol` (FPM uses the default `GroupTerm` - SIGTERM to the whole process group). The error/reason types `ExitReason`, `SpawnFailureReason`, and `DownloadError` also live in `yerd-supervise`; `yerd-php`'s `error.rs` keeps only `PhpError`, which wraps them.

`ProcessSpawner::spawn` takes a `std::process::Command` (not a tokio one) so the trait itself stays runtime-free; the production impl converts internally.

::: warning Process-group signalling (Unix)
`ChildHandle::kill` signals the **process group** on Unix, not just the master PID. `TokioProcessSpawner` sets `process_group(0)` at spawn time (via the manager's `build_cmd`), so the child's PID is also the process-group ID, and `real::TokioChild::kill` calls `nix::sys::signal::killpg`. This is what reaps the FPM workers along with the master. **Never refactor the Unix impl to `kill(pid)` - that would leak workers.** On Windows both signals collapse to `tokio::process::Child::kill`, and workers are taken down by tokio's `kill_on_drop(true)`; a future ticket adds job-object teardown via the helper.
:::

### The `Downloader` seam and offline tests

`yerd-php` is dependency-light on purpose. The `Downloader` trait is transport-agnostic - only `async-trait`, no `reqwest`. The real `reqwest`-backed implementation lives in the daemon (`bin/yerdd`), and tests inject a fake. `DownloadError` carries a *flattened* message string rather than wrapping a transport type, so a test fake can construct it without pulling in `reqwest`. **SHA-256 verification of the fetched bytes is the caller's job, not the downloader's.**

### Production impls (`real.rs`)

`SystemClock` wraps `Instant::now()`. `TokioProcessSpawner` converts the std `Command` to a tokio one, sets `kill_on_drop(true)` (so a daemon crash takes FPM with it), spawns, and reads the PID once. `TokioChild` wraps `tokio::process::Child`; its `try_wait` / `wait` translate `ExitStatus` into `ExitReason` via `ExitReason::from_status` (which maps a Unix termination signal to `ExitReason::Signal`, otherwise the exit code, otherwise `Unknown`).

## The `Listen` enum: Unix socket vs TCP loopback

FPM listens on either a Unix domain socket or a TCP loopback address. `Listen` now lives in [`yerd-supervise`](./yerd-supervise) (re-exported here); `AllocatedListen::plan` - the PHP-specific planning around it - stays in `yerd-php`'s `listen.rs`.

```rust
pub enum Listen {
    UnixSocket(PathBuf),   // Unix only
    TcpLoopback(SocketAddr), // always valid; required on Windows
}
```

`Listen` is deliberately **not** `#[non_exhaustive]` - exhaustive matching on the two cases is intended. `AllocatedListen::plan` is the planner-side entry. The daemon calls it before rendering the pool config, then bakes the resolved address into the template. Its behaviour is `cfg`-split:

* **Unix:** returns `Listen::UnixSocket(dirs.runtime / "fpm-<version>-<instance_id>.sock")`. No socket is created yet - FPM creates it itself on start. The `PortBinder` argument is ignored (a Unix test stub panics if `bind` is ever called).
* **Windows:** Windows has no FPM Unix sockets, so the planner binds `127.0.0.1:0` via the supplied `PortBinder`, captures the resolved port, **drops** the listener, and returns `Listen::TcpLoopback`.

::: warning The Windows drop-then-rebind race
There is no portable way to inherit an open `TcpListener` into the FPM child, so the planner must bind-find-port, drop, and let FPM rebind. That window is racy, so `PhpManager::ensure` retries `AllocatedListen::plan` up to `MAX_BIND_ATTEMPTS` (5). On Unix this loop runs at most once because no binding happens.
:::

The `instance_id` is the daemon's `std::process::id()`. It is embedded into Unix socket (and pid/log/config) basenames so concurrent Yerd daemons on the same host never clobber each other. On Windows it isn't embedded - the kernel assigns a unique ephemeral port - but the parameter shape stays uniform.

## `PoolConfig` and `PhpManager`

`PoolConfig` (`#[non_exhaustive]`) is the input to `render_fpm_conf`. `PoolConfig::dev_defaults(version, listen, dirs, instance_id)` builds a sane local-dev config: `pm = OnDemand`, `max_children = 16` (enough for Laravel + Vite + several tabs), pid/log under `dirs.state`, config under `dirs.config`, all basenames embedding both version and instance id. Its `extension: Option<PathBuf>` and `ini_defines: Vec<(String, String)>` fields are populated by `ensure` from `DumpExtSettings` (see [Dump-extension loading](#dump-extension-loading)) and become the `-d` arguments on the spawned command.

`PhpManager<S, C, P>` is generic over the `ProcessSpawner`, `Clock`, and `HealthProbe` seams; it holds one `Pool` per `PhpVersion` in a `BTreeMap` (so shutdown order is deterministic). `lib.rs` includes a compile-time assertion that the production instantiation is `Send + 'static`:

```rust
const _: () = {
    const fn assert_send_static<T: Send + 'static>() {}
    assert_send_static::<PhpManager<TokioProcessSpawner, SystemClock, FastCgiProbe>>();
};
```

### The driver

`PhpManager::drive` is the loop that pumps `transition` and performs the I/O each `Action` demands. Public entry points feed the initial event and `drive` runs the machine to a terminal state:

| Method | Behaviour |
| --- | --- |
| `ensure(v)` | Idempotent. Fast path: if the pool is `Running` and `try_wait` shows the child still alive, return the cached listen address. Otherwise plan the address, create parent dirs, render + atomically write the config, scrub the env, then drive from `Stopped` via `EnsureRequested`. Returns the `Listen`. |
| `restart(v)` | `stop` then `ensure` (stop errors are swallowed; the pool is gone from the map either way). |
| `stop(v)` | No-op if no pool. Drives from the stored state via `StopRequested`, then removes any leftover Unix socket file. |
| `shutdown()` | Stops every pool in `BTreeMap` key order, returning the first error encountered. |
| `snapshots()` | Read-only-intent status report (`&mut self` because `try_wait` needs `&mut`). Each pool is reported `Running` (with PID) only if its stored state is `Running` *and* the child is still alive; otherwise `Failed`. Does not reconcile the pool set. |
| `set_binaries(map)` | Replaces the known-binary map. A version installed at runtime (`yerd install php`) is invisible to a long-running manager until the daemon calls this. |
| `set_ini_settings(v)` | Replaces the global ini settings injected into each pool's config on the next `ensure`. |
| `set_dump_ext(opt)` | Configures (or, with `None`, disables) daemon-managed dump-extension loading. Takes effect on the next `ensure` / restart of a pool. |

The spawned command is assembled by `build_cmd`: `php-fpm --fpm-config <path>`, with `env_clear()` followed by the scrubbed allowlist, and `process_group(0)` on Unix. When dump-extension loading is active for the version, `build_cmd` prepends `-d extension=<so>` plus one `-d key=value` per ini define **before** `--fpm-config` (startup-INI overrides must precede it so they apply at PHP `MINIT`, which the extension needs to register its observers).

### Dump-extension loading

`PhpManager::set_dump_ext(Option<DumpExtSettings>)` wires the Laravel ▸ Dumps extension into FPM pools. `DumpExtSettings` is:

```rust
pub struct DumpExtSettings {
    pub so_dir: PathBuf,                  // base dir of per-version extensions
    pub ini_defines: Vec<(String, String)>, // extra -d key=value defines
}
```

On each `ensure`, if `dump_ext` is set the manager probes for `so_dir/php-<version>/yerd-dump.so`. When that file exists, the pool spawns with `-d extension=<so>` plus one `-d key=value` per entry in `ini_defines` (e.g. `yerd_dump.state_path=<path>`).

::: warning It is `extension=`, not `zend_extension=`
The yerd-dump build is a regular PHP extension, so the spawn code emits `-d extension=<so>` - **not** `-d zend_extension=<so>`. A stale code comment on `set_dump_ext` still says `zend_extension`; the authoritative behaviour is the `build_cmd` body, which writes `extension={so}`. Document and rely on `extension=`.
:::

The probe gates **only on the `.so` being present**, not on the `dumps.enabled` config flag. The extension self-disables via its on-disk state file, so the daemon loads it into every pool whenever a matching artifact exists and lets the extension decide per-request whether to capture. Toggling `dumps.enabled` rewrites the state file rather than restarting FPM.

::: details Driver invariants (from manager.rs)
Inside `drive`, the events fed into `transition` never produce `Action::None` in a *non-terminal* state. The `Action::None` arm returns the running child (`Outcome::Running`) or `Stopped`, and **panics** on any other state as an explicit invariant violation. The driver never re-feeds `EnsureRequested` mid-loop, and never feeds `StopTick` after a SIGKILL (the SIGKILL path waits unconditionally and feeds `StopComplete`). `ensure` cleans a stale socket before spawn and `stop` removes it on the way out - the only two serialisation points against stale sockets.

During `HealthCheck`, the driver `tokio::select!`s the FastCGI probe (wrapped in a 500 ms `HEALTH_PROBE_TIMEOUT`) against `child.wait()`. If the child wins the race, that becomes a `Crashed` event; a 100 ms `HEALTH_PROBE_GAP` floor between retries prevents hot-spinning on connection-refused.
:::

## Error model

`PhpError` (`#[non_exhaustive]`) is intentionally **not** `Clone + Eq` because it wraps `std::io::Error` and `yerd_platform::PlatformError`. Its variants pin the operational failure surface: `VersionNotInstalled`, `DiscoveryIo`, `Spawn { reason: SpawnFailureReason, .. }`, `ConfigWrite`, `HealthCheckTimedOut`, `PermanentFailure`, `Bind` (Windows-only listen allocation), `Kill`, `UnsupportedPlatform`, `VersionUnavailable`, `Download(DownloadError)`, and `Extract`.

`SpawnFailureReason::from_kind` classifies an `io::ErrorKind`: `NotFound → BinaryNotFound`, `PermissionDenied → PermissionDenied`, anything else `→ Other` (plus `WaitFailed` for a wait that fails mid-supervision). `ExitReason` (`Code(i32)`, `Signal(i32)`, `Unknown`) implements `Hash` so callers can aggregate exits for telemetry.

## Version & release handling

::: tip PHP is downloaded, not bundled
Yerd does not ship PHP. It downloads prebuilt, statically-linked PHP builds that Yerd publishes itself (the `forjedio/yerd-php` build repo) on demand when you run `yerd install php`. Those builds link libcurl **without c-ares** so PHP resolves Yerd's scoped `.test` resolver, and ship the **bulk** extension set (glibc on Linux) so common Laravel needs like `intl`, `sodium`, and `mysqli` are included. See the [PHP Versions guide](../../guide/php-versions).
:::

### `release.rs` - pure manifest resolution

Supported versions come from Yerd's signed `php.json` manifest. The daemon fetches `php.json` + its detached `php.json.minisig`, **verifies the minisign signature** (at the I/O edge, against the embedded `PHP_LISTING_PUBLIC_KEY`), then hands the trusted JSON body to the pure functions here. Each build also carries a per-tarball SHA-256 (verified after download) and a `revision` (`-N`) counter:

::: info Legacy channel: a second, independently-signed manifest
A `Channel { Stable, Legacy }` enum picks which manifest a version is sourced
from: `Channel::of(version)` derives it from `PhpVersion::is_legacy` (the same
`< 8.2` cutoff as `MIN_SUPPORTED` / `yerd_core::FIRST_SUPPORTED_MINOR`), so there
is exactly one boundary in the codebase. `Channel::Stable` maps to `php.json`;
`Channel::Legacy` maps to a second manifest, `php-legacy.json`, hosted alongside
it on the same rolling release with the **same schema**, the **same** embedded
minisign key, and the **same** per-tarball SHA-256 verification - only the
listing URL differs (`listing_url` / `listing_sig_url` now take a `Channel`).
`resolve_from_listing` and `available_minors` filter their input listing by
`Channel::of(version) == channel`, so a legacy minor never resolves off the
stable manifest and vice versa. See the [PHP Versions guide](../../guide/php-versions#legacy-php-versions)
for the user-facing restrictions this backs.
:::

| Function | Purpose |
| --- | --- |
| `resolve_from_listing(listing, version, os, arch, channel)` | Selects the single `(minor, os, arch)` build and returns an `Artifact` with `cli_url`/`fpm_url`, their `sha256`s, and the `revision`. Errors `VersionUnavailable` if none match (including when `Channel::of(version) != channel`), or `UnsupportedListingSchema` / `ListingParse` on a bad manifest. |
| `available_minors(listing, os, arch, channel)` | Every distinct major.minor with a build for the platform whose channel matches, sorted + deduped. Feeds the GUI dropdown / `yerd list php`. |
| `listing_url(channel)` / `listing_sig_url(channel)` | URLs of the channel's manifest (`Channel::Stable` → `php.json`, `Channel::Legacy` → `php-legacy.json`) and its detached signature. |
| `is_safe_member(name)` | Zip-slip guard: a tar member is trusted only if relative with no `..`, root, or prefix components. |
| `is_newer_build` / `patch_of` / `display_build` | Build-level `(patch, revision)` comparison for update checks, and the `<patch>-<revision>` display string. |

`Os` is `Linux | Macos` and `Arch` is `X86_64 | Aarch64` (the `std::env::consts` spellings the manifest uses); `current_os_arch()` errors with `UnsupportedPlatform` on anything else (e.g. Windows, 32-bit) and must be called before any download. The `revision` dimension is what makes a rebuild of an unchanged patch (e.g. the c-ares cutover, `8.5.7-1`) reach an existing install: a pre-cutover install recorded as revision 0 is offered the `-1` rebuild.

`BinaryKind` (`Cli` / `Fpm`) maps to install layout: CLI installs to `bin/php`, FPM to `sbin/php-fpm`, and the archive members are named `php` / `php-fpm`.

### `version.rs` - bundled discovery

`discover_bundled(&PlatformDirs)` walks `dirs.data / "php"` for per-version FPM binaries and returns `(PhpVersion, PathBuf)` tuples sorted by version. The daemon calls it at startup to populate the manager's `binaries` map.

It is now also the single source of truth for **cover-shim reconciliation**: the daemon (`bin/yerdd`) takes one `discover_bundled` snapshot and uses it to build and prune the `{data}/bin` shim set - including the per-version `php<X.Y>cover` (and `phpcover`) symlinks that front pcov-enabled coverage runs. A single snapshot drives both create and prune so the scan can't straddle a concurrent install. The shim-building/pruning logic itself lives in `bin/yerdd` (`php_install::reconcile_shims`), not in this crate; `yerd-php` only provides `discover_bundled` (version enumeration) plus the PHP install/layout primitives it builds on.

```text
{dirs.data}/php/php-8.3/sbin/php-fpm     (Unix)
{dirs.data}\php\php-8.3\php-fpm.exe      (Windows)
```

A directory whose name doesn't parse as `php-<maj>.<min>` (case-insensitive prefix) is skipped, as is one with no FPM binary present. A missing root returns `Ok(vec![])` (empty install); any other `read_dir` error becomes `DiscoveryIo`.

## Tests & invariants

The test suite is split between in-module unit tests and three integration tests under `tests/`.

### `supervisor_states` test

End-to-end driver coverage using fakes for `ProcessSpawner`, `Clock`, `HealthProbe`, and `ChildHandle`. A `FakeChild` is programmed with `ChildBehavior::{Crashes, Lives, LivesUntilKilled}`; `FakeProbe` replays a programmed sequence of probe outcomes. The cases exercise the happy path (`ensure` returns the listen address and is idempotent), crash + recovery (crash once, second spawn lives), permanent failure (`MAX_RESTART_ATTEMPTS` crashes → `PermanentFailure`), clean stop (a `LivesUntilKilled` child receives a SIGTERM), runtime install visibility via `set_binaries`, and parent-dir creation for logs. Live FPM coverage lives in the daemon's integration suite so this test stays fakes-only and passes on every CI target.

### `fpm_conf_golden` test

A byte-exact golden test that pins the rendered FPM config format. Future template edits must flip this test deliberately.

### `no_runtime_deps` test {#no-runtime-deps-test}

A dependency-graph invariant, modelled on the equivalent in `yerd-platform`. It runs `cargo metadata --locked --filter-platform <host>`, walks the normal-dependency graph reachable from `yerd-php`, and asserts that none of `anyhow`, `reqwest`, `openssl`, `openssl-sys`, or `native-tls` appear, and that `tokio` resolves to a single version. This is the machine-checked guarantee behind "downloads go through the `Downloader` trait; no `reqwest` in the default graph."

---

---
url: 'https://yerd.app/developer/crates/yerd-mail.md'
---
# yerd-mail

`yerd-mail` is Yerd's built-in **mail-capture SMTP sink** plus the **on-disk
store** behind it. Herd-style: the daemon runs a tiny SMTP server on a loopback
port, writes everything it receives as a raw `.eml` file, and surfaces each
message (decoded) to the GUI and CLI for inspection. There is no relaying -
**captured mail never leaves the box**.

The crate is consumed by [`yerdd`](../binaries/yerdd) (the long-running daemon),
which opens the store at startup, optionally binds the listener, and answers the
mail [IPC requests](./yerd-ipc) by reading and mutating the store.

::: info Crate metadata
`description`: *Built-in mail-capture SMTP server + on-disk store for Yerd
(Herd-style).* `#![forbid(unsafe_code)]`. Depends on [`yerd-ipc`](./yerd-ipc) (for
the owned wire types `MailSummary` / `MailDetail` / `MailHeader`) and
[`mail-parser`](https://github.com/stalwartlabs/mail-parser) - a pure-Rust MIME
parser with no C dependencies. The only async runtime is `tokio`.
:::

See also the [Crates overview](../crates), [`yerd-ipc`](./yerd-ipc) (the request /
response types), and the user-facing [Mail Capture guide](../../guide/mail).

## Module map

The crate mirrors the `pure` / `io` split used across the Yerd workspace: all
*decisions* (the SMTP command state machine, MIME decoding, retention policy) are
synchronous and I/O-free; all *effects* (the TCP server, the disk store) sit in a
thin I/O layer.

```text
src/
├── lib.rs            # re-exports + the purity-boundary doc
├── error.rs          # MailError (Bind / Io / Index)
├── pure/
│   ├── smtp.rs       # Session - the SMTP receiver state machine + RawMessage
│   ├── mime.rs       # summary() / detail() - decode an .eml into owned wire types
│   └── retention.rs  # evict_count() + DEFAULT_CAP
└── io/
    ├── server.rs     # bind() / serve() - the tokio SMTP accept loop
    └── store.rs      # Store - the on-disk .eml store + index.json cache
```

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## Public API

Everything is re-exported from `lib.rs`:

```rust
pub use error::MailError;
pub use io::server::{bind, serve};
pub use io::store::Store;
pub use pure::smtp::RawMessage;
```

| Item | Layer | Role |
|------|-------|------|
| `bind(port)` | io | Bind the loopback SMTP listener; returns a `TcpListener`. |
| `serve(listener, store, shutdown)` | io | Accept loop: drive a `Session` per connection and persist each message. |
| `Store` | io | The on-disk `.eml` store + `index.json` metadata cache. |
| `RawMessage` | pure | One captured message: envelope + verbatim dot-unstuffed body. |
| `MailError` | - | The crate's error type. |

## The `pure/` layer

Everything under `pure/` is synchronous, I/O-free, and unit-testable without
sockets or a filesystem. `smtp.rs` owns no sockets; `mime.rs` takes a byte slice
and returns owned types; `retention.rs` is a single arithmetic function.

### `smtp` - the SMTP receiver state machine

`Session` speaks just enough of RFC 5321 to capture mail from a local app's
mailer: `EHLO`/`HELO`, `MAIL FROM`, `RCPT TO`, `DATA`, `RSET`, `NOOP`, `QUIT`.
There is **no AUTH, no TLS, and no relaying** - every recipient is accepted and the
body is captured verbatim. The module owns no I/O: the server reads a line, calls
`Session::command`, and acts on the returned `Reply`.

```rust
pub fn command(&mut self, line: &str) -> Reply;
pub fn finish_data(&mut self, data: &[u8]) -> RawMessage;
```

`Reply` tells the I/O layer what to do next:

```rust
pub enum Reply {
    Line(String),       // write this reply, keep reading commands
    StartData(String),  // write this reply, then collect DATA until \r\n.\r\n
    Close(String),      // write this reply, then close (QUIT)
}
```

The command surface and the replies it emits:

| Verb | Reply | Notes |
|------|-------|-------|
| `HELO` / `EHLO` | `250 yerd` | Greeting on connect is `220 yerd mail capture ready`. |
| `MAIL` | `250 OK` | Begins a new transaction: clears any leftover recipients so an abandoned prior envelope can't leak into this message. |
| `RCPT` | `250 OK` | Address pushed in order; all recipients accepted. |
| `DATA` | `354 …` (`StartData`) or `503 RCPT first` | Refuses with `503` when no recipient has been given. |
| `RSET` | `250 OK` | Clears `from` and recipients. |
| `NOOP` | `250 OK` | |
| `QUIT` | `221 Bye` (`Close`) | |
| empty line | `500 Syntax error` | |
| anything else | `250 OK` | **Lenient catch-all**: a capture sink accepts whatever a dev mailer sends. |

`extract_address` pulls the address from between the angle brackets of
`MAIL FROM:<addr>` / `RCPT TO:<addr>`, falling back to the trimmed text after the
first `:` when there are no brackets.

`finish_data` is fed the bytes between the `354` and the terminating `\r\n.\r\n`
(that terminator already stripped by the server). It **dot-unstuffs** them via the
pure `unstuff` helper - undoing SMTP's RFC 5321 §4.5.2 transparency, where a body
line beginning with `.` is sent with an extra leading `.` - and returns a
`RawMessage`:

```rust
pub struct RawMessage {
    pub envelope_from: String,  // MAIL FROM address
    pub recipients: Vec<String>, // RCPT TO addresses, in order
    pub raw: Vec<u8>,            // dot-unstuffed body: an RFC 5322 message
}
```

`finish_data` also resets the envelope, so the same connection may send another
message.

### `mime` - decoding a captured `.eml`

`mail-parser` is a zero-copy parser - its output borrows the input via `Cow` and
lifetimes - so nothing it returns can cross the IPC wire or be stored directly.
This module clones every field out into owned `String` / `u64` values, producing
the owned [`yerd-ipc`](./yerd-ipc) wire types:

```rust
pub fn summary(id: &str, raw: &[u8]) -> MailSummary;  // metadata only
pub fn detail(id: &str, raw: &[u8]) -> MailDetail;    // headers + decoded bodies
```

* **`summary`** decodes only the envelope metadata (`from`, `to`, `subject`,
  `date_epoch`) - cheap, used to build the index entry on capture.
* **`detail`** decodes the full content: all header lines (sliced byte-exact from
  the raw message and UTF-8-lossy trimmed), the decoded text body, and the decoded
  HTML body.

Two decoding subtleties, both grounded in the source:

* **Genuine HTML only.** `mail-parser`'s `body_html` would *synthesise* HTML from a
  text-only message. `detail` only surfaces `html_body` when a real `text/html`
  part is present (checked via `is_html_part`), so a text-only message leaves
  `html_body` as `None` and a client falls back to `text_body`. This is what lets
  `yerd mail show` print "(HTML-only message …)" only when there genuinely is no
  text part.
* **`cid:` → `data:` rewrite.** When an HTML body references inline attachments by
  `cid:`, `rewrite_cids` replaces each `cid:<id>` (and `CID:<id>`) with an inline
  `data:<mime>;base64,<…>` URL built from the matching attachment, so a sandboxed
  viewer renders embedded images **without any network access**. A small local
  standard-alphabet `base64_encode` is inlined here rather than pulling a base64
  dependency for this one use.
* **Downloadable attachments.** `collect_attachments` walks `mail-parser`'s
  attachment list and keeps parts **without** a `Content-ID` (inline `cid:`
  images stay out of that list). Each part becomes a `MailAttachment` on
  `MailDetail` with filename, MIME type, size, and base64 `data`. The field is
  omitted on the wire when empty so older clients keep decoding.

### `retention` - bounding the store

```rust
pub const DEFAULT_CAP: usize = 200;
pub fn evict_count(current_len: usize, cap: usize) -> usize;
```

`evict_count` is a one-liner - `current_len.saturating_sub(cap)` - returning how
many of the **oldest** entries must be evicted to get back within the cap (zero
when already within bounds, assuming oldest-first ordering). The `Store` calls it
after every append.

## The `io/` layer

These edges do socket and filesystem work and are therefore deliberately outside
`pure/`.

### `server` - the tokio SMTP capture server

```rust
pub async fn bind(port: u16) -> Result<TcpListener, MailError>;
pub async fn serve<S>(listener: TcpListener, store: Arc<Store>, shutdown: S)
    -> Result<(), MailError>
where S: Future<Output = ()> + Send + 'static;
```

`bind` binds `127.0.0.1:<port>` (loopback only - never a routable address),
surfacing a bind failure as `MailError::Bind` (which the daemon treats as
non-fatal). `serve` is the accept loop: it `tokio::select!`s the `shutdown` future
against `listener.accept()` (`biased`, so shutdown wins), and `tokio::spawn`s a
per-connection task that drives the pure `Session`.

Per connection, `handle_conn`:

1. writes the `220` greeting,
2. reads command lines, feeding each to `Session::command` and writing the
   `Reply`,
3. on `StartData`, reads the body via `read_data` until the `\r\n.\r\n` marker,
   calls `Session::finish_data`, and `store.append`s the raw bytes - replying
   `250 OK: queued` on success or `451 storage error` if the store write failed.

`read_data` enforces a defensive `MAX_MESSAGE_BYTES` cap (25 MiB). Once a message
goes oversized it stops *appending* but keeps *consuming* lines until the
terminating dot, so a truncated body is never re-read as SMTP commands (which would
desync the connection for any subsequent message).

::: info Best-effort by design
A per-connection error is only logged at `debug`; a failed store write surfaces to
the client as `451` but never tears down the server. Mail capture is meant to be a
convenience that can't take your sites down.
:::

### `store` - the on-disk store

`Store` is the persistent capture store; the daemon holds it behind an `Arc`.
Layout under the store directory:

* `<id>.eml` - the verbatim captured message, one per email.
* `index.json` - an ordered, **oldest-first** list of `MailSummary` metadata, so
  listing doesn't re-parse every `.eml`.

```rust
pub fn open(dir: PathBuf) -> Result<Self, MailError>;     // DEFAULT_CAP
pub fn open_with_cap(dir: PathBuf, cap: usize) -> Result<Self, MailError>;
pub async fn append(&self, raw: &[u8]) -> Result<(), MailError>;
pub async fn list(&self) -> Vec<MailSummary>;             // newest-first
pub async fn count(&self) -> u32;
pub async fn counts(&self) -> (u32, u32);                 // (total, unread)
pub async fn get(&self, id: &str) -> Result<Option<MailDetail>, MailError>;
pub async fn delete_many(&self, ids: &[String]) -> Result<(), MailError>;
pub async fn mark_read(&self, ids: &[String]) -> Result<(), MailError>;
pub async fn clear(&self) -> Result<(), MailError>;
```

`MailSummary` carries a `read: bool` that lives in `index.json` (it is store
state, not decoded from the message). New captures start unread; `mark_read`
sets the read flag (one-way, unread to read) for the given ids and rewrites the
index only when something changed, and `counts` returns the total and the unread
tally under one lock so
the daemon's `Status` can report both consistently.

Design properties worth knowing as a contributor:

* **Single mutex, no file locks.** All mutations go through one
  `tokio::sync::Mutex<Inner>`, so concurrent SMTP connections appending at once
  can't lose an index update. Advisory file locks / `fs2` are **forbidden by the
  workspace dep-graph gate**, hence the in-process mutex.
* **Monotonic, never-reused ids.** Ids are a zero-padded (`{:06}`) counter that
  sorts in receipt order and is never reused - not even across `clear` /
  `delete_many`, which delete files but don't reset the counter. On `open`, the
  counter is seeded from the max of *both* the index *and* any `<id>.eml` on disk
  (`max_eml_id`), so an `.eml` written but never recorded in the index (a crash
  between the two writes) can never have its id reused.
* **Cap eviction on append.** After writing the new `.eml` and pushing its
  `summary`, `append` calls `retention::evict_count` and removes the oldest
  entries' `.eml` files beyond the cap.
* **Newest-first reads, oldest-first storage.** `entries` is stored oldest-first
  (cheap eviction from the front); `list` reverses it so callers see newest-first.
* **Atomic index writes.** `write_index` writes a sibling `index.json.tmp` then
  renames it over `index.json` - the same write-temp-then-rename discipline as
  [`yerd-config`](./yerd-config) / [`yerd-php`](./yerd-php), so a crash or partial
  write can never leave a truncated index. Rename is atomic on the same filesystem.
* **Corrupt index is recoverable, not fatal.** `load_index` treats garbled JSON as
  recoverable: the `.eml` files are the source of truth and `max_eml_id` reseeds
  the counter, so a corrupt index logs a warning and starts from empty rather than
  failing `Store::open` (which would take down the whole daemon). An absent
  `index.json` is simply an empty store.

## Error model

`MailError` (`#[non_exhaustive]`, `thiserror`) has three variants:

| Variant | Meaning |
|---------|---------|
| `Bind { port, source }` | The loopback SMTP port couldn't be bound (e.g. in use). The daemon logs and runs with capture **not listening**. |
| `Io { path, source }` | A filesystem operation on the store failed (carries the path for diagnostics). |
| `Index(serde_json::Error)` | The `index.json` cache couldn't be (de)serialised. |

It is intentionally **not** `Clone`/`Eq` because it wraps `std::io::Error` and
`serde_json::Error`.

## How `yerdd` consumes it

At startup the daemon ([`bin/yerdd/src/startup.rs`](../binaries/yerdd)):

1. **Always opens the store** at `<data>/mail` via `Store::open`. The store exists
   even when capture is disabled, so already-captured mail stays listable and
   clearable after the server is turned off.
2. **Binds the listener only when `[mail].enabled`** is true, calling
   `yerd_mail::bind(port)` with `config.mail.port` (default
   [`DEFAULT_MAIL_PORT`](./yerd-config) = `2525`). A bind failure is logged and
   degrades to non-listening - **non-fatal**. The resulting `listening` flag is
   recorded in `MailRuntime` and surfaced in `Status`.
3. **Spawns `serve`** with the bound listener, an `Arc<Store>` clone, and the
   daemon's shutdown future.

The IPC server then maps the mail [requests](./yerd-ipc) onto the store:

| Request | Store call |
|---------|-----------|
| `ListMails` | `store.list()` → `MailSummary`s, newest-first |
| `GetMail { id }` | `store.get(&id)` → `Option<MailDetail>` |
| `ClearMails` | `store.clear()` |
| `DeleteMails { ids }` | `store.delete_many(&ids)` (e.g. all mail for one app) |
| `MarkMailsRead { ids }` | `store.mark_read(&ids)` (mark opened mail read) |
| `SetMailPort { port }` / `SetMailEnabled { enabled }` | persist to the `[mail]` config table |

The `Status` report's `MailStatus` also calls `store.counts()` so the GUI's
unread badge (sidebar pill, tray dot, "Mail (N)" label) tracks captured mail.

::: warning Port / enabled changes need a restart
`SetMailPort` and `SetMailEnabled` save to config immediately but take effect on
the **next daemon start/restart** - whether the server is actually bound is a
startup property, with no implicit hot rebind. This mirrors `SetServicePort`.
:::

## See also

* [Mail Capture guide](../../guide/mail) - the user-facing feature
* [Mail CLI reference](../../reference/cli/mail) - `list` / `show` / `clear`
* [yerd-ipc](./yerd-ipc) - the `MailSummary` / `MailDetail` wire types and requests
* [The Daemon](../../guide/daemon) - the binder and consumer of this crate
* [Crates Overview](../crates)
* Source: [`crates/yerd-mail`](https://github.com/forjedio/yerd/tree/main/crates/yerd-mail)

---

---
url: 'https://yerd.app/developer/crates/yerd-mcp.md'
---
# yerd-mcp

`yerd-mcp` is the **Model Context Protocol server logic** behind `yerd mcp`: the
tool catalog agents call, the JSON-RPC state machine that drives a session, and
the rendering of daemon answers back into tool results. It lets Claude Code,
Cursor, and other local agents manage Yerd directly.

The crate is **sans-io**. It never touches stdin, a socket, the clock, or the
environment; it turns one input line into a description of what the caller should
do next. The stdio loop and the daemon exchange live at the binary edge, in
[`yerd`](../binaries/yerd)'s `mcp_cmd` module.

::: info Crate metadata
`description`: *Model Context Protocol server logic: tool catalog, JSON-RPC state
machine, and result rendering.* `#![forbid(unsafe_code)]`. Depends on
[`yerd-core`](./yerd-core) and [`yerd-ipc`](./yerd-ipc) (default features - the
pure build) plus `serde` / `serde_json` / `thiserror`. **No async runtime**, and
`tests/no_runtime_deps.rs` keeps it that way.
:::

See also the [Crates overview](../crates), [`yerd-ipc`](./yerd-ipc) (the requests
each tool maps to), the [`yerd mcp` command reference](../../reference/cli/mcp),
and the user-facing [AI Agents guide](../../guide/ai-agents).

## Module map

```text
src/
├── lib.rs        # Server / Outgoing / PendingCall / Availability + the layering doc
├── protocol.rs   # JSON-RPC envelope, method dispatch, the handshake
├── tools.rs      # the catalog: ToolDef table, schemas, build() -> yerd_ipc::Request
├── render.rs     # daemon Response -> MCP tool result (content / isError)
└── error.rs      # ArgError - argument validation, surfaced as JSON-RPC -32602
```

## The state machine

One tool = exactly one [`yerd_ipc::Request`](./yerd-ipc), so a call needs at most
one daemon round trip and the machine never has to track multi-step work.

```rust
let mut server = Server::new(Availability::Enabled, "2.0.3");
match server.handle_line(line) {
    Outgoing::Reply(line) => write(line),          // answer it yourself
    Outgoing::None => {}                           // a notification: never answer
    Outgoing::CallDaemon(call) => {                // one exchange, then complete
        let result = exchange(call.request.clone()).await;
        write(call.complete(result));
    }
    Outgoing::PolicyBlocked(call) => { /* re-check the gate, then run or refuse */ }
}
```

`PendingCall::complete` takes a `Result<Response, String>`. The `Err` side is not
an error type but the human-readable text describing a transport failure - the
caller has already decided what to tell the agent, and this renders it as a
failed tool result.

## Rules worth knowing before you edit

**Notifications are never answered.** `handle_line` branches on the presence of
`id` *before* method dispatch. A message with no `id` is a notification -
`notifications/cancelled` and friends are consumed silently; replying to one is a
protocol violation. A message with no `method` is a stray response and is
likewise ignored.

**`-32xxx` is for protocol faults, not policy.** A disabled toggle produces a
failed *tool result*, not a JSON-RPC error, and `initialize` always succeeds. A
server that failed its handshake because a feature was switched off would be
indistinguishable, in an agent's server list, from one that is broken.

**Validation beats the gate.** Tool lookup and argument checks run before the
availability check, so a malformed call is reported as malformed even while
gated - otherwise the agent is sent to fix the wrong thing.

**Guidance is rendered on demand.** `Server::gate_reply` reflects the *current*
availability. A session that starts with no daemon and later finds the toggle off
must stop blaming the daemon.

**Wire casing is exact.** `protocolVersion`, `serverInfo`, `inputSchema`, and
`isError` are camelCase per the spec; a snake\_case `inputSchema` is silently
ignored by clients, which then see a schema-less tool. The golden test pins it.

## Tests / invariants

* `tests/protocol.rs` - the handshake matrix, the notification/request split,
  error-code mapping, the gate, and single-line framing.
* `tests/tools.rs` - the catalog name list is **pinned**; every entry is
  well-formed, builds its request, and exposes no destructive tool.
* `tests/render.rs` - content shape, error mapping, status trimming, job hints.
* `tests/no_runtime_deps.rs` - the manifest declares no async runtime. Note this
  checks the *manifest*, not the resolved graph like the other pure crates'
  guards: `cargo metadata` unifies features workspace-wide, and because `yerdd`
  enables `yerd-ipc/transport`, a reachability walk sees a `yerd-ipc -> tokio`
  edge no matter who asks.

Treat a catalog-pin failure as a contract alarm: the tool list is what agents
build their calls against.

## Design notes

**Why hand-rolled?** The needed surface is four methods and a tool table. Yerd
already hand-rolls DNS ([`yerd-dns`](./yerd-dns)) and SMTP
([`yerd-mail`](./yerd-mail)) for the same reason: the official SDK is
tokio-based and its async model would not fit a pure crate, while its dependency
tree would have to be pinned and audited against the workspace's 1.77 MSRV.

**Why curated tools, not the whole IPC surface?** Roughly 100 auto-generated
tools measurably degrade an agent's tool selection and cost tokens on every turn.
The catalog is also where destructive operations are kept out: v1 exposes nothing
that drops a database, uninstalls software, unlinks a site, or clears captured
data.

---

---
url: 'https://yerd.app/developer/crates/yerd-tunnel.md'
---
# yerd-tunnel

`yerd-tunnel` is the **Cloudflare Tunnel** support crate: it generates the
`cloudflared` argument vectors and `config.yml`, parses `cloudflared`'s log
output for readiness, and supervises the long-running `cloudflared` child. It
powers the user-facing [Sharing Sites](../../guide/sharing) feature.

The crate is modeled on [`yerd-php`](./yerd-php) (not on the strictly-pure
[`yerd-core`](./yerd-core)): the `origin`, `args`, `parse`, and `config`
submodules are **pure** (sync, I/O-free, table-tested), while `manager` is the
**async I/O edge** that spawns and supervises the child behind injected traits.
This keeps the supervised driver in a *library* (so the binaries stay thin) while
the logic stays unit-testable.

::: info Crate metadata
`description`: *Cloudflare Tunnel argument/config generation and supervised
cloudflared lifecycle for Yerd.* `#![forbid(unsafe_code)]`. Depends only on
[`yerd-supervise`](./yerd-supervise) (the restart/health state machine and its
`ProcessSpawner` / `ChildHandle` / `Clock` traits) and `thiserror`; the only
async runtime is `tokio` (`time` + `macros`). It does **not** depend on any
binary - the `cloudflared` installer and the Cloudflare-account flows live in
[`yerdd`](../binaries/yerdd), which calls into this crate's pure helpers and
drives its `TunnelManager`.
:::

See also the [Crates overview](../crates), [`yerd-supervise`](./yerd-supervise)
(the shared supervision substrate), and the [Sharing Sites
guide](../../guide/sharing).

## Module map

The `pure` / `io` split: every *decision* (which loopback target, which argv,
whether the tunnel is ready, what the config renders to) is synchronous and
I/O-free; the only *effects* (spawning, sleeping, reading the logfile, killing)
sit in `manager`.

```text
src/
├── lib.rs        # re-exports + TunnelKind
├── origin.rs     # OriginTarget::for_site - loopback scheme/port + Host-rewrite flags
├── args.rs       # cloudflared argv builders (quick_tunnel/named_run/login/create/route/delete/...)
├── config.rs     # render_ingress_config - the named tunnel's config.yml (one rule per site)
├── parse.rs      # log scanners: parse_quick_url / is_named_ready / find_auth_url / find_tunnel_id
├── error.rs      # TunnelError
└── manager.rs    # TunnelManager - the async supervised driver (the I/O edge)
```

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## Routing: a Host-header rewrite, not a proxy change

A tunnel doesn't add any seam to the reverse proxy. Yerd's proxy already routes
purely by the `Host` header matching `.test`, so `yerd-tunnel` has `cloudflared`
**rewrite the Host header** to the site's canonical `{name}.{tld}` and point it at
Yerd's own loopback listener. `OriginTarget::for_site` encodes the choice:

* **Secure site** → `https://127.0.0.1:{https_bound}` with `--http-host-header`,
  `--origin-server-name` (the SNI drives the proxy's per-site cert resolver), and
  `--no-tls-verify` (the loopback hop uses Yerd's private CA, so public-trust
  validation is skipped - intentionally).
* **Non-secure site** → `http://127.0.0.1:{http_bound}` with `--http-host-header`
  (secure sites must take the HTTPS path to avoid the proxy's HTTP→HTTPS redirect).

The named tunnel serves every exposed site from one process: `render_ingress_config`
emits one ingress rule per site (each with its own origin) plus the mandatory
terminal `service: http_status:404`.

## The supervised driver

`TunnelManager<S: ProcessSpawner, C: Clock>` reuses
[`yerd-supervise`](./yerd-supervise)'s pure `transition` state machine and the
`SupervisorPolicy::tunnel()` profile (a generous 60s readiness window for a cold
edge connect, a 5s stop grace). The child is stored generically as `S::Child` so
a `FakeSpawner` substitutes in tests.

Supervision is **tick-based**: `begin()` registers and spawns the child, then the
caller drives readiness with `advance()`, **re-acquiring the manager lock per tick
and sleeping with the lock released**. Every lock-hold is therefore bounded (a sync
FSM step, or one stop-grace window on a kill), so `stop`/`status`/shutdown stay
responsive and a stuck connect can be cancelled. Readiness comes from the child's
logfile: the assigned `*.trycloudflare.com` URL (quick) or an edge-registration
line (named), parsed by the `parse` submodule.

## Public API

Re-exported from `lib.rs`:

```rust
pub use config::IngressRule;
pub use error::TunnelError;
pub use manager::{LaunchSpec, Step, TunnelManager, TunnelSnapshot, TunnelState};
pub use origin::{OriginTarget, Scheme};
```

| Item | Layer | Role |
|------|-------|------|
| `OriginTarget::for_site(...)` | pure | The loopback scheme/port/Host-rewrite flags for a site. |
| `args::*` | pure | One argv builder per `cloudflared` invocation. |
| `config::render_ingress_config(...)` | pure | Render the named tunnel's `config.yml`. |
| `parse::*` | pure | Log scanners (URL capture, readiness markers, auth URL, tunnel id). |
| `LaunchSpec` | - | Binary + args + pinned env + logfile for one spawn. |
| `TunnelManager` | io | Supervise one `cloudflared` child per site via the shared FSM. |
| `TunnelKind` | - | `Quick` vs `Named`. |
| `TunnelError` | - | The crate's error type (`thiserror`). |

---

---
url: 'https://yerd.app/developer/crates/yerd-services.md'
---
# yerd-services

`yerd-services` owns Yerd's **local database and cache services**: installing
prebuilt service binaries, supervising one instance per engine, reporting their
live state, and performing SQL database administration (create / drop / list /
backup / restore). It is the services counterpart to [`yerd-php`](./yerd-php) and
is structured the same way - every *decision* is pure and unit-testable; every
byte of I/O sits behind the [`yerd-supervise`](./yerd-supervise) trait seams.

The four engines it models:

| Service | `id` | Display name | Kind | Default port | Server binary |
|---|---|---|---|---|---|
| Redis | `redis` | `Redis (Valkey)` | Cache | 6379 | `valkey-server` |
| MySQL | `mysql` | `MySQL` | Database | 3306 | `mysqld` |
| MariaDB | `mariadb` | `MariaDB` | Database | 3306 | `mariadbd` |
| PostgreSQL | `postgres` | `PostgreSQL` | Database | 5432 | `postgres` |

::: info Redis is served by Valkey
The "Redis" slot is filled by **Valkey** - the BSD-licensed fork - because Redis
7.4+ is SSPL/RSALv2 and not cleanly redistributable. It stays wire-compatible, so
clients are unaffected. The server binary is `valkey-server`; the user-facing
display name is `Redis (Valkey)`.
:::

::: info Crate metadata
`description`: *Local database / cache service supervision and version management
for Yerd.* `#![forbid(unsafe_code)]`. Internal deps:
[`yerd-platform`](./yerd-platform) (`PlatformDirs`, `PortBinder`),
[`yerd-supervise`](./yerd-supervise) (the trait seams + state machine). External:
`thiserror`, `async-trait`, `serde`, `serde_json`, `tokio`.
:::

See also the [Crates overview](../crates), [`yerd-supervise`](./yerd-supervise),
and the user-facing [Services guide](../../guide/services).

## Module map

```text
src/
├── lib.rs            # re-exports + a compile-time Send+'static guard
├── service.rs        # Service / ServiceKind - pure per-engine metadata
├── database.rs       # pure SQL-admin logic (name validation, quoting, argv)
├── config_render.rs  # pure config rendering (redis.conf / my.cnf / postgresql.conf)
├── release.rs        # pure artifact resolution from the hosted listing
├── version.rs        # version labels + on-disk path layout; discover_installed
├── health.rs         # readiness probes (Redis PING, MySQL/Postgres handshake)
├── manager.rs        # ServiceManager - the I/O driver that runs the state machine
└── error.rs          # ServiceError
```

Pure modules: `service`, `database`, `config_render`, `release`, plus the path
builders in `version` and `error`. I/O lives in `manager` (spawning, fs, ports),
`health` (sockets), and `version::discover_installed`.

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## `service.rs` - pure engine metadata

`Service` (`Redis`, `MySql`, `MariaDb`, `Postgres`) and `ServiceKind` (`Cache`,
`Database`) are compile-time facts about each engine - no I/O. `Service::ALL` is
the canonical 4-element iteration order. Beyond the table at the top of this page,
each `Service` exposes:

| Method | Redis | MySql | MariaDb | Postgres |
|---|---|---|---|---|
| `client_binary()` | `None` | `mysql` | `mariadb` | `psql` |
| `dump_binary()` | `None` | `mysqldump` | `mariadb-dump` | `pg_dump` |
| `needs_init()` | false | true | true | true |
| `init_binary()` | `None` | `mysqld --initialize-insecure` | `mariadb-install-db` | `initdb` |
| `kind()` | `Cache` | `Database` | `Database` | `Database` |
| `datadir_pinned_to_major()` | false | false | false | **true** |

MySQL and MariaDB share port 3306, so only one can run on it at a time
(the config layer allows a per-instance override). PostgreSQL pins its data
directory to its major version (`data-<major>`) and refuses to start against a
datadir written by a different major.

## `database.rs` - the SQL-admin security boundary (pure)

All database administration logic is pure and **constructs SQL that cannot be
injected**. The daemon's [`db_admin`](../binaries/yerdd) edge calls these
functions and passes the result to the engine's client as a single argv element -
never through a shell.

* **`validate_db_name(name)`** - strict allowlist: non-empty, ≤ 63 chars (the
  lowest engine cap), first char an ASCII letter or `_`, the rest
  `[A-Za-z0-9_]`. Returns `DbNameError` (`Empty`, `TooLong`, `BadStart`,
  `BadChar(char)`). This policy applies only to databases Yerd creates.
* **`validate_existing_db_name(name)`** - accepts engine-created names selected
  for drop, backup, or restore, including whitespace, punctuation, Unicode, and
  quoting characters. It rejects only empty strings and embedded NUL characters.
* **`is_system_database(service, name)`** - case-insensitive guard. MySQL/MariaDB:
  `information_schema`, `performance_schema`, `mysql`, `sys`; Postgres: `postgres`,
  `template0`, `template1`. System databases cannot be dropped or restored over.
* **`quote_ident(service, name)`** - backticks for MySQL/MariaDB, double-quotes
  for Postgres (each doubling the quote char).
* **`create_sql` / `drop_sql` / `list_sql`** - per-engine statements. Postgres
  drop uses `DROP DATABASE <ident> WITH (FORCE);` (PG13+); Postgres list queries
  `pg_database WHERE datistemplate = false`. List queries return hexadecimal
  UTF-8 so line breaks and surrounding whitespace in names survive client output.
* **`client_args` / `dump_args` / `restore_args`** - build the argv for the
  interactive client / dump tool. MySQL & MariaDB connect over the local **Unix
  socket** as a passwordless `root`; Postgres connects over **TCP loopback** as
  `postgres`. Restore reuses the *client* binary (replaying SQL on stdin), not the
  dump binary.
* **`parse_db_list(service, stdout)`** - decodes hexadecimal names, filters system
  DBs, sorts, and deduplicates without altering database names.

## `config_render.rs` - pure config rendering

One renderer per engine, all returning text the caller writes to disk (no I/O
here):

* **`render_redis_conf`** - loopback bind, `protected-mode`, `daemonize no`, no
  password (local-dev posture).
* **`render_my_cnf`** - one `[mysqld]` renderer for both MySQL and MariaDB: bind
  `127.0.0.1`, `skip-name-resolve`, a Unix socket, and a pid-file.
* **`render_postgresql_conf`** - `listen_addresses = '127.0.0.1'` and
  **`unix_socket_directories = ''`** (Postgres uses TCP loopback only; the macOS
  `sun_path` limit rules out a socket here), with hba/ident pinned to the datadir.

## `release.rs` - artifact resolution (pure)

Yerd hosts its **own** multi-platform service distribution (the
`forjedio/yerd-services` build matrix) with a `services.json` listing
(`LISTING_SCHEMA = 1`). `SERVICES_BASE_URL` points at that GitHub release. The
pure functions here resolve a `(service, version, os, arch)` request against a
fetched listing body:

| Function | Purpose |
| --- | --- |
| `resolve_from_listing(...)` | Finds the build for an exact version, returning an `Artifact { service, version, url }`. Errors `VersionUnavailable` / `ListingParse` / `UnsupportedListingSchema`. |
| `available_versions(...)` | Every version published for the platform (infallible; empty on parse error). Feeds the GUI dropdown and `yerd service available`. |
| `artifact_url` / `listing_url` / `platform_token` | URL construction. |
| `current_os_arch()` | Resolves the host `(Os, Arch)`; errors on Windows / 32-bit. |

The daemon performs the actual HTTPS download (via the `Downloader` seam) and
hands the bytes back; integrity rests on HTTPS to the host (there is no separate
checksum sidecar for service builds).

## `version.rs` - layout & discovery

`ServiceVersion` is an opaque, validated version label (services don't share PHP's
major.minor shape). Labels may carry a **variant suffix** after a hyphen -
Postgres publishes both a lean base (`17`) and a PostGIS `17-full` under the same
service. The label is treated as opaque end to end: `release.rs` reads each
`version` string straight from the `services.json` listing (it never splits a
filename), so a hyphen in the label is safe by construction. Ordering
compares component-by-component and ranks a **plain** build above a suffixed one
at the same number (`"17.10" > "17.10-full"`), so `full` is never mistaken for the
"latest" build when resolving the newest version. `ServiceVersion::major()` ignores
the variant suffix (it splits on the first `.` or `-`), so a base and any variant of
the same major **share one datadir** (`data-<major>`) - which is what lets a
`change-version` between base and `full` preserve databases. For a variant install,
`manager.rs` also probes the install tree for `proj.db` / `gdalvrt.xsd` and, when
found, exports `PROJ_DATA` / `GDAL_DATA` into the postmaster environment (base
installs get neither) - what lets `PostGIS` `ST_Transform` / raster reprojection
resolve their runtime data. The on-disk layout under `PlatformDirs`:

```text
{data}/services/<id>/<version>/bin/<server_binary>   # the install (per version/label)
{data}/services/<id>/data                  (or data-<major> for Postgres) # shared datadir
{state}/services/<id>/<id>.conf            # rendered config
{state}/services/<id>/<id>.log             # captured stdout/stderr
{runtime}/services/<id>/<id>.sock          # Unix socket (MySQL/MariaDB)
```

`discover_installed(&PlatformDirs)` scans for version directories that contain a
real server binary; the daemon calls it at startup.

## `health.rs` - readiness probes

`ReadinessProbe` (service-aware) and `ServiceProbes` (the production dispatcher)
implement [`yerd-supervise`](./yerd-supervise)'s address-only `HealthProbe`. A
bare TCP accept is not enough during datadir init, so each probe requires a real
protocol response:

* **`RedisProbe`** - sends `PING`, expects `+PONG`.
* **`MySqlProbe`** - reads the initial handshake packet (first byte `0x0a`
  greeting or `0xff` ERR). MariaDB reuses this probe (same wire protocol).
* **`PostgresProbe`** - sends a startup message, accepts an `R` (auth) or `E`
  (error) reply tag.

## `manager.rs` - the `ServiceManager` driver

`ServiceManager<S, C, P>` is generic over the `ProcessSpawner`, `Clock`, and
`ReadinessProbe` seams, and always drives the state machine under
`SupervisorPolicy::database()`. It holds one `Instance` per `Service` in a
`BTreeMap` (deterministic shutdown order).

| Method | Behaviour |
| --- | --- |
| `ensure(service, version, port)` | Idempotent. Fast path returns the cached `Listen` if already running; otherwise runs one-time datadir init (staging dir + atomic rename), pre-flights the port via `PortBinder` (→ `PortInUse`), renders + writes the config, and drives the supervisor to `Running`. |
| `restart` / `stop` | Drive the supervisor through a stop (then re-`ensure` for restart). |
| `shutdown()` | Stops every instance in `BTreeMap` order. |
| `snapshots()` | Read-only `ServiceSnapshot { service, version, state, pid, listen }` per instance. |

`ServiceRunState` is `Running` or `Failed` (the daemon fills in `Stopped` for an
engine with no live instance). Per-engine specifics live in `build_cmd` (Redis
`valkey-server <config>`; MySQL/MariaDB `--defaults-file=<config>`; Postgres
`-D <datadir> -c config_file=<config>`) and `stop_protocol` (Postgres →
`MasterInterrupt`, all others → `GroupTerm`).

## How the daemon wires it in

[`yerdd`](../binaries/yerdd) instantiates
`ServiceManager<TokioProcessSpawner, SystemClock, ServiceProbes>` and exposes the
crate over IPC:

* **`bin/yerdd/src/services.rs`** handles `ListServices`, `AvailableServices`
  (downloads the listing on demand), `InstallService` (download + unpack, then
  start), `ChangeServiceVersion` (install → restart → remove old,
  keeping the datadir), `UninstallService` (optional `--purge` deletes data),
  `StartService` / `StopService` (toggle the status-only `enabled` flag; boot
  auto-start keys on installed versions, not this flag), `RestartService`,
  `SetServicePort`, and `ServiceLogs`. The per-service status reports
  `supports_databases` from `ServiceKind`.
* **`bin/yerdd/src/db_admin.rs`** is the I/O edge for database administration. It
  requires a *running* SQL engine with a client binary present, passes the pure
  SQL as a single argv element (no shell), streams `BackupDatabase` to a temp
  sibling and atomically renames it (never truncating the target), and streams
  `RestoreDatabase` into the client's stdin. Create uses the portable name
  allowlist; drop/backup/restore use exact existing names after empty/NUL checks.
  Engine errors are classified into
  typed `ErrorCode`s (`AlreadyExists` / `NotFound` / `Internal`).

See [IPC Protocol](../ipc-protocol) for the full service/database message set.

## Error model

`ServiceError` (`#[non_exhaustive]`, not `Clone + Eq` - it wraps `io::Error` and
`PlatformError`) pins the failure surface: `Unsupported`, `VersionNotInstalled`,
`DiscoveryIo`, `Init`, `Spawn`, `ConfigWrite`, `HealthCheckTimedOut`,
`PermanentFailure`, `PortInUse`, `Bind`, `Kill`, `VersionUnavailable`,
`UnsupportedPlatform`, `ListingParse`, `UnsupportedListingSchema`,
`Download(DownloadError)`, and `Extract`.

::: tip Engine availability is a distribution question, not a code one
All four engines are implemented end-to-end - supervision, init, config rendering,
health probing, and (for the SQL engines) database administration. Whether a given
engine/version installs depends only on whether a prebuilt build is published in
the hosted `services.json` listing for your platform. An unpublished build surfaces
as `VersionUnavailable` rather than a missing feature.
:::

---

---
url: 'https://yerd.app/developer/crates/yerd-doctor.md'
---
# yerd-doctor

`yerd-doctor` is the pure decision layer behind `yerd doctor` and `yerd doctor fix`. It takes a typed health snapshot - a [`StatusReport`](./yerd-ipc) - and turns it into two things: a list of human-readable findings ([`Diagnosis`](./yerd-ipc)), and a list of safe, unprivileged repairs the daemon may apply automatically (\[`FixAction`]).

The crate is deliberately tiny and runtime-free. It does **no I/O**, spawns no tasks, and touches no filesystem, network, or process. Every byte of "state" it reasons about arrives in the `StatusReport` argument; everything it produces is a return value. The daemon ([yerdd](../binaries/yerdd)) owns all effects - assembling the report, restarting pools, re-running diagnosis - and uses this crate only to decide *what* a snapshot means and *which* fixes are safe.

For the user-facing walkthrough of `yerd doctor`, see [Diagnostics](../../guide/diagnostics).

## Why this crate exists separately

Diagnosis is a pile of conditional rules: "a privileged port that fell back is a warning - unless a pf redirect makes it reachable anyway"; "an undeterminable CA-trust probe must stay silent rather than cry wolf"; "no PHP at all should suppress the narrower *default-not-installed* finding." That logic is worth testing exhaustively and in isolation, with no daemon, no sockets, and no OS. Pulling it into a `#![forbid(unsafe_code)]`, dependency-light crate (`yerd-core` + `yerd-ipc` only) makes the rules a pure function of an input struct - trivially unit-testable, and impossible to accidentally entangle with I/O.

```toml
# crates/yerd-doctor/Cargo.toml
[dependencies]
yerd-core = { path = "../yerd-core" }
yerd-ipc  = { path = "../yerd-ipc" }
```

## File map

The whole crate is one module.

| Path | Contents |
| --- | --- |
| `crates/yerd-doctor/src/lib.rs` | `FixAction`, `diagnose`, `plan_auto_fixes`, `is_auto_fixable`, plus private helpers (`privileged_fallback`, `port_findings`, `resolver_backup_finding`, `warn`, `fail`) and the full unit-test module. |

Source: [`crates/yerd-doctor/src/lib.rs`](https://github.com/forjedio/yerd/blob/main/crates/yerd-doctor/src/lib.rs).

## Public API

### `diagnose(&StatusReport, Option<bool>) -> Vec<Diagnosis>`

Runs every check against the report and returns the findings in a stable order.
The second argument, `path_needs_setup`, lets the caller surface a
`BinDirNotOnPath` warning when the yerd bin dir isn't on `PATH` (`None` = unknown,
skip that check).

```rust
#[must_use]
pub fn diagnose(report: &StatusReport, path_needs_setup: Option<bool>) -> Vec<Diagnosis>;
```

Two cross-cutting invariants hold for the output:

* **Always non-empty.** When no `Warn`/`Fail` finding is produced, a single \[`DiagnosisCode::AllGood`] `Ok` finding is appended, so a caller always has something to render.
* **No false alarms from unknowns.** Probes typed as `Option<bool>` that come back `None` ("couldn't determine") emit **no** finding. Only an explicit `Some(false)` raises a warning. This is why the CA and resolver checks compare against `Some(false)` rather than `!= Some(true)`.
* **Most-specific port finding wins.** `port_findings` raises `ForeignWebListener` when `report.foreign_web_listener == Some(true)` (a non-Yerd process on 80/443) and *suppresses* the generic `PortFallback` in that case - telling the user to free the port, not to elevate (which can't bind a port someone else owns). An active macOS redirect (`port_redirect == Some(true)`) likewise suppresses `PortFallback`.

### `plan_auto_fixes(&StatusReport) -> Vec<FixAction>`

Returns the safe, unprivileged fixes the daemon may apply for this report.

```rust
#[must_use]
pub fn plan_auto_fixes(report: &StatusReport) -> Vec<FixAction> {
    let mut fixes: Vec<FixAction> = report
        .php
        .iter()
        .filter(|p| p.state == PoolRunState::Failed)
        .map(|p| FixAction::RestartFpm(p.version))
        .collect();
    if report.ca.php_trusts_ca == Some(false) {
        fixes.push(FixAction::RebuildPhpCaBundle);
    }
    fixes
}
```

Conservative by design: the auto-fixes are restarting a failed FPM pool and rebuilding the bundled PHP's CA bundle (`{data}/cacert.pem`) when it's missing or stale - both fast, idempotent, and unprivileged (each writes only user-owned files). Privileged or slow remediation - CA trust, resolver install, `setcap`/pf, PHP install - is never auto-applied; it is left to the user to run the suggested command.

### `is_auto_fixable(DiagnosisCode) -> bool`

```rust
#[must_use]
pub fn is_auto_fixable(code: DiagnosisCode) -> bool {
    matches!(
        code,
        DiagnosisCode::FpmPoolFailed | DiagnosisCode::PhpCaNotTrusted
    )
}
```

Lets the daemon drop already-handled findings from the "manual" remainder it reports after a fix run. It is kept in lockstep with `plan_auto_fixes`: `FpmPoolFailed` and `PhpCaNotTrusted` are the codes both treat as auto-fixable.

### `FixAction`

```rust
/// A safe, fast, unprivileged fix the daemon may apply automatically.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum FixAction {
    /// Restart the FPM pool for this PHP version.
    RestartFpm(PhpVersion),
    /// Rebuild the managed PHP CA bundle (`{data}/cacert.pem`) so the bundled
    /// PHP trusts the Yerd CA again.
    RebuildPhpCaBundle,
}
```

`#[non_exhaustive]` so new variants can be added without a breaking change. Note the payload is a typed `yerd_core::PhpVersion`, not a string - this is the crux of the design decision below.

## Why plan from `StatusReport`, not from `Diagnosis`

A natural-looking alternative API would be `auto_fix(&Diagnosis)`. It does not work, and the crate documents why in its module docs:

> A wire `Diagnosis` carries only strings, so it cannot hand back the typed `PhpVersion` a `FixAction::RestartFpm` needs. Planning fixes from the typed report instead keeps the action list precise.

A [`Diagnosis`](./yerd-ipc) is a *wire* type - `code`, `severity`, `title`, `detail`, and an `Option<String> remedy`. The version of a failed pool only ever appears interpolated into human prose ("The PHP 8.5 FPM pool is not running"). Recovering a `PhpVersion` from that text would mean re-parsing a sentence. By planning from the *typed* `StatusReport`, `plan_auto_fixes` reads `PoolRunState::Failed` entries directly and carries each `PhpPoolStatus::version` straight into a `FixAction::RestartFpm(version)` - no stringly-typed round-trip, no parsing.

This is the same separation the rest of Yerd uses: structured truth in `StatusReport`, presentation in `Diagnosis`.

## No I/O - the daemon owns effects

`diagnose` and `plan_auto_fixes` only read their `&StatusReport` argument and allocate the returned `Vec`s. The daemon supplies the snapshot and applies the effects. The `doctor fix` flow in [yerdd](../binaries/yerdd) is the canonical consumer and shows the full round-trip:

```rust
// bin/yerdd/src/ipc_server.rs - run_doctor_fix (abridged)
let report = build_status_report(state).await;          // daemon does the I/O
let mut performed: Vec<FixResult> = Vec::new();

for action in yerd_doctor::plan_auto_fixes(&report) {     // pure planning
    if let yerd_doctor::FixAction::RestartFpm(v) = action {
        let outcome = { state.php_manager.lock().await.restart(v).await }; // effect
        performed.push(/* FixResult { code: FpmPoolFailed, ok, message } */);
    }
}

// Re-diagnose against a *fresh* report; surface what still needs the user.
let after  = build_status_report(state).await;            // daemon does the I/O again
let manual = yerd_doctor::diagnose(&after)                // pure, on fresh state
    .into_iter()
    .filter(|d| matches!(d.severity, Severity::Warn | Severity::Fail))
    .collect();

Response::DoctorFix { report: FixReport { performed, manual } }
```

The shape of this loop matters:

1. The daemon assembles a `StatusReport` (`build_status_report`).
2. `plan_auto_fixes` turns it into `FixAction`s - *pure*.
3. The daemon performs each action (`PhpManager::restart`) - *effect*.
4. The daemon assembles a **fresh** report and calls `diagnose` again - *pure*, against post-fix reality.
5. Warn/Fail findings from that second pass become `FixReport::manual`.

Re-diagnosing from a freshly-built report (rather than mutating the old one or trusting the fix succeeded) means `manual` reflects what is actually still broken - including any fix that failed to take. The `#[non_exhaustive]` `FixAction` is handled with `if let`, so a future variant the daemon doesn't yet know how to apply is silently skipped rather than mis-handled.

The plain `yerd doctor` path is even simpler - it just renders `diagnose(&build_status_report(state))`. When the CLI can't reach the daemon at all, it never enters this crate; [yerd](../binaries/yerd) substitutes a synthetic `DiagnosisCode::DaemonDown` `Fail` so the down state still renders and exits non-zero.

## The checks, in emission order

`diagnose` pushes findings in a fixed sequence. The table lists each rule, its trigger, and the severity it emits.

| # | `DiagnosisCode` | Severity | Triggers when | Remedy / note |
| --- | --- | --- | --- | --- |
| 1 | `PortFallback` | `Warn` | A *privileged* configured port (`requested < 1024`) fell back **and** `port_redirect != Some(true)` | `sudo yerd elevate ports` |
| 2 | `CaNotTrusted` | `Warn` | `ca.trusted_system == Some(false)` | `sudo yerd elevate trust` |
| 3 | `ResolverNotInstalled` | `Warn` | `resolver_installed == Some(false)` | `sudo yerd elevate resolver` |
| 4 | `NoPhpInstalled` | `Fail` | `php.is_empty()` | `yerd install php <default>` (suppresses #5) |
| 5 | `DefaultPhpNotInstalled` | `Fail` | `default_php` not among installed `php` | `yerd install php <default>` |
| 6 | `FpmPoolFailed` | `Fail` | one per pool with `state == Failed` | auto-fixed by `yerd doctor fix`, or `yerd use <ver>` |
| 7 | `ServiceFailed` | `Fail` | one per DB/cache service with `state == Failed` | `yerd service restart <svc>` |
| 8 | `PhpUpdateAvailable` | `Ok` | a pool has `update_available = Some(latest)` | `yerd update php <ver>` |
| 9 | `ResolverBackupSaved` | `Ok` | `resolver_backup == Some(path)` | informational, **no** remedy |
| 10 | `NoSites` | `Ok` | `sites.parked == 0 && sites.linked == 0` | `yerd park <dir>` / `yerd link <name> <dir>` |
| 11 | `DomainShadowed` | `Warn` | one per entry in `report.shadows` (a site whose apex or explicit domain was claimed by another site at router-build time); **not** auto-fixable | `yerd domain remove` / `yerd domain primary` |
| 12 | `BinDirNotOnPath` | `Warn` | `path_needs_setup == Some(true)` (a dev tool is installed but `{data}/bin` isn't on `PATH`) | `yerd path install` |
| 13 | `AllGood` | `Ok` | no `Warn`/`Fail` finding was produced | appended last |

A few rules carry subtle logic worth calling out.

### Privileged-port fallback (`PortFallback`)

```rust
const PRIVILEGED_PORT_CEILING: u16 = 1024;

fn privileged_fallback(report: &StatusReport) -> bool {
    (report.http.requested  < PRIVILEGED_PORT_CEILING && report.http.fell_back)
        || (report.https.requested < PRIVILEGED_PORT_CEILING && report.https.fell_back)
}
```

Only a port configured **below 1024** that fell back counts - a user who deliberately runs on `8080` and sees it bump to `8081` is not nagged. And even a genuine privileged fallback is suppressed when `report.port_redirect == Some(true)`: on macOS the daemon keeps binding the rootless ports after elevation, but an active pf `rdr` makes 80/443 reachable anyway, so the warning would be misleading. `Some(false)` (redirect present but inactive) and `None` (Linux / not applicable) both leave the warning in place. See [Elevation & Privileges](../../guide/elevation).

### "Unknown is silent" probes

`CaNotTrusted` and `ResolverNotInstalled` fire **only** on an explicit `Some(false)`. A `None` probe means "couldn't determine" - for example a CA store the daemon couldn't read - and produces no finding at all. This keeps the doctor from inventing problems out of missing data.

### PHP install findings are mutually exclusive

`NoPhpInstalled` (nothing installed) and `DefaultPhpNotInstalled` (the configured default specifically is missing) are wired as `if … else if …`, so an empty install only ever emits the broader `NoPhpInstalled`. See [PHP Versions](../../guide/php-versions).

### Informational findings never suppress `AllGood`

`PhpUpdateAvailable`, `ResolverBackupSaved`, and `NoSites` are all `Severity::Ok`. The `AllGood` summary is appended whenever no `Warn`/`Fail` exists - so a perfectly healthy machine that merely has an update available still shows the green "all checks passed" line alongside the informational ones.

### `ResolverBackupSaved` has no remedy on purpose

```rust
fn resolver_backup_finding(report: &StatusReport) -> Option<Diagnosis> {
    let path = report.resolver_backup.as_ref()?;
    Some(Diagnosis {
        code: DiagnosisCode::ResolverBackupSaved,
        severity: Severity::Ok,
        title: "Resolver file replaced".to_owned(),
        detail: format!(/* …saved to {path}… safe to delete, or copy it back… */),
        remedy: None,   // a path is not a runnable command
    })
}
```

The GUI renders `remedy` as a copy-the-command chip. The backup is a file *path*, not a command, so emitting it as a remedy would misrepresent it as runnable - hence `remedy: None`. The daemon only sets `resolver_backup` for a recent backup, so this finding auto-clears instead of nagging forever. See [DNS & .test Domains](../../guide/dns).

## Tests and invariants

The unit-test module builds a fully-healthy baseline `StatusReport` (`fn healthy()`) and perturbs single fields, asserting on the resulting `DiagnosisCode` set. The cases pin the rules above:

| Test | Invariant it locks in |
| --- | --- |
| `healthy_report_is_all_good_only` | a healthy report yields exactly `[AllGood]`, and `plan_auto_fixes` is empty |
| `privileged_fallback_warns_but_high_ports_do_not` | only sub-1024 requested ports warn on fallback |
| `active_port_redirect_suppresses_fallback_warning` | `Some(true)` suppresses; `Some(false)`/`None` do not |
| `ca_and_resolver_unknown_is_silent` | `None` probes emit nothing |
| `ca_and_resolver_false_warns` | `Some(false)` probes warn |
| `no_php_suppresses_default_not_installed` | empty install → only `NoPhpInstalled` |
| `default_not_installed_when_other_versions_present` | other versions installed but default missing → `DefaultPhpNotInstalled` |
| `failed_pool_is_fail_and_auto_fixable` | failed pool ⇒ `FpmPoolFailed` Fail, planned `RestartFpm(version)`, and `is_auto_fixable` agrees |
| `update_available_is_informational_and_still_all_good` | `Ok` findings coexist with `AllGood` |
| `resolver_backup_surfaces_as_ok_finding_with_no_remedy` | backup is `Ok`, `remedy.is_none()`, not auto-fixable |
| `no_sites_is_informational` | empty parked+linked ⇒ `NoSites` |
| `problems_suppress_all_good` | any `Warn`/`Fail` removes `AllGood` |

::: tip Adding a new check
Add the `Severity::Ok/Warn/Fail` finding in `diagnose` (use the `warn`/`fail` helpers), give it a new `DiagnosisCode` variant in `yerd-ipc` (additive - `DiagnosisCode` is `#[non_exhaustive]`), and pin it with a test off the `healthy()` baseline. If it should be auto-repairable, add a `FixAction` variant, emit it from `plan_auto_fixes`, list its code in `is_auto_fixable`, and teach the daemon's `run_doctor_fix` how to apply it.
:::

::: warning Keep `plan_auto_fixes` and `is_auto_fixable` in sync
`is_auto_fixable` is what the daemon uses to drop already-handled findings from the manual remainder. If a `FixAction` is added without updating `is_auto_fixable`, the daemon will both fix the problem *and* report it as still-manual.
:::

## Relationship to neighbouring crates

```mermaid
flowchart TD
    SR["StatusReport (yerd-ipc)"] --> DOC["yerd-doctor"]
    DOC -->|diagnose| DIAG["Vec&lt;Diagnosis&gt; (yerd-ipc)"]
    DOC -->|plan_auto_fixes| FIX["Vec&lt;FixAction&gt; (yerd-core::PhpVersion payload)"]
    FIX --> YERDD["yerdd applies effects, then re-diagnoses"]
```

* [`yerd-ipc`](./yerd-ipc) - owns every wire type this crate reads and writes (`StatusReport`, `Diagnosis`, `DiagnosisCode`, `Severity`, `PoolRunState`, plus the `FixReport`/`FixResult` the daemon wraps results in).
* [`yerd-core`](./yerd-core) - provides `PhpVersion`, the typed payload of `FixAction::RestartFpm`.
* [yerdd](../binaries/yerdd) - the sole consumer; builds the report, runs the fixes, re-diagnoses.
* [yerd](../binaries/yerd) - renders the `Diagnosis` list and computes the doctor-aware exit code.

See the [Crates Overview](../crates) for how the layer fits the wider workspace.

---

---
url: 'https://yerd.app/developer/crates/yerd-platform.md'
---
# yerd-platform

`yerd-platform` is Yerd's **OS abstraction layer**. It is the single place where the rest of the workspace touches platform-specific behaviour - trust stores, DNS resolver redirection, privileged-port binding, filesystem layout, and process metrics. Everything above it (the daemon, the CLI, `yerd-tls`, `yerd-dns`, `yerd-doctor`) consumes the traits defined here and never reaches for `#[cfg(target_os = ...)]` itself.

The crate has three jobs and keeps them strictly separated:

1. **Define the traits** - one trait per platform concern, with typed error and result types.
2. **Implement them once per OS**, selected at compile time, exposed through `Active*` aliases so callers name the concrete impl without a `cfg`.
3. **Keep all decision logic pure** in the `pure` module so it is unit-tested in-memory with no I/O, clock, environment, or async runtime.

A fourth, cross-cutting responsibility is the **privilege boundary**: this crate is unprivileged library code and never spawns the helper. See [Cross-Platform Model](../cross-platform) and [Elevation & Privileges](../../guide/elevation) for the wider picture.

::: info Source
[`crates/yerd-platform`](https://github.com/forjedio/yerd/tree/main/crates/yerd-platform). The crate is `#![forbid(unsafe_code)]`.
:::

## Module map

```text
src/
  lib.rs            re-exports the traits, types, and Active* aliases
  detect.rs         ProjectSignalSource trait + gather_project_signals (web-root signals)
  error.rs          PlatformError + typed reason enums + ops:: tag constants
  helper.rs         HelperInvocation (typed) + to_argv / from_argv wire contract
  metrics.rs        SystemMetrics trait (Option-returning, best-effort)
  paths.rs          Paths trait + PlatformDirs struct
  port_binder.rs    PortBinder trait + BoundPort / PortPair
  port_redirect.rs  PortRedirector trait + loopback_port_reachable / loopback_redirect_reaches_proxy
  resolver.rs       ResolverInstaller trait
  trust_store.rs    TrustStore trait + CaFingerprint + NssOutcome / NssFailure
  os/
    mod.rs          cfg-selects exactly one impl; exposes `active` aliases
    linux.rs        Linux* impls
    macos.rs        Macos* impls (+ security-framework)
    unsupported.rs  Unsupported* stubs (Windows, Phase 1)
  pure/
    mod.rs
    firefox.rs          parse_profiles_ini
    pem_match.rs        find_by_fingerprint, sha256, der_to_pem
    pf_anchor.rs        compose/insert/remove macOS pf redirect rules
    port_plan.rs        classify_desired / classify_fallback
    proc_metrics.rs     parse_vmrss_bytes / parse_loadavg (Linux /proc)
    ps_metrics.rs       parse_ps_rss_bytes (macOS `ps`)
    resolv_conf.rs      select supported Linux resolver backend
    networkmanager_dnsmasq.rs compose/match NetworkManager snippets
    dns_probe.rs        compose/validate the loopback DNS probe
    resolved_drop_in.rs compose/parse systemd-resolved drop-in
    resolver_file.rs    compose/parse macOS /etc/resolver/<tld>
```

Runtime dependencies are deliberately tiny: `thiserror`, `directories`, `sha2`, `hex`, `pem`, `serde_json` (only to read `composer.json` during signal gathering), plus `yerd-tls` and `yerd-core` (for the `ProjectSignals` / `Detection` types the detector feeds), with `security-framework` gated to macOS only. A test (`tests/no_runtime_deps.rs`) walks the resolved dependency graph (scoped with `--filter-platform` so cfg gates apply) and asserts that `tokio`, `anyhow`, `reqwest`, `openssl`, `openssl-sys`, and `native-tls` never appear in the normal-kind runtime graph - none of which `serde_json` or `yerd-core` pull in.

## The core traits

Each trait is intentionally narrow. With one exception, fallible methods return `Result<_, PlatformError>`.

### `Paths`

```rust
pub trait Paths {
    fn resolve(&self) -> Result<PlatformDirs, PlatformError>;
}
```

`resolve` returns a `PlatformDirs` with five directories. **Existence is not guaranteed** - callers are responsible for `create_dir_all` before writing.

| Field     | Meaning                          | Linux                                                       | macOS                              |
| --------- | -------------------------------- | ----------------------------------------------------------- | ---------------------------------- |
| `config`  | User config                      | `~/.config/yerd`                                            | macOS config dir                   |
| `data`    | Persistent data (CA + leaf certs)| XDG data home                                               | macOS data dir                     |
| `state`   | Long-lived state                 | `XDG_STATE_HOME` (distinct from `data`)                     | collapses to `data`                |
| `cache`   | Logs, downloads                  | XDG cache home                                              | macOS cache dir                    |
| `runtime` | IPC socket + PID file            | `XDG_RUNTIME_DIR/yerd`, else `/tmp/yerd-$UID`               | `/tmp/yerd-$UID`                   |

The Linux impl uses the `directories` crate, falling back to reading the real UID from `/proc/self/status` when `XDG_RUNTIME_DIR` is unset. macOS uses `ProjectDirs::from("io", "yerd", "Yerd")` and deliberately chooses a **deterministic, uid-derived** `/tmp/yerd-$UID` for `runtime` rather than `std::env::temp_dir()` (the per-session `/var/folders/…` path). Determinism is load-bearing: `yerd elevate`, running as root under `osascript`/`sudo`, must reconstruct the socket path from `SUDO_UID` alone without privileged FFI.

::: warning runtime is security-sensitive
When the `/tmp/yerd-$UID` fallback is used, the caller must `mkdir(mode=0o700)` and, if the directory already exists, verify ownership (`uid == geteuid()`) and mode (`0o700`) before using it. `yerd-platform` deliberately does not do this - it only computes the path; the daemon's `secure_fs` owns the fail-closed creation.
:::

### `TrustStore`

```rust
pub trait TrustStore {
    fn install_system(&self, ca_pem: &str, fp: &CaFingerprint) -> Result<(), PlatformError>;
    fn uninstall_system(&self, fp: &CaFingerprint) -> Result<(), PlatformError>;
    fn is_present_system(&self, fp: &CaFingerprint) -> Result<bool, PlatformError>;
    // Effectively *trusted* for SSL, not merely present. Defaulted to
    // `Unsupported` (the only defaulted method); macOS uses `security
    // verify-cert`, Linux delegates to `is_present_system`.
    fn is_trusted(&self, ca_path: &Path, fp: &CaFingerprint) -> Result<bool, PlatformError>;
    fn install_firefox_nss(&self, ca_path: &Path) -> Result<NssOutcome, PlatformError>;
    fn uninstall_firefox_nss(&self) -> Result<NssOutcome, PlatformError>;
    // Whether the per-user *browser* NSS stores trust the CA. Defaulted to
    // `Unsupported`; macOS + Linux override.
    fn browser_ca_trust(&self, fp: &CaFingerprint) -> Result<BrowserCaTrust, PlatformError>;
}
```

The CA is identified by a `CaFingerprint` - a newtype around `[u8; 32]` (SHA-256 over the cert's DER body) with a private field, so callers cannot construct an unchecked fingerprint. Its canonical wire form is **64 lowercase hex characters**; `from_hex` strictly rejects uppercase, wrong length, and non-hex so the form stays byte-stable across the helper argv boundary.

* `install_system` / `uninstall_system` always return `Err(PlatformError::NeedsHelper { .. })` in Phase 1. They are write operations against a root-owned store, so the daemon materialises the matching `HelperInvocation` and runs `yerd-helper`.
* `is_present_system` is a **read-only, unprivileged presence probe**. It reports whether a CA matching the fingerprint is *in* the store - not whether it is trusted for SSL by every consumer. On macOS it enumerates `/Library/Keychains/System.keychain` via `security-framework` and hashes each cert's DER; on Linux it iterates the distro's anchor directory and hashes each PEM block (the candidate directories are `/usr/local/share/ca-certificates`, `/etc/pki/ca-trust/source/anchors`, and `/etc/ca-certificates/trust-source/anchors`).
* `install_firefox_nss` / `uninstall_firefox_nss` / `browser_ca_trust` are the trust operations that run **per-user and unprivileged**. On Linux, Chromium-family browsers (Brave/Chrome/Chromium/Edge) and Firefox ignore the system store and read their own per-user NSS database - `~/.pki/nssdb` (shared by Chromium-family) and one `cert9.db` per Firefox profile, including Snap (`~/snap/<app>/{common,current}/...`) and Flatpak (`~/.var/app/<id>/...`) copies. Path derivation and the `certutil` argv are pure (`pure::nss`); the discover→run→aggregate orchestration is behind injected seams (`nss_exec`) so it is unit-tested in-memory. `certutil` (from `libnss3-tools`) missing is a first-class outcome (`certutil_missing` / `BrowserCaTrust::ToolMissing`), not an error. `install_firefox_nss` takes the CA **path** (read `-i` by `certutil`), creating and initialising `~/.pki/nssdb` if absent. It is best-effort and returns `Ok(NssOutcome)` even on partial failure:

```rust
pub struct NssOutcome {
    pub profiles_attempted: usize,
    pub profiles_succeeded: usize,
    pub failures: Vec<(PathBuf, NssFailure)>, // per-profile, in attempt order
    pub certutil_missing: bool,
}

pub enum NssFailure { CertutilMissing, CertutilExit(i32), DbMissing }
```

The caller decides whether to surface the degraded outcome. See [HTTPS & Certificates](../../guide/https) for the user-facing story.

### `ResolverInstaller`

```rust
pub trait ResolverInstaller {
    fn install(&self, tld: &str, addr: SocketAddr) -> Result<(), PlatformError>;
    fn uninstall(&self, tld: &str) -> Result<(), PlatformError>;
    fn is_installed(&self, tld: &str, addr: SocketAddr) -> Result<bool, PlatformError>;
}
```

`addr` is the IP+port the OS resolver should forward `.test` lookups to. The Phase-1 daemon always passes `127.0.0.1:<port>`, but the trait takes a full `SocketAddr` so a future version can move the DNS responder without a breaking change. `install`/`uninstall` return `NeedsHelper`; `is_installed` reads public config and is unprivileged. Both `uninstall` and `is_installed` are idempotent for an absent TLD (`Ok(())` / `Ok(false)`).

`is_installed` must verify the on-disk config points at **this** `addr` - a stale file aimed elsewhere (e.g. a Valet/Herd leftover on `:53`) must report `false` so the redirect gets re-installed. See [DNS & .test Domains](../../guide/dns).

### `PortBinder`

```rust
pub trait PortBinder {
    fn bind(&self, port: u16) -> Result<BoundPort, PlatformError>;
    fn bind_pair(&self, desired: (u16, u16), fallback: (u16, u16))
        -> Result<PortPair, PlatformError>;
}
```

`BoundPort` wraps a plain `std::net::TcpListener` (not the tokio variant) so `yerd-platform` keeps `tokio` out of its public surface; `yerd-proxy` converts via `tokio::net::TcpListener::from_std`. `BoundPort::port()` reads the resolved port from `local_addr()`, so it is correct even when binding `0`.

`bind_pair` binds HTTP+HTTPS atomically with a fallback. It attempts the desired pair, then:

* both succeed → keep them;
* one fails with a retry-trigger kind (`PermissionDenied`, `AddrInUse`, `AddrNotAvailable`) → drop any partial listener and retry the fallback pair;
* one fails with any other kind → surface `PlatformError::Bind` immediately *without* trying the fallback.

If both pairs fail, the error is `PlatformError::BindPair` carrying **all four** `io::ErrorKind`s, so the daemon can tell "setcap missing" (`PermissionDenied` everywhere) from "port already in use" (`AddrInUse` on the desired pair) and message the user accordingly. The classification itself is pure - see [`port_plan`](#port-plan).

### `PortRedirector`

```rust
pub trait PortRedirector {
    fn is_active(&self) -> Option<bool>;
    fn foreign_web_listener(&self) -> Option<bool>; // default impl, cross-platform
}
```

On macOS the unprivileged daemon cannot bind 80/443, so `yerd elevate ports` installs a pf `rdr` redirect to its rootless ports. Because the daemon still binds the high ports, `StatusReport.http.fell_back` stays `true` even when the redirect works - the doctor needs an independent signal that 80/443 are *actually reachable*. `is_active` is therefore an **active, unprivileged** check, and it goes further than "something answers": it speaks HTTP to loopback and requires the proxy's `Server` marker (`yerd_core::PROXY_SERVER_ID`) on the reply, so a foreign listener or a stale `pf` rule can't read as a live Yerd redirect.

```rust
// Bare reachability: does *anything* answer?
pub fn loopback_port_reachable(port: u16) -> bool { /* TCP connect, 250ms */ }

// Identity-confirming: is the answer *this* daemon's proxy? (Server: yerd marker)
pub fn loopback_redirect_reaches_proxy(port: u16) -> bool { /* HTTP probe */ }
```

`is_active` returns `None` on Linux (it binds the privileged ports directly after `setcap`). `foreign_web_listener` is the inverse, useful signal and is **cross-platform**: a default trait method that returns `Some(true)` when a privileged web port answers but the Yerd proxy marker is absent (a non-Yerd process squatting 80/443), `Some(false)` otherwise. The daemon surfaces it as `StatusReport.foreign_web_listener`, and `yerd-doctor` raises `ForeignWebListener` from it. The `unsupported` stub overrides it back to `None`.

### `SystemMetrics`

```rust
pub trait SystemMetrics {
    fn rss_bytes(&self, pid: u32) -> Option<u64>;
    fn load_average(&self) -> Option<[f64; 3]>;
}
```

Unlike every other trait here, metrics return `Option`, not `Result`. `None` collapses two cases - "OS unsupported" and "transient read failed" - because the only caller (`yerd status`) treats both identically: show nothing. The OS impls do only the file read / subprocess; the actual decoding lives in the table-tested `proc_metrics` / `ps_metrics` parsers.

## OS implementations and the `Active*` aliases

`os/mod.rs` compiles exactly one of `linux`, `macos`, or `unsupported` per build and re-exports it under uniform aliases:

```rust
pub(crate) mod active {
    #[cfg(target_os = "linux")]
    pub use super::linux::{
        LinuxPaths as ActivePaths, LinuxPortBinder as ActivePortBinder,
        LinuxPortRedirector as ActivePortRedirector,
        LinuxResolverInstaller as ActiveResolverInstaller,
        LinuxSystemMetrics as ActiveSystemMetrics, LinuxTrustStore as ActiveTrustStore,
    };
    // macos / unsupported arms are symmetric
}
```

`lib.rs` re-exports these, so callers write `ActiveTrustStore`, `ActivePaths`, etc. and the right concrete type is selected at compile time - no `cfg` leaks into consumer crates.

The **`unsupported` stub** (Windows in Phase 1) implements every trait so `cargo check --workspace` stays green on any host. Every fallible method returns `Err(PlatformError::Unsupported { operation })`; `SystemMetrics` returns `None`; `PortRedirector` returns `None`. `tests/unsupported.rs` (gated to non-Linux/non-macOS targets) asserts each method returns `Unsupported`.

## The `pure` module

Every function in `pure` is sync, runtime-free, and free of I/O, clock reads, and environment lookups. The OS impls do the reads/writes and call into `pure` for the decision; `pure` is table-tested in isolation.

### firefox

`parse_profiles_ini(text) -> Vec<Profile>` parses Firefox `profiles.ini`. It returns each `[Profile<N>]` section's `Name`, `Path`, `IsRelative`, and `Default`, silently ignoring `[General]`/`[Install…]` sections, comments, and profiles with no `Path`. Output `path` is raw - the caller joins relative paths against the `profiles.ini` parent, which `pure` does not know about.

### pem\_match

`find_by_fingerprint(blobs: &[(PathBuf, Vec<u8>)], fp: &[u8;32]) -> Result<Option<PemMatch>, PathBuf>` searches pre-read PEM blobs (the caller does the I/O) for the first `CERTIFICATE` block whose DER body hashes to `fp`, returning the matching path and 0-based block index. `Err(path)` signals a blob that failed PEM parsing, which the OS layer translates to `TrustStoreErrorReason::AnchorPemInvalid`. A blob with no certificate blocks (e.g. a README in an anchor dir) is `Ok(None)`, not an error. Also exports `sha256`, `der_to_pem`, and `fingerprint_of_first_cert_in_pem`.

### pf\_anchor

Composes the macOS pf redirect. Key constants: `ANCHOR_NAME = "dev.yerd"`, `ANCHOR_PATH = "/etc/pf.anchors/dev.yerd"`, `PLIST_PATH = "/Library/LaunchDaemons/dev.yerd.pf.plist"`, `PF_CONF_PATH = "/etc/pf.conf"`.

```text
rdr pass on lo0 inet proto tcp from any to any port 80  -> 127.0.0.1 port <http_to>
rdr pass on lo0 inet proto tcp from any to any port 443 -> 127.0.0.1 port <https_to>
```

`on lo0` is load-bearing: pf `rdr` only fires for `127.0.0.1→127.0.0.1` traffic when the rule is anchored to `lo0`. Functions: `compose_anchor_rules`, `is_installed`, `insert_anchor_refs`, `remove_anchor_refs`, `compose_launchdaemon_plist`. Inserted lines carry a `# yerd-managed` marker so insertion is idempotent and removal is unambiguous; the `rdr-anchor` reference is placed after the last existing translation anchor (pf requires the translation section before filter rules). The design **edits** `/etc/pf.conf` rather than loading a self-contained ruleset, because `pfctl -f <full-ruleset>` would flush Apple's default `com.apple/*` anchors. The boot-persistence plist is one-shot (`RunAtLoad`, no `KeepAlive`).

### port\_plan

The pure classifier behind `PortBinder::bind_pair`:

```rust
pub fn classify_desired(http: BindOutcome, https: BindOutcome) -> DesiredPairAction; // KeepDesired | UseFallback | HardFail(ErrorKind)
pub fn classify_fallback(http: BindOutcome, https: BindOutcome) -> FallbackPairAction; // KeepFallback | BothFailed
pub fn is_retry_kind(kind: ErrorKind) -> bool; // PermissionDenied | AddrInUse | AddrNotAvailable
```

The precedence is pinned by tests: a hard (non-retry) kind always beats a retry kind, and on the desired pair, `http` is inspected before `https`.

### resolv\_conf, networkmanager\_dnsmasq, dns\_probe, resolved\_drop\_in, resolver\_file (DNS)

* `resolv_conf` prefers systemd-resolved, selects NetworkManager only from its positive `/etc/resolv.conf` generator marker, and otherwise returns unsupported. It also validates NetworkManager's post-reload `127.0.0.1` dnsmasq nameserver.
* `networkmanager_dnsmasq` composes and strictly matches the `[main] dns=dnsmasq` override and per-TLD `server=/test/127.0.0.1#1053` rule.
* `dns_probe::compose_query(tld)` builds the A query for `yerd-resolver-probe.<tld>` that the helper sends to `127.0.0.1:53` after a NetworkManager reload; `response_has_loopback_a` checks the reply carries our transaction ID, `NOERROR`, and an `A 127.0.0.1` record. Keeping the packet bytes pure means the post-condition is table-testable without a socket.
* `resolved_drop_in::compose(tld, addr)` emits the Linux drop-in `[Resolve]\nDNS=<addr>\nDomains=~<tld>\n` (`/etc/systemd/resolved.conf.d/yerd-<tld>.conf`); `parse` / `matches` tolerate comments and extra keys so the `is_installed` probe is robust against operator edits.
* `resolver_file::compose(addr)` emits the macOS `/etc/resolver/<tld>` body `nameserver <ip>\nport <port>\n`; `parse` / `matches` ignore comments and ordering, defaulting a missing `port` to `53` per `resolver(5)`. `restorable(text)` (= `parse(text).is_some()`) is the pure guard the helper uses before writing a backup back over `/etc/resolver/<tld>` on `unelevate resolver`, so an empty/garbage backup is never restored. `backup_filename` / `parse_backup_secs` / `latest_backup` are the path-logic for the timestamped backups (`<tld>-<unixsecs>.conf`); the macOS helper restores the newest and clears the rest, the daemon reads the newest to report `ResolverBackupSaved`.

### proc\_metrics, ps\_metrics

* `proc_metrics::parse_vmrss_bytes(status)` reads the `VmRSS:` line of `/proc/<pid>/status` (kibibytes → bytes); `parse_loadavg(text)` reads the first three figures of `/proc/loadavg`. Using `VmRSS` avoids needing `_SC_PAGESIZE`, keeping the parser `unsafe`-free.
* `ps_metrics::parse_ps_rss_bytes(stdout)` parses the headerless first token of `ps -o rss= -p <pid>` (kibibytes → bytes) on macOS, which has no cheap `unsafe`-free per-process RSS source in `std`. All three return `None` on malformed input - metrics are best-effort.

## Web-root signal gathering (`detect`)

`detect.rs` is the **I/O half of web-root detection** - the *decision* half is the pure [`yerd_core::detect`](./yerd-core#detect). Gathering reads a project directory and produces an in-memory `yerd_core::ProjectSignals`; the daemon then calls `yerd_core::detect` on it to pick the served subdirectory.

Per the crate's "side effects behind traits" rule, gathering is exposed through a trait so callers can inject a fake:

```rust
pub trait ProjectSignalSource {
    fn gather(&self, project_root: &Path) -> ProjectSignals;
}

#[derive(Debug, Default, Clone, Copy)]
pub struct FsSignalSource;            // the real, filesystem-backed impl

pub fn gather_project_signals(project_root: &Path) -> ProjectSignals;
```

`gather_project_signals` is **best-effort and infallible** - a missing or malformed `composer.json`, an unreadable directory, etc. simply contribute fewer signals. It reads only the project root and the immediate candidate web dirs (`yerd_core::detect::WEB_DIR_CANDIDATES`), never recursively: it parses `composer.json`'s `require`/`require-dev` package names (lowercased), stats the `ROOT_MARKERS` (file *or* dir presence), and checks each candidate dir for an `index.php` front controller. Tempdir fixture tests (Laravel-like, WordPress-like, plain, empty, malformed-JSON) pin the gather→detect pipeline end to end.

This is the only place in the crate that touches a non-config filesystem path, and it is not OS-gated - the conventions are the same on every platform.

## The privilege boundary

This is the crate's most important invariant. `yerd-platform` is **unprivileged**. Any operation that needs root does not perform it - it returns `PlatformError::NeedsHelper { operation }`, where `operation` is one of the `&'static str` tags in `error::ops` (the single source of truth for these strings, also used as the leading argv element).

```rust
pub enum PlatformError {
    NeedsHelper { operation: &'static str },
    Unsupported { operation: &'static str },
    MissingHomeDir,
    TrustStore { reason: TrustStoreErrorReason },
    Resolver { reason: ResolverErrorReason },
    Bind { port: u16, source: std::io::Error },
    BindPair { reason: BindPairErrorReason },
    Io { path: PathBuf, source: std::io::Error },
    MissingTool { tool: &'static str, install_hint: Option<&'static str> },
}
```

`PlatformError` is `#[non_exhaustive]`, as are its reason sub-enums, so adding variants is semver-compatible. It is intentionally **not** `Clone + Eq` because two variants wrap `std::io::Error`.

When the daemon sees `NeedsHelper`, it builds a typed `HelperInvocation` and hands it to its subprocess spawner. Values stay typed all the way until `to_argv` serialises them at the spawn site - there is no `Vec<String>` round-trip in between.

```rust
pub enum HelperInvocation {
    InstallCa { ca_pem_path: PathBuf, fp: CaFingerprint },
    UninstallCa { fp: CaFingerprint },
    InstallResolver { tld: String, addr: SocketAddr },
    UninstallResolver { tld: String },
    Setcap { daemon_binary: PathBuf },
    InstallPortRedirect { http_from: u16, http_to: u16, https_from: u16, https_to: u16 },
    UninstallPortRedirect,
}
```

::: warning This crate never spawns the helper
The OS impls never call `Command::new(...)` for a privileged operation. A privileged caller owns the spawn: the daemon for its own setup, or `yerd elevate` running under `sudo`. `yerd-platform` only computes *what* should happen and serialises the request. See [yerd-helper](../binaries/yerd-helper) and [Elevation & Privileges](../../guide/elevation).
:::

`HelperInvocation::to_argv` / `from_argv` are a **wire contract** with the `yerd-helper` binary, pinned by `tests/helper_argv_shape.rs` (frozen golden vectors) and round-trip tested in the unit suite. The first element is always the op tag; subsequent elements alternate `--flag` and a single typed value:

```sh
install-ca --pem /run/user/1000/yerd/ca.pem --fingerprint <64-hex>
uninstall-ca --fingerprint <64-hex>
install-resolver --tld test --addr 127.0.0.1:5353
uninstall-resolver --tld test
setcap --binary /usr/bin/yerdd
install-port-redirect --http-from 80 --http-to 8080 --https-from 443 --https-to 8443
uninstall-port-redirect
```

`from_argv` is strict: unknown ops, unknown/missing flags, missing values, bad fingerprints (rejects uppercase/short), bad socket addresses, bad ports, non-UTF-8 values, and trailing argv each map to a typed `ArgvParseError`. Adding a field, reordering, or renaming a flag trips the golden test - which is exactly the point.

## Design invariants summary

| Invariant | Enforced by |
| --- | --- |
| No `tokio`/`anyhow`/`reqwest`/OpenSSL in the runtime graph | `tests/no_runtime_deps.rs` |
| Helper argv shape is frozen | `tests/helper_argv_shape.rs` + round-trip unit tests |
| Fingerprint wire form is 64 lowercase hex | `CaFingerprint::from_hex` + tests |
| Every trait method on unsupported OSes returns `Unsupported` | `tests/unsupported.rs` |
| `bind_pair` fallback/precedence rules | `pure::port_plan` tests |
| All decision logic is pure and I/O-free | `pure` module + per-submodule tests |
| `#![forbid(unsafe_code)]` | compiler |

## Related pages

* [Cross-Platform Model](../cross-platform) - how the cfg-gated layout and helper boundary fit together.
* [Crates Overview](../crates) - where `yerd-platform` sits in the workspace.
* [yerd-tls](./yerd-tls) and [yerd-dns](./yerd-dns) - primary consumers of `TrustStore` and `ResolverInstaller`.
* [yerd-helper (privileged)](../binaries/yerd-helper) - the binary that executes a `HelperInvocation`.
* [Elevation & Privileges](../../guide/elevation) - the user-facing view of the privilege boundary.

---

---
url: 'https://yerd.app/developer/crates/yerd-service-ctl.md'
---
# yerd-service-ctl

`yerd-service-ctl` is the **start/stop/restart control** for the `yerdd`
daemon's OS service registration. It exists so the self-update applier
([`yerd`](../binaries/yerd)) can restart the daemon onto a freshly-swapped
binary without re-implementing the platform service mechanics - the applier
cannot depend on the GUI binary (dependencies only flow downhill), so this
logic lives in its own library crate instead.

::: info Crate metadata
`description`: *Cross-platform start/stop/restart control for the yerdd
daemon service.* `#![forbid(unsafe_code)]`. Depends on `thiserror`, plus `nix`
(`user` feature, for `getuid`/`kill`) on Unix. No internal `yerd-*`
dependencies and no async runtime - it shells out to `launchctl`/`systemctl`
and uses `nix`'s safe wrappers, so its own dependency graph stays minimal.
:::

See also the [Crates overview](../crates), [`yerd-update`](./yerd-update)
(the version-decision logic the applier resolves before calling into this
crate), and the [Self-Update CLI reference](../../reference/cli/update).

## Module map

The whole crate is one module, split by concern rather than by file:

```text
src/
└── lib.rs   # ServiceCtl, ServiceError, plus the per-OS stop/start/restart mechanics
```

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## Per-OS mechanics

`ServiceCtl` is constructed with the path to the `yerdd` binary (used only by
the Linux no-systemd fallback) and exposes `stop`, `start`, and `restart`:

* **macOS** - `stop` sends `launchctl kill SIGTERM gui/$uid/dev.yerd.daemon`;
  `start` and `restart` both use `launchctl kickstart -k …`, which kills and
  restarts the already-registered `LaunchAgent` in one step. Registering the
  `SMAppService` job itself is the GUI's job (it owns the Swift/objc
  bindings) - this crate only drives `launchctl` against the already-known
  label.
* **Linux** - when a systemd `--user` instance is reachable
  (`systemctl --user show-environment` exits `0`), `stop`/`start`/`restart`
  map directly onto `systemctl --user {stop,start,restart} yerd`. Otherwise
  `restart` falls back to `stop` → poll for the process to exit (bounded to
  \~5s) → `start`, and `start` spawns a detached `yerdd serve` in its own
  process group so it survives the caller exiting.
* **Every OS** - `stop` also SIGTERMs any still-running `yerdd` pid found via
  `pgrep -x yerdd -U <uid>`, covering a bare `cargo run` / `yerdd serve` that
  no service manager supervises. This is best-effort: a `pgrep` failure or no
  match is treated as "nothing to signal," never an error.

Any platform without a supported service mechanism (i.e. not macOS or Linux)
returns `ServiceError::Unsupported` rather than silently doing nothing.

## Why `restart` differs by OS

macOS registers `yerdd` as a `LaunchAgent`, so `launchctl kickstart -k` is a
single atomic kill-then-restart of that job - there is no window where the
daemon is definitively "down" that the caller needs to wait out. Linux without
systemd has no equivalent primitive: the applier must confirm the old process
has actually released its executable inode and any bound sockets/ports before
spawning a new one, hence the explicit stop → `wait_for_exit` → start sequence
and the `ServiceError::Tool` returned if the daemon doesn't exit before the
timeout - starting a new daemon on top of a still-running old one would just
fail to bind.

## Public API

```rust
pub struct ServiceCtl { /* yerdd_path */ }

impl ServiceCtl {
    pub fn new(yerdd_path: impl Into<PathBuf>) -> Self;
    pub fn stop(&self);
    pub fn start(&self) -> Result<(), ServiceError>;
    pub fn restart(&self) -> Result<(), ServiceError>;
}
```

| Item | Role |
|------|------|
| `ServiceCtl::new(yerdd_path)` | Construct a controller; `yerdd_path` is only used by the Linux no-systemd detached-spawn fallback. |
| `ServiceCtl::stop` | Best-effort stop: asks the service manager, then SIGTERMs any still-running `yerdd`. Infallible. |
| `ServiceCtl::start` | Start via the service manager, or a detached spawn when none is available. |
| `ServiceCtl::restart` | Restart onto a freshly-swapped binary: `launchctl kickstart -k` on macOS, `systemctl --user restart` or stop-wait-start on Linux. |
| `ServiceError` | `Spawn` (couldn't launch the tool/binary), `Tool` (the tool ran and failed), `Unsupported` (no service mechanism on this platform). `#[non_exhaustive]`. |

---

---
url: 'https://yerd.app/developer/crates/yerd-update.md'
---
# yerd-update

`yerd-update` is the **decision layer** behind Yerd's self-update: given the
running version and a set of fetched GitHub releases, it decides whether a
newer version is available on the configured channel, and which downloadable
artifact matches the host platform. It powers the bare `yerd update` command
(see [Self-Update](../../reference/cli/update)) and the GUI's Updates section.

The crate does **no I/O**: fetching releases from GitHub, downloading
artifacts, and installing them all live in [`yerdd`](../binaries/yerdd) (the
version check) and [`yerd`](../binaries/yerd) (the applier, via
[`yerd-service-ctl`](./yerd-service-ctl)). This crate only decides *what*
should happen, given data the I/O layer already fetched.

::: info Crate metadata
`description`: *Pure release-channel selection and version-decision logic for
Yerd self-update.* `#![forbid(unsafe_code)]`. No internal `yerd-*`
dependencies - only `semver`, `sha2`, `hex`, and `minisign-verify`. A `pacman`
feature (off by default) flips \[`PkgFormat::current`] from `Deb` to `Pacman`
for the Arch package build; `bin/yerdd`'s own `pacman` feature forwards into
it (`yerd-update/pacman`).
:::

See also the [Crates overview](../crates), [`yerd-service-ctl`](./yerd-service-ctl)
(the daemon-restart step of the applier), and the
[Self-Update CLI reference](../../reference/cli/update).

## Module map

```text
src/
├── lib.rs        # Channel, ReleaseMeta, UpdateDecision, select_target, is_check_due
└── artifact.rs   # Platform, PkgFormat, ArtifactKind, select_asset, verify_sha256, verify_minisign
```

[Browse the source on GitHub.](https://github.com/forjedio/yerd)

## Channel resolution: stable vs. edge

`select_target` takes the full set of fetched releases, the configured
\[`Channel`], and the running version, and returns an \[`UpdateDecision`]:

* **`Channel::Stable`** resolves to the highest version among releases that
  are *not* pre-releases.
* **`Channel::Edge`** resolves to the highest version across every release,
  pre-releases included.
* A release counts as a pre-release if either the source (GitHub) flagged it,
  **or** its semver carries a pre-release component (`-rc.N`) - so a
  mis-flagged release is still classified safely.
* The channel's latest only becomes `target` when it is strictly newer than
  `current`; otherwise `target` is `None` ("nothing to do"). This means the
  stable channel never *downgrades* a user running a newer pre-release -
  `UpdateDecision::ahead_of_stable` flags exactly that case, which drives the
  `--stable`/`--force` downgrade guard in the CLI.

`is_check_due` decides whether enough wall-clock time has passed
(`CHECK_INTERVAL_SECS`, 4 hours) since the last check to poll again; `yerdd`
uses it to gate its periodic background poll.

## Artifact selection and verification

`select_asset` picks the right downloadable artifact (plus its detached
signature and the `SHA256SUMS` manifest) out of a release's assets, by
filename convention: the macOS artifact ends `.app.tar.gz`, the Linux artifact
ends `.deb` or `.pkg.tar.zst` depending on \[`PkgFormat`]. Intel macOS and any
other \[`Platform::Unsupported`] host get `AssetError::NoArtifactForPlatform`
rather than a mis-selected file.

The detached signature is named `<artifact>.minisig` (minisign's own default),
with a legacy `<artifact>.sig` accepted as a fallback for releases published
before the rename. When both names are present `select_asset` prefers
`.minisig`, so behaviour is identical during and after the transition window;
if neither is attached the artifact is treated as unsigned and
`AssetError::MissingSignature` is returned. The rename exists because pacman
reserves `<pkg>.sig` for a detached OpenPGP signature, so publishing a minisign
`.sig` beside the Arch package broke `pacman -U` (#157).

Verification is two independent checks, both pure functions over
already-downloaded bytes:

* `verify_sha256` looks up the artifact's filename in the `SHA256SUMS` body
  and compares against a freshly computed digest.
* `verify_minisign` checks a detached, **prehashed** minisign signature
  against one of two embedded public keys - \[`UPDATE_PUBLIC_KEY`] for app
  artifacts, and the separate \[`PHP_LISTING_PUBLIC_KEY`] for the PHP listing
  manifest fetched by `yerd-php` (a distinct key, since PHP installs are on
  the install critical path, not just app updates).

`yerdd`'s `StageUpdate` handler runs both checks before writing the artifact
to disk; the applier ([`yerd`](../binaries/yerd)) re-runs the minisign check a
second time immediately before swapping, closing the TOCTOU window between
daemon-verify and install.

## Public API

Re-exported from `lib.rs`:

```rust
pub use artifact::{
    select_asset, sha256_for, sha256_hex, verify_minisign, verify_sha256, ArtifactKind,
    ArtifactSelection, AssetError, PkgFormat, Platform, VerifyError, PHP_LISTING_PUBLIC_KEY,
    UPDATE_PUBLIC_KEY,
};
```

| Item | Layer | Role |
|------|-------|------|
| `Channel` | pure | `Stable` / `Edge`, with `as_str`/`parse` mirroring the persisted config string. |
| `ReleaseMeta` / `Asset` | pure | Plain data the I/O layer maps GitHub's release JSON into. |
| `select_target(releases, channel, current)` | pure | Decide the update target, latest-per-channel, and `ahead_of_stable`. |
| `UpdateDecision` | pure | The full result of `select_target`. |
| `is_check_due(last_checked, now)` | pure | Whether the 4-hour poll interval has elapsed. |
| `Platform` / `PkgFormat` | pure | Host platform and Linux package format (build-time, via a Cargo feature). |
| `select_asset(release, platform, format)` | pure | Resolve the artifact + signature + checksums asset triple. |
| `verify_sha256` / `verify_minisign` | pure | Checksum and signature verification over in-memory bytes. |
| `UPDATE_PUBLIC_KEY` / `PHP_LISTING_PUBLIC_KEY` | - | Embedded minisign public keys. |

---

---
url: 'https://yerd.app/developer/crates/yerd-depcheck.md'
---
# yerd-depcheck

`yerd-depcheck` is a small **test-only** crate: a shared `cargo metadata`
dependency-graph walk, used by every crate's and binary's
`tests/no_runtime_deps.rs` guard to keep the workspace off OpenSSL/native-tls
and free of accidental diamond-dependency version splits. It replaced six
near-identical ~140-line copies of the same breadth-first `cargo metadata`
walk (one per consumer) with one shared implementation.

::: info Crate metadata
`description`: *Test-only cargo-metadata dependency-graph assertions, shared
by every crate/binary's no\_runtime\_deps guard.* Depends only on `serde_json`.
Not `#![forbid(unsafe_code)]`-exempt in any way, but does carry a crate-level
`#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic, ...)]` -
the same allow every one of its six consumers' own `tests/no_runtime_deps.rs`
already needed, now centralised in one place instead of repeated six times.
:::

**Never appears in `[dependencies]`.** Every consumer pulls it in via
`[dev-dependencies]` only - that's load-bearing, not just convention:
`cargo metadata`'s `dep_kinds` marks a dev-dependency edge as `"dev"`, not
`null` ("normal"), and `DepGraph`'s own breadth-first walk only follows normal
edges. So a crate depending on `yerd-depcheck` for its tests never pollutes
its *own* runtime-graph assertions with `yerd-depcheck`'s dependencies.

## The API

```rust
pub struct DepGraph { /* private */ }

impl DepGraph {
    /// Run `cargo metadata --locked --filter-platform <host>` and BFS the
    /// normal dependency edges reachable from the workspace package `root`.
    pub fn for_package(root: &str) -> Self;

    /// Assert none of `forbidden` appear anywhere in the reachable graph.
    pub fn assert_none_of(&self, forbidden: &[&str]);

    /// Assert each of `names` resolves to at most one version (absent is fine).
    pub fn assert_at_most_one_version_each(&self, names: &[&str]);

    /// Assert each of `names` resolves to exactly one version (must be present).
    pub fn assert_exactly_one_version_each(&self, names: &[&str]);
}
```

A consumer's whole `tests/no_runtime_deps.rs` is now typically five to fifteen
lines:

```rust
#[test]
fn no_forbidden_crates_in_runtime_graph_and_unique_versions() {
    let graph = yerd_depcheck::DepGraph::for_package("yerd-proxy");
    graph.assert_none_of(&[
        "anyhow", "openssl", "openssl-sys", "native-tls",
        "hyper-tls", "tokio-native-tls", "webpki-roots",
    ]);
    graph.assert_at_most_one_version_each(&["hyper", "rustls", "tokio", "time"]);
}
```

## Consumers

| Crate/binary | Forbidden | Unique-version check |
|---|---|---|
| [`yerd-tls`](./yerd-tls) | `tokio`, `anyhow` | `time`, `x509-parser` (exactly one - both are known-present) |
| [`yerd-platform`](./yerd-platform) | `tokio`, `anyhow`, `reqwest`, `openssl`, `openssl-sys`, `native-tls` | - |
| [`yerd-php`](./yerd-php) | `anyhow`, `reqwest`, `openssl`, `openssl-sys`, `native-tls` | `tokio`, `time` (at most one) |
| [`yerd-proxy`](./yerd-proxy) | `anyhow`, `openssl`, `openssl-sys`, `native-tls`, `hyper-tls`, `tokio-native-tls`, `webpki-roots` | `hyper`, `rustls`, `tokio`, `time` (at most one) |
| [`yerdd`](../binaries/yerdd) | `anyhow`, `openssl`, `openssl-sys`, `native-tls`, `hyper-tls`, `tokio-native-tls`, `fs2` | `hyper`, `rustls`, `tokio`, `time` (at most one) |
| [`yerd-helper`](../binaries/yerd-helper) | `tokio`, `reqwest`, `openssl`, `openssl-sys`, `native-tls` | - |

Each consumer's forbidden list reflects *its own* dependency policy (e.g.
`yerdd` explicitly allows `webpki-roots`, since it fetches prebuilt PHP over
HTTPS via `reqwest` + rustls and bundled Mozilla roots are the right trust
anchor there; every other consumer forbids it). `yerd-depcheck` only supplies
the mechanism - each `tests/no_runtime_deps.rs` still states its own crate's
policy explicitly, so a `cargo test -p <crate> --test no_runtime_deps` failure
names exactly which crate's graph regressed.

::: info Standardised on `--filter-platform`
Before consolidation, five of the six consumers already ran `cargo metadata`
with `--filter-platform <host>` (scoping the graph to what actually compiles
for the current target); `yerd-tls`'s copy predated that pattern and queried
the full, unfiltered graph. `DepGraph::for_package` always filters - a strict
narrowing of the unfiltered graph, so this can only make a forbidden-crate or
unique-version assertion easier to satisfy, never spuriously fail one that
passed before.
:::

## See also

* [Crates Overview](../crates) - where this sits relative to the real
  (shipped) library crates.
* [Contributing](../contributing) - the full local test/lint gate this guard
  is part of.
* Source: [`crates/yerd-depcheck`](https://github.com/forjedio/yerd/tree/main/crates/yerd-depcheck)

---

---
url: 'https://yerd.app/developer/binaries/yerdd.md'
---
# yerdd (daemon)

`yerdd` is Yerd's **unprivileged, long-running daemon**. It is the process that actually serves HTTP/HTTPS, answers DNS for the local TLD, supervises PHP-FPM pools and database/cache services, owns the local certificate authority, and exposes the IPC socket that the [`yerd` CLI](./yerd) and the [desktop app](../gui) drive.

The crate is deliberately **thin orchestration**: nearly all real logic lives in the libraries (`yerd-core`, `yerd-config`, `yerd-tls`, `yerd-dns`, `yerd-proxy`, `yerd-supervise`, `yerd-php`, `yerd-services`, `yerd-doctor`, `yerd-platform`, `yerd-ipc`). `yerdd` wires them together - it loads config, builds the router, binds sockets, spawns the subsystem tasks (proxy, DNS, PHP-FPM pools, database/cache services), dispatches IPC requests, and handles process lifecycle. For anything that requires elevated privileges (trust-store install, resolver config, privileged-port redirect) it does **not** elevate itself; it shells out to [`yerd-helper`](./yerd-helper) through the [`yerd-platform`](../crates/yerd-platform) layer.

For the user-facing operational view of the daemon, see [The Daemon](../../guide/daemon). For the request/response contract this binary serves, see the [IPC Protocol](../ipc-protocol).

::: info Source
[`bin/yerdd`](https://github.com/forjedio/yerd/tree/main/bin/yerdd) on GitHub. The crate is published as both a binary (`src/main.rs`) and a library (`src/lib.rs`) - the lib shim exists only so the integration tests under `tests/` can reach internal entry points like `bring_up_with_dirs` and `run_with_daemon`.
:::

## Process model at a glance

```mermaid
flowchart TD
    BU["startup::bring_up (yerdd, one per user, single-instance)<br>InstanceLock (flock yerd.lock), load config, load/gen CA<br>build SiteRouter (parked scan + linked), bind HTTP/HTTPS/DNS<br>PhpManager, DaemonCertStore, IPC listener, DaemonState"]
    BU -->|"run_with_daemon spawns tasks, all watching one shutdown channel"| DNS
    BU --> PROXY
    BU --> IPC
    BU --> UPD
    BU --> WATCH

    DNS["DNS task (yerd-dns)"]
    PROXY["proxy task (yerd-proxy)"]
    IPC["IPC task (ipc_server)"]
    UPD["update-check task (PHP every 12h; Yerd self-update wall-clock-gated at 4h)"]
    WATCH["fs-watch task (re-scan parked roots on change)"]

    PROXY -->|"resolves backends,<br/>ensure() FPM pools"| HELPER
    DNS --> HELPER
    HELPER["privileged work<br/>yerd-helper via yerd-platform<br/>never in-process"]
```

## CLI surface

The daemon has a single subcommand, `serve`, which also runs when no subcommand is given (`src/args.rs`):

```rust
#[derive(clap::Subcommand, Debug)]
pub enum Command {
    /// Run the daemon in the foreground.
    Serve(ServeArgs),
}

#[derive(clap::Args, Debug, Default)]
pub struct ServeArgs {
    /// Increase log verbosity. `-v` → debug, `-vv` → trace.
    #[arg(short, long, action = clap::ArgAction::Count)]
    pub verbose: u8,
    /// Override the config file location.
    #[arg(short, long)]
    pub config: Option<PathBuf>,
}
```

| Flag | Effect |
| --- | --- |
| *(no subcommand)* | Equivalent to `serve` with defaults. |
| `serve` | Run the daemon in the foreground. |
| `-v` / `-vv` | Raise the log level to `DEBUG` / `TRACE` (see [tracing](#tracing-init)). |
| `-c, --config <PATH>` | Override the config file path. Defaults to `<config-dir>/yerd.toml`. |

`yerdd` runs in the **foreground** - process supervision (launchd/systemd, or the desktop app's spawn) is the caller's responsibility. It does not daemonize itself.

## Entry point and exit codes

`main.rs` parses args, installs tracing, builds a multi-threaded tokio runtime, and blocks on `run(args)`. The result is an `Outcome`:

```rust
pub enum Outcome {
    Exit,    // normal shutdown - process should exit
    Restart, // re-exec the binary in place (same PID)
}
```

`Outcome::Restart` is produced by a `RestartDaemon` IPC request. `main` drops the runtime first (joining worker threads so no residual fd survives), then `restart_in_place()` re-execs the binary with the original argv via `CommandExt::exec` on Unix. On non-Unix the daemon refuses `RestartDaemon`, so `Restart` is unreachable there.

Errors are translated to **sysexits-style** exit codes by `error::exit_code` (`src/error.rs`):

| Code | Meaning | `DaemonError` variants |
| --- | --- | --- |
| `0` | Clean shutdown | - |
| `70` | `EX_SOFTWARE` (fallback) | DNS, Proxy, PHP, IPC, runtime-build failures |
| `71` | `EX_OSERR` | `Platform`, `Tls` |
| `74` | `EX_IOERR` | `Io` |
| `75` | `EX_TEMPFAIL` | `AlreadyRunning` (another instance holds the lock) |
| `78` | `EX_CONFIG` | `Config`, `Core` |

`DaemonError` is `#[non_exhaustive]` and uses `thiserror` with `#[from]` conversions for every library error type, so any subsystem failure funnels into one daemon error and one exit code.

## Module map

The daemon's modules (`src/lib.rs` re-exports each as `pub mod`):

| Module | Responsibility |
| --- | --- |
| `args` | clap-derived CLI surface (`serve`, `-v`, `--config`). |
| `startup` | Bring-up pipeline: dirs, config, CA, router, socket binds, `DaemonState`. |
| `state` | `DaemonState` - the shared config + router + lifecycle channel. |
| `ipc_server` | IPC accept loop and per-request dispatch. |
| `cert_store` | `DaemonCertStore` - per-SNI leaf issuance/cache for the proxy. |
| `backend_resolver` | `DaemonBackendResolver` - routes a `Site` to a live FPM pool. |
| `detect_cache` | `DetectCache` - memoises web-root detection per project, keyed on a freshness stamp. |
| `fs_watch` | Debounced filesystem watcher that re-scans parked roots as projects appear/change. |
| `mutate` | Pure, I/O-free config-mutation logic (`Park`/`Link`/`SetPhp`/… plus the four domain mutations). |
| `site_domains` | Infallible, collision-resolving router builder (`build`) plus `collisions`, which reports the losing side of each domain clash (surfaced as `StatusReport.shadows`). |
| `php_install` | Download + unpack prebuilt PHP builds; `reqwest` downloader. |
| `php_updates` | PHP update poller + cache (notify-only). |
| `self_update` | Yerd self-update poller: fetches the GitHub Releases API, decides via the pure `yerd-update` crate, and persists a snapshot (`checked_at` + decision) both to disk and in `DaemonState` (notify-only). |
| `dump_server` | Loopback TCP server reading newline-delimited JSON dump frames from the native `yerd-dump` extension into a bounded ring buffer; serves the ring to the GUI over IPC (`ListDumps`/`DumpsStatus`/…). |
| `ext_install` | Downloads + SHA-256-verifies native PHP extension `.so`s per installed PHP version (from the `forjedio/yerd-php-ext` releases) into `{data}/php-ext/php-<ver>/`. An `ExtSpec` abstraction drives one fetch loop for **both** `yerd-dump` (`DUMP_SPEC`, gated on dumps) and `pcov` (`PCOV_SPEC`, ungated) - two manifests, one release. |
| `tools` | Dev-tool installers (Composer, Node, Bun, the Laravel installer, WP-CLI): download/build + verify into `{data}/tools/<id>/` and reconcile their `{data}/bin` shims. See [Dev-tool installers](../dev-tools). |
| `create_site` | Site-scaffolding job bodies for the GUI wizard (`laravel.rs`, `wordpress.rs`) - see [WordPress support](#wordpress-support) below. |
| `wordpress_detect` | Narrow marker-file check for whether a site is a `WordPress` install (`wp-config.php`/`wp-load.php`). |
| `wordpress_login` | One-click `WordPress` admin login: token registry + the `auto_prepend_file` bootstrap script. |
| `wordpress_url_sync` | Keeps a `WordPress` site's own `siteurl`/`home` options in sync with its HTTP/HTTPS toggle. |
| `wordpress_users` | Lists a `WordPress` site's administrator accounts (`wp user list`) for the login-as-user picker. |
| `wordpress_versions` | Cached `WordPress` core-version list for the create-site wizard's version dropdown. |
| `secure_fs` | Filesystem hardening (`0o700` dirs, `0o600` secrets). |
| `signals` | Unified shutdown future (SIGTERM + Ctrl-C). |
| `single_instance` | `InstanceLock` - exclusive `flock` so only one daemon runs. |
| `tracing_init` | Idempotent tracing-subscriber install. |
| `error` | `DaemonError` + sysexits exit-code mapping. |

## Startup (`startup.rs`)

`bring_up(args)` resolves the per-user [`PlatformDirs`](../crates/yerd-platform) via `ActivePaths::new().resolve()`, computes the config path (`--config` override, else `<config>/yerd.toml`), loads the config, and delegates to `bring_up_with_dirs`. The latter is the shared pipeline used by both production and the lifecycle tests (which inject a `tempfile`-rooted `PlatformDirs`), and it runs in this order:

1. **Single-instance lock** - `InstanceLock::acquire(&dirs)` (see below).
2. **PHP discovery** - `yerd_php::discover_bundled(&dirs)` finds installed builds under the data dir, producing a `BTreeMap<PhpVersion, PathBuf>`. An empty map is a warning, not an error.
3. **CA load-or-generate** - `load_or_generate_ca`. If `ca.cert.pem` + `ca.key.pem` exist they are re-loaded and their modes re-asserted (`0o644` cert, `0o600` key); otherwise a fresh `CertAuthority` ("Yerd Local CA", ~10-year validity) is generated and persisted. The CA path and SHA-256 fingerprint are captured **before** the CA is moved into the cert store, because `yerd elevate trust` needs both.
4. **Router build** - `build_router(&config, &dirs, &detect_cache)`: `scan_sites` walks every parked root for child directories, then appends explicitly linked sites. The result becomes a `SharedRouter` (`Arc<RwLock<SiteRouter>>`). A shared `DetectCache` (`Arc`) is created just before this and threaded into the build so the mutation path and the filesystem watcher reuse cached web-root detection.
5. **Port binding** - `ActivePortBinder::bind_pair((http, https), (8080, 8443))`. If `80`/`443` need elevation, the daemon falls back to `8080`/`8443` and logs a warning. The std listeners are converted to non-blocking tokio listeners. The bound HTTPS port also seeds `DaemonState::redirect_https_port` - see [the run loop](#the-run-loop-lib-rs) for how that value can later change live, without a restart.
6. **PhpManager** - constructed with `TokioProcessSpawner`, `SystemClock`, `FastCgiProbe`, the dirs, a port binder, the **daemon PID** as `instance_id` (disambiguates concurrent daemons), and the discovered binaries. Global ini settings from `config.php.settings` are seeded so the first pool start renders the user's values.
7. **IPC listener** - `build_ipc_listener` (Unix socket `runtime/yerd.sock` on Unix, named pipe `yerd-<pid>` on Windows).
8. **DNS bind** - `yerd_dns::Bound::bind(127.0.0.1:<dns_port>)`. A **fixed** port is required so an installed resolver config (`DNS=127.0.0.1:<port>`) survives restarts; `dns_port = 0` requests an ephemeral port (dev/tests only), read back via `Bound::local_addr`.
9. **Mail-capture store + listener** (the Email Capture feature). A `yerd_mail::Store` is opened over `{data}/mail` **unconditionally** - so already-captured mail stays listable even when capture is off - and is a hard error if it can't open. The SMTP listener is then bound via `yerd_mail::bind(mail_port)` **only when `config.mail.enabled`**; a bind failure (e.g. the port is busy) is logged and degrades to not-listening (`mail_listener = None`) rather than aborting the daemon. The resulting `mail_listening` flag is recorded on `DaemonState` and surfaced by `Status`.
10. **Dump-extension wiring.** Before the manager is shared, `php_manager.set_dump_ext(..)` is called so any pool with a matching `yerd-dump.so` under `{data}/php-ext/php-<ver>/` starts with `-d extension=<so>` plus the extension's `yerd_dump.state_path` ini define. The `.so` itself is fetched on demand (see [the run loop](#the-run-loop-lib-rs) / `ext_install`); the extension self-disables via its state file when dumps are off.
11. **DaemonState assembly** - everything the running tasks share (next section), including the `DumpStore` (the ring + rebind signal) and the mail store/runtime flag. After assembly, the extension's runtime `state.json` is seeded from the persisted `[dumps]` config (best-effort) so a fresh boot reflects the durable settings.

### Site discovery: `scan_sites` / `build_routing`

`scan_sites` reads each `cfg.parked.paths` root and turns each non-hidden child **directory** into a parked `Site` keyed by its lowercased name. Linked sites win on a name collision (the parked child is skipped). Persisted per-site overrides (`cfg.overrides`, keyed by the site's `document_root` stringified with `to_string_lossy`) are re-applied here - PHP version, `secure` flag, and `web_root` - **without promoting the site to linked**. A missing parked root is a warning, not an error.

**Web-root detection.** For each parked site, if the override pins a `web_root` it is used; otherwise the daemon detects one via the shared `DetectCache` - `yerd_platform::gather_project_signals` (I/O) feeds `yerd_core::detect` (pure). A site whose detection is **unresolved** (an empty folder with no framework evidence yet) serves the project root provisionally and its path is collected as a *watch target*. So `scan_sites` returns `(Vec<Site>, Vec<PathBuf>)`, and `build_routing(cfg, dirs, cache) -> (SiteRouter, Vec<PathBuf>)` exposes both; `build_router` is the thin wrapper that keeps only the router. Linked sites carry their `web_subpath` in the persisted `Site`, so they aren't re-detected on a scan (re-detection is on demand via `SetWebRoot { path: None }`).

::: tip Override-key invariant
`startup::scan_sites` and the `SetWebRoot`/`mutate` handlers both derive the overrides map key from the same `DirEntry::path()` via `to_string_lossy`, so the strings are byte-identical. Neither side canonicalises independently - that is what keeps a parked site's override matching across a re-scan.
:::

The unit tests in `startup.rs` pin this behaviour: parked-dir walking, missing-root tolerance, linked-wins-on-collision, PHP/secure override application, dormant orphan overrides, a linked collision leaving a parked override dormant, web-root detection collecting the unresolved roots, and a `web_root` override pinning the path without watching it.

### The detection cache (`detect_cache.rs`)

`DetectCache` memoises `Detection` per project root, keyed on a **freshness stamp** = `max(project-root dir mtime, composer.json mtime)`. Adding/removing a top-level entry (e.g. cloning in `public/`) bumps the dir mtime; editing `composer.json` in place bumps the file mtime - so the stamp invalidates exactly when the web root could change. Without it, every unrelated mutation (`yerd use`, `yerd secure`) would re-read every parked project's `composer.json` under the config lock. It uses a `std::sync::Mutex` (the critical section is a brief map lookup, no `.await`) and recovers from a poisoned lock rather than panicking.

### Filesystem watcher (`fs_watch.rs`)

Detection at scan time only fires at startup and on mutations, so a project cloned into a parked folder *afterwards* would serve from the wrong directory until something else triggered a re-scan. The watcher closes that gap. It uses `notify` + `notify-debouncer-mini` and watches **non-recursively**, so the descriptor count scales with the number of sites (not project size) and `vendor/`/`node_modules/` churn never reaches a parent watch. The live watch set is:

* **every parked root** - always, to notice child sites appearing/disappearing; plus
* **only the project roots of *unresolved* parked sites** (no framework detected yet, no manual override) - to catch a project being cloned in.

A site is dropped from the watch set once it resolves or is manually overridden - "don't watch what we already know" (the documented trade-off: deleting a resolved site's web root *in place* isn't noticed until the next scan from another trigger). On a debounced batch of events - or a ping on `state.watch_dirty` (sent after every mutation commits, so a freshly parked root is watched without waiting for an fs event) - the task rebuilds the router from the *current* config under the config lock (same `config → router-write` order as the mutation path, so it never races a mutation) and **never writes config**, so it cannot feed back into its own fs events. It is the fifth subsystem task (see [the run loop](#the-run-loop-lib-rs)).

## Shared state (`state.rs`)

`DaemonState` is the single `Arc`-shared struct the IPC dispatch and proxy read at runtime. The non-obvious fields:

| Field | Purpose |
| --- | --- |
| `config: Mutex<Config>` | Authoritative config, mirrored in memory; the mutex serializes concurrent mutations. |
| `router: SharedRouter` | Live routing table (`Arc<RwLock<SiteRouter>>`), replaced wholesale on a successful mutation; the proxy reads it. |
| `dirs`, `config_path` | For re-scanning parked roots and persisting on mutation. |
| `dns_addr`, `ca_path`, `ca_fingerprint` | Reported by `DaemonInfo` / `Status` (the resolver and trust installers consume them). |
| `php_updates: RwLock<HashMap<PhpVersion, String>>` | Update cache: installed minor → newest known patch. Served (no network) on `ListPhp`. |
| `php_manager: Arc<Mutex<DaemonPhpManager>>` | The FPM supervisor, shared with the proxy backend resolver and update task. |
| `http`, `https: PortStatus` | Requested-vs-bound ports (drives the rootless-fallback diagnostics). |
| `redirect_https_port: Arc<AtomicU16>` | Port the HTTP→HTTPS redirect currently advertises. Seeded from `https.bound`; when `https.fell_back`, the redirect-probe task (see [the run loop](#the-run-loop-lib-rs)) flips it to `https.requested` once a privileged-port redirect (macOS `pf`, `yerd elevate ports`) is live, and back when it isn't - so `yerd-proxy`'s `HttpsBinding::public_port` can change without restarting the proxy. |
| `started_at: Instant` | `Status` uptime. |
| `shutdown_tx: watch::Sender<bool>` | The one broadcast channel every task watches; `RestartDaemon` trips it directly. |
| `restart_requested: AtomicBool` | Set before tripping shutdown so `main` re-execs instead of exiting. |
| `detect_cache: Arc<DetectCache>` | Shared web-root detection cache (mutation path + watcher). |
| `watch_dirty: Notify` | Pinged after a mutation commits so the watcher reconciles its watch set without waiting for an fs event. |
| `shim_reconcile: Mutex<()>` | Serializes `php_install::reconcile_shims` runs. IPC dispatch is `tokio::spawn`-per-connection, so two clients could rebuild the `{data}/bin` cover/clean shims at once; this guard keeps the (sync) scan→prune from interleaving. |
| `wordpress_sites: Arc<RwLock<HashMap<String, bool>>>` | Cache of which sites are `WordPress` (site name → bool), refreshed on every router rebuild. Read by `ListSites` (badge), the login/user-listing handlers, `wordpress_url_sync`, and the proxy's `DaemonBackendResolver::allows_direct_script_execution` (see [Backend resolver](#backend-resolver-backend-resolver-rs)). |
| `wordpress_login_tokens: Arc<wordpress_login::LoginTokenRegistry>` | One-click admin-login token store, shared with `yerd-proxy` via `LoginTokenConsumer`. See [WordPress support](#wordpress-support). |
| `wordpress_login_prepend_script: Option<PathBuf>` | Path the auto-login bootstrap script was written to at startup, or `None` if that write failed - one-click login is then unavailable this boot (the ordinary `/wp-admin/` link still works). |
| `wordpress_versions: RwLock<Option<(Instant, Vec<WordPressVersionInfo>)>>` | Last successful `WordPress` core-version fetch, plus when, so a request can decide whether to re-fetch. Served stale-on-failure. |

::: warning Lock order
The mutation path is the only place that holds two locks, and always in the order **config-mutex → router-write**. The proxy and `ListSites` take only a router *read* guard and never touch the config mutex, so there is no cross-lock cycle. The status assembler (`build_status_report`) takes each guard, drains it into owned data, and drops it before the next - never two at once, never a guard held across an `.await` that touches another lock.
:::

## The run loop (`lib.rs`)

`run(args)` calls `bring_up`, then `run_with_daemon`, which:

1. Clones `state.shutdown_tx` and subscribes a receiver.
2. Spawns `signals::wait_for_shutdown` on the sender.
3. Calls `run_until_shutdown`, which spawns the long-lived subsystem tasks - each watching a clone of the shutdown channel:

   * **DNS** (`yerd_dns::Bound::serve`),
   * **proxy** (`yerd_proxy::ProxyServer::serve` with the `DaemonBackendResolver` and an `HttpsBinding` carrying the cert store),
   * **IPC** (`ipc_server::run`),
   * the **dump-telemetry server** (`dump_server::run`) - a loopback TCP listener receiving newline-delimited JSON frames from the native PHP `yerd-dump` extension into a ring buffer; it rebinds on a port change and a bind failure is non-fatal (logged, retried on the next rebind),
   * an **update checker** covering two independent cadences in one task: a
     **PHP checker** (poll once, then every 12h) and a **Yerd self-update
     checker** (`self_update::poll_if_due`, woken every 15 minutes but only
     fetching when `yerd_update::is_check_due` says its own 4h wall-clock
     interval has elapsed - robust to the process being suspended, unlike a
     plain `tokio::time::interval`). Both are notify-only,
   * the **filesystem watcher** (`fs_watch::run`, see above),
   * conditionally, the **mail-capture SMTP task** (`yerd_mail::serve`) - spawned only when `daemon.mail_listener` is `Some` (mail capture enabled *and* the SMTP port bound at startup; a disabled or failed bind is non-fatal and already logged in `bring_up`), and
   * conditionally, the **redirect-port prober** (`spawn_redirect_probe`) - spawned only when the proxy is up *and* `state.https.fell_back` (the HTTPS listener bound the rootless fallback, e.g. `8443`). Every 5s it calls `yerd_platform::PortRedirector::is_active` (via `spawn_blocking`, since the probe does real loopback I/O) and stores `effective_redirect_port(state.https, active)` into `DaemonState::redirect_https_port` - flipping the HTTP→HTTPS redirect target to the well-known port once a macOS `pf` redirect (`yerd elevate ports`) is confirmed live, and back if it later disappears. On platforms/configs where `is_active` is always `None` (Linux, or a well-known-port bind that never fell back) this task is either unnecessary (not spawned) or a cheap no-op poll.

   That is **six always-on tasks plus two conditional ones** (mail, redirect-probe). Four further spawns are fire-and-forget background work, deliberately *not* awaited so a slow boot can't delay the listeners: an **installed-services auto-start** (`services::auto_start_installed`) that brings up every engine with an installed version, regardless of the persisted `enabled` flag (a `Stop` lasts only the session). It watches the shutdown channel and bails the moment shutdown is requested, so an instance torn down shortly after booting (an upgrade-restart bounce) never spawns DB engines it would only have to stop again - that 10s `stop_grace` would otherwise hold the instance lock and stall the next launch. When dumps are enabled in config, an **extension-install** pass (`ext_install::ensure_for_installed`) that fetches the dump `.so` for installed PHP versions so on-demand pools pick it up; an **always-on pcov + cover-shim** pass (`ipc_server::refresh_pcov_and_shims`) that bundles `pcov.so` for installed versions and (re)builds the `{data}/bin` cover/clean shims. This pass is where the **cover symlinks self-heal**: it re-points them at the current `yerd` binary, so a moved-binary install still resolves, and warm/offline starts skip the network (a local-presence check on the `.so`s) - see [cover-shim reconciliation](#cover-shim-reconciliation-and-pcov). The fourth spawn is a **dev-tool shim reconcile** (`reconcile_tool_shims_now`) that self-heals the `composer`/`node`/`bun` shims (re-pointing the `composer` multi-call link if the `yerd` binary moved) and prunes shims for tools removed between runs.
4. Awaits the shutdown channel, then caps each task's join with a `timeout` (10s DNS/proxy, 5s IPC/dump/update/watch, and 5s for the mail and redirect-probe tasks when present) so a stuck task can't hang the exit.
5. Shuts down the PhpManager and the service manager, reads `restart_requested`, drops the instance lock, and returns `Outcome`.

After `run_until_shutdown` returns, the signal task is **aborted** rather than awaited - when shutdown came from a `RestartDaemon` IPC (which trips the channel directly with no OS signal), the signal task is still parked and awaiting it would hang the restart forever.

## IPC server (`ipc_server.rs`)

`ipc_server::run` is a `tokio::select!` accept loop (biased toward the shutdown branch) that spawns one `handle_client` task per connection. Each client task frames with `yerd_ipc`'s `FrameDecoder` / `read_message` / `write_message` (`DEFAULT_MAX_FRAME` cap) and loops request→`dispatch`→response. Decode errors close the connection quietly (common with mismatched-version clients).

`dispatch` is a single `match` over `yerd_ipc::Request` (which is `#[non_exhaustive]`, hence the catch-all arm returning `Internal`). It covers:

* **Read-only:** `Ping`, `ListSites`, `ListParked`, `DaemonInfo`, `Status`, `Diagnose`, `ListPhp`, `AvailablePhp`.
* **Mutations:** `Park`, `Link`, `Unlink`, `Unpark`, `SetPhp`, `SetSecure`, `SetWebRoot`, `AddDomain`, `RemoveDomain`, `SetPrimaryDomain`, `ResetDomains` → `handle_mutation`.
* **PHP lifecycle:** `InstallPhp`, `UpdatePhp`, `CheckPhpUpdates`, `SetDefaultPhp`, `SetPhpSettings`, `RestartPhp`, `RestartAllPhp`, `UninstallPhp`.
* **Doctor:** `Diagnose` (via `yerd_doctor::diagnose`), `DoctorFix` (runs `plan_auto_fixes`, applies FPM restarts, re-diagnoses).
* **Dumps (Laravel telemetry):** `ListDumps` (pages the ring), `ClearDumps`, `DeleteDump`, `DumpsStatus`, `SetDumpsEnabled` (first enable fetches the `.so` and restarts started pools), `SetDumpsPort` (test-binds then triggers a hot rebind), `SetDumpsPersist`, `SetDumpFeature` → `dump_server::*`.
* **Mail capture:** `ListMails`, `GetMail`, `ClearMails`, `DeleteMails`, `MarkMailsRead` (marks the given mails read in the store), `SetMailPort`, `SetMailEnabled` (port/enabled persist to config and take effect on the next restart - no hot rebind) → the `mail_store` / `set_mail_*` handlers. `Status` reports the store's total and unread counts via `MailStatus`.
* **Dev tools:** `ListTools` (pure fs status), `InstallTool`/`UninstallTool` → `tools::*` then a `{data}/bin` shim reconcile. See [Dev-tool installers](../dev-tools).
* **WordPress:** `CreateSite` (WordPress or Laravel spec) → a background job under `create_site::*`, polled via `JobStatus`. `MintWordpressLoginToken`, `SetWordpressAutoLogin` → `handle_mutation`, `WordpressAdminUsers`, `AvailableWordpressVersions` → `wordpress_login::*` / `wordpress_users::*` / `wordpress_versions::*`. See [WordPress support](#wordpress-support) above.
* **Lifecycle:** `RestartDaemon` (Unix only).

The dispatch also routes the **services / database-admin** families (`ListServices`, `InstallService`, `StartService`/`StopService`/`RestartService`, `CreateDatabase`/`ListDatabases`/`DropDatabase`/`BackupDatabase`/`RestoreDatabase`, …) to `services::*` / `db_admin::*`.

### The mutation pipeline

Mutations go through `handle_mutation`, which is strict **build → validate → commit** so a failed mutation leaves disk and the live router untouched:

```
1. canonicalize the path (Park/Link) OUTSIDE the config lock
2. take the config mutex; clone the config into `new`
3. compute the delta:
     - SetWebRoot → resolve_web_root_mutation (I/O: validate/detect; see below)
     - everything else → mutate::apply(&mut new, &*router.read(), &req, …) (pure)
4. new.validate()           - never persist an invalid config (incl. WebRootEscapes)
5. startup::build_router    - candidate router (re-scans parked roots, via DetectCache)
6. new.save(config_path)    - atomic write-temp-then-rename
7. *cfg_guard = new; *router.write() = candidate; drop guard; watch_dirty.notify_one()
```

The pure delta lives in `mutate::apply` (`mutate.rs`), which is deliberately I/O-free - paths arrive pre-canonicalised, the router and config are borrowed, and nothing touches the filesystem, clock, or environment. It lowercases the request `name` before every lookup (the router and `cfg.linked` are keyed by lowercased names). For a parked site, `SetPhp`/`SetSecure` record an override via `cfg.overrides.entry(key).or_default()` - using `.entry().or_default()` (never `.insert()`) so a co-existing override on the same path is preserved - and the site **stays parked**. `MutateError` maps to wire `ErrorCode`s (`NotFound`, `AlreadyExists`, `InvalidPath`).

`SetWebRoot` is handled outside the pure `apply` because it does I/O - it needs the target site's `document_root` (read from the router/`cfg.linked`) to validate the requested path or to re-detect. `resolve_web_root_mutation` resolves the path against the document root, **canonicalises both sides** (so a Windows `\\?\` verbatim prefix doesn't spuriously fail the containment check), requires the result be a directory *inside* the project, and stores the relative remainder: on the linked `Site`'s `web_subpath`, or in `cfg.overrides[..].web_root` for a parked site. `path: None` resets to auto-detect (re-detect now for a linked site; drop the override for a parked one). After commit, step 7 pings `watch_dirty` so the watcher reconciles.

### PHP install / update flows

PHP version operations are I/O at the daemon edge:

* **`install_php`** → `php_install::install`: resolve the latest patch from the distribution's live listing, download the CLI + FPM tarballs, safe-extract the single binary from each (tar-member safety via `yerd_php::is_safe_member`), and atomically swap a staging dir into `data/php/php-<minor>/`. A `.yerd-version` marker records the exact patch so it lands atomically with the binaries. **Integrity is TLS-only** - no checksum sidecars, no hash pinning (a deliberate decision). After install, `refresh_php_binaries` re-discovers and hands the updated map to the live `PhpManager` so the proxy can spawn the new pool **without a daemon restart**.
* **`update_php`** upgrades a given minor (or all installed) to the latest patch when `yerd_php::is_newer` says so, then refreshes the cache.
* **`php_updates::poll_and_refresh`** (the periodic task and `CheckPhpUpdates`) repopulates `state.php_updates` and logs notices; it is **failure-tolerant** (network errors log at `debug` and leave the cache untouched). `cached_updates` serves the annotations on `ListPhp` with no network access.
* **`uninstall_php`** is guarded: blocked if the version is assigned to any site, if it is the last installed version while sites remain, or if it is the current default while others are installed. It stops the pool, removes the version dir, and refreshes the binary map.
* **`set_php_settings`** validates each ini key/value (`yerd_core::php_settings::validate_value` + `canonical_value`), persists, then under a single `php_manager` lock updates the settings and restarts every started pool so the new directives take effect. An empty-string value removes a key.

The `reqwest`-backed `ReqwestDownloader` (rustls, no OpenSSL, follows redirects) lives in `php_install.rs` so that `yerd-php` stays dependency-light.

Each of these flows also keeps the **cover shims** in step (next section): an install bundles pcov and reconciles, an uninstall drops the orphaned `pcov.so` and prunes the dangling shims, and `set_default_php` repoints `phpcover` / the versioned set at the new default.

### Cover-shim reconciliation and pcov

The pcov code-coverage launcher (the [`yerd` multi-call binary](./yerd#cover-shims-yerd-as-a-multi-call-binary-cover_shim-rs)) needs two things on the daemon side: the `pcov.so` for each installed PHP version, and a set of managed symlinks in `{data}/bin` for the CLI to be invoked under. Both live in `php_install.rs` and `ipc_server.rs`, and the whole feature is **Unix-only** (no-op elsewhere).

**The managed shim set.** `php_install::reconcile_shims(dirs, yerd_bin, default)` builds and prunes the symlinks under `{data}/bin` from a **single** `discover_bundled` snapshot (so a second scan can't straddle a concurrent install's atomic rename and prune a just-created link):

* `php` - the default (its CLI binary); created if installed and missing/stale, but left alone otherwise so it never fights `set_default_shim`.
* `phpcover` - points at `yerd_bin`; resolves the default version at run time.
* per installed version `v`: `php<v>` → that version's clean CLI binary, and `php<v>cover` → `yerd_bin`.
* it then **prunes** managed `php<X.Y>` / `php<X.Y>cover` symlinks whose version is no longer installed. `managed_shim_version` matches *only* canonical names (rejecting `php`, `phpcover`, leading-zero spellings, and foreign files like `phpunit`), so the pruner only ever removes links yerd created.

`versioned_shim_name` emits the canonical dotted form; `set_default_shim` (used by `set_default_php`) atomically repoints just `php`. All link writes go through an atomic temp-then-rename `place_symlink`.

**pcov fetch.** `ext_install::ensure_pcov_for_installed` is **ungated** (pcov is always bundled, unlike the dumps `.so`) and best-effort. It short-circuits the network entirely when no PHP is installed or every installed version already has its `pcov.so` (`pcov_so_path`), so warm/offline starts never touch GitHub. The `.so` sits beside `yerd-dump.so` under `{data}/php-ext/php-<ver>/`, so a PHP patch update (which wipes `{data}/php/php-<ver>`) never deletes it.

**Wiring (`ipc_server.rs`).** `refresh_pcov_and_shims` fetches pcov for installed versions then reconciles; `reconcile_shims_for` / `reconcile_shims_now` run the reconcile serialized behind `state.shim_reconcile` (the per-daemon mutex), having released the config lock first. `yerd_sibling` derives the `yerd` binary as a sibling of the running `yerdd`. The hooks:

* **startup** - the best-effort background spawn (see [the run loop](#the-run-loop-lib-rs)); also self-heals the cover symlinks if the `yerd` binary moved between runs.
* **PHP install** (`InstallPhp`) - `refresh_pcov_and_shims` after `refresh_php_binaries`.
* **PHP uninstall** (`UninstallPhp`) - removes the orphaned `pcov.so` (file only; the dir is shared with `yerd-dump.so`), then `reconcile_shims_now` to prune the now-dangling shims.
* **set-default** (`SetDefaultPhp`) - `reconcile_shims_for(new_default)` so `phpcover` and the versioned set track the new default.

::: info No new wire types
This is all daemon-internal: **no new IPC `Request`/`Response` variants were added** and `crates/yerd-ipc` was untouched. The shim reconciliation rides on the existing install / uninstall / set-default requests.
:::

## Cert store (`cert_store.rs`)

`DaemonCertStore` implements `yerd_proxy::CertStore`. On the first SNI miss for a host it issues a fresh leaf via the in-memory `CertAuthority` (~395-day validity), persists the PEM under `data/leaves/<host>.{cert,key}.pem`, parses it into a `rustls::sign::CertifiedKey`, and caches it. SNI lookups are normalised (trailing dot stripped, lowercased) so `app.test`, `APP.TEST.`, and `app.test` share one cached `Arc`. The unit tests assert the issue-then-cache identity (`Arc::ptr_eq`), PEM persistence, and case-insensitive lookup.

## Backend resolver (`backend_resolver.rs`)

`DaemonBackendResolver` implements `yerd_proxy::BackendResolver`:

```rust
pub struct DaemonBackendResolver {
    pub php_manager: Arc<Mutex<DaemonPhpManager>>,
    pub wordpress_sites: Arc<RwLock<HashMap<String, bool>>>,
}
```

For a routed `&Site`, `backend_for` locks the `PhpManager` only for the duration of `ensure(site.php())` (which has a fast path for already-running pools), then maps the returned `yerd_php::Listen` to a proxy `Backend`:

```rust
match listen {
    yerd_php::Listen::UnixSocket(p) => Ok(Backend::PhpFpm { socket: p }),
    yerd_php::Listen::TcpLoopback(a) => Ok(Backend::PhpFpmTcp { addr: a }),
}
```

`allows_direct_script_execution` (the trait's other method - see [`yerd-proxy`'s trait seams](../crates/yerd-proxy#trait-seams-certstore-backendresolver-logintokenconsumer)) mirrors `DaemonState::wordpress_sites` directly:

```rust
async fn allows_direct_script_execution(&self, site: &yerd_core::Site) -> bool {
    self.wordpress_sites.read().await.get(site.name()).copied().unwrap_or(false)
}
```

`DaemonPhpManager` is the concrete `PhpManager<TokioProcessSpawner, SystemClock, FastCgiProbe>` used throughout the daemon.

## WordPress support {#wordpress-support}

The `wordpress_*` modules plus `create_site/wordpress.rs` and `tools/wp_cli.rs` back the GUI's "Create a new WordPress site" wizard and one-click admin login (see the user-facing [Sites guide](../../guide/sites#create-a-new-wordpress-site)).

**Detection (`wordpress_detect.rs`).** `detect(document_root)` is a narrow, synchronous marker-file check (`wp-config.php` or `wp-load.php` present) - deliberately not a deep framework probe like `yerd-core`'s web-root detection. `startup::build_routing` runs it for every site on each router rebuild and populates `DaemonState::wordpress_sites`; `ListSites` badges each site from that cache rather than re-checking the filesystem on every poll.

**Scaffolding (`create_site/wordpress.rs`).** `run` is the WordPress counterpart to `laravel.rs`'s `run` (both driven by the shared `create_site::run_streamed`/job-registry plumbing), reporting progress through seven phases in order - **Preflight → Provisioning database → Downloading WordPress → Configuring → Installing → Registering → Done** - mirrored exactly by the wizard's progress stepper. Notable pieces:

* `validate_admin_credentials` (server-side, mirroring `yerd_services::database::validate_db_name`'s "the daemon is the authority" pattern) rejects an empty/whitespace admin username, a password under `MIN_ADMIN_PASSWORD_LEN` (8), or a malformed email - independent of whatever the wizard already validated client-side.
* `resolve_db_name` derives a database name from the site name when the request left one unset, the same fallback the wizard itself uses.
* `apply_permalink_structure` runs `wp rewrite structure '/%postname%/'` after install (WordPress otherwise defaults to unfriendly `?p=123` URLs) - best-effort: a failure only logs a warning (`PermalinkOutcome::Applied`) and never fails or rolls back the job, unlike every earlier phase.
* `enable_default_admin_login` turns on one-click login by default for a wizard-created site (via the same `SetWordpressAutoLogin` mutation the Edit dialog uses) - never for a parked/pre-existing WordPress site, since yerd has no basis for assuming that's wanted for an arbitrary directory.

**One-click login (`wordpress_login.rs`).** `LoginTokenRegistry` mints a short-TTL (30s), single-use, 32-byte random token per `Request::MintWordpressLoginToken`, and implements `yerd_proxy::LoginTokenConsumer` so the proxy can validate/consume one without depending on this crate - see [`yerd-proxy`'s login-token section](../crates/yerd-proxy#one-click-wordpress-admin-login) for the consuming side. `mint_wordpress_login_token` refuses to mint at all (`NotFound`) unless the site exists, is WordPress, has `wp_auto_login` enabled, *and* `DaemonState::wordpress_login_prepend_script` is `Some` - the proxy only ever adds `auto_prepend_file` when both a consumed token and that path are present, so minting despite a missing prepend script would silently burn a token that could never log anyone in. `write_prepend_script` writes the bootstrap script (compiled into the binary via `include_str!`) to `{data}/wordpress-autologin-prepend.php` at every startup, treating a write failure as "one-click login unavailable this boot" rather than fatal.

**URL sync (`wordpress_url_sync.rs`).** After a mutation commits, `sync_site_url` runs `wp option update siteurl`/`home` against the site's *configured TLD* (not a hardcoded `.test`) if it's a WordPress site with WP-CLI and its pinned PHP both installed - best-effort and silent on failure, so a WP-CLI hiccup never fails the mutation it's attached to. `ipc_server`'s `site_needing_url_sync` decides *which* mutations trigger it: `SetSecure` (the scheme flips) plus all four domain mutations `AddDomain`/`RemoveDomain`/`SetPrimaryDomain`/`ResetDomains` (each can change the primary domain a WordPress install should advertise; `AddDomain` is included because re-adding a suppressed apex can flip the derived primary back). It re-reads the just-rebuilt router's primary, so re-running it when nothing changed is an idempotent no-op.

**Admin listing (`wordpress_users.rs`).** `admin_users` runs `wp user list --role=administrator --format=json` and parses the result for the "Sign in as" picker in the Edit dialog - same `NotFound`-if-not-WordPress gate as minting, `Internal` for a WP-CLI/PHP-missing or non-zero-exit/unparseable-JSON failure.

**Version list (`wordpress_versions.rs`).** Caches the wizard's "Core version" dropdown data (a remote `wordpress-versions.json` manifest) with a `(Instant, Vec<WordPressVersionInfo>)` freshness pair on `DaemonState`, served stale-on-fetch-failure rather than blocking the wizard on a flaky network.

**WP-CLI deprecation suppression (`tools/wp_cli.rs`).** WP-CLI's bundled Composer dependencies (`react/promise`, `wp-cli/php-cli-tools`) emit PHP `E_DEPRECATED` notices on newer PHP that would otherwise flood streamed job logs and break anything parsing `--format=json` output. `QUIET_DEPRECATIONS` (`-d error_reporting=E_ALL & ~E_DEPRECATED`) passed as leading `php` flags covers every `wp` invocation the daemon spawns directly - but not a PHP process WP-CLI spawns *internally* via `WP_CLI::launch_self()` (used by `rewrite structure` among other subcommands), since that re-invocation builds its own bare `php <script>` command line with none of the caller's flags. `ensure_quiet_deprecations_scan_dir` writes a tiny drop-in ini to `{data}/wp-cli-quiet.d/` applying the same suppression, and `quiet_deprecations_scan_dir_env` returns a `PHP_INI_SCAN_DIR` value (prefixed with `:` so PHP still scans its compiled-in default directory too) to set as an env var - unlike a CLI flag, an env var *is* inherited by a child process, so it still applies after a `launch_self()` re-exec. Wired into `create_site::run_streamed` (via a `quiet_wp_cli_deprecations: bool` parameter, `true` only for the WordPress scaffolding path, not Laravel's), `wordpress_url_sync.rs`, and `wordpress_users.rs`; duplicated (not shared - different binary) in [`bin/yerd/src/wp_shim.rs`](./yerd#cover-shims-yerd-as-a-multi-call-binary-cover_shim-rs) for the `wp` CLI shim.

## Signals & single instance

`signals::wait_for_shutdown` awaits whichever fires first - `SIGTERM` or `Ctrl-C` on Unix, `Ctrl-C` only elsewhere - then `send_replace(true)` on the shutdown channel so every watcher's `changed().await` resolves. If installing the SIGTERM handler fails it falls back to awaiting `Ctrl-C` so the daemon can't hang forever.

`single_instance::InstanceLock` takes an exclusive advisory lock on `runtime/yerd.lock` (`flock`-style via `fs4` on Unix, `LockFileEx` on Windows). `fs4`'s `try_lock_exclusive` returns `Ok(false)` when another process holds it - the daemon treats that as `DaemonError::AlreadyRunning` (exit `75`) rather than silently allowing a second daemon. The lock is held for the process lifetime and released on drop. Acquisition first hardens the runtime dir to `0o700`.

## Filesystem hardening (`secure_fs.rs`)

The daemon's only access control over the IPC socket is directory/socket permissions (the IPC server does **no peer-credential check**), and the Linux fallback when `XDG_RUNTIME_DIR` is unset is the world-traversable `/tmp/yerd-$UID`. So `secure_fs` enforces:

* `create_private_dir` → `0o700` on the runtime dir (fail-closed: if a different user pre-created it, the `chmod` fails and the daemon refuses to start).
* `restrict_to_owner` → `0o600` on the CA private key and the IPC socket.
* `restrict_writes_to_owner` → `0o644` on the **public** CA cert (world-readable is fine, but it must not be group/world-*writable* or the trust helper refuses to install it as a tamper guard).

On non-Unix targets these are no-ops (Windows ACL hardening is a later item); the directory is still created.

## Tracing (`tracing_init.rs`)

`init(verbose)` installs a compact stderr subscriber at `INFO`/`DEBUG`/`TRACE` for `verbose` `0`/`1`/`2+`. At the default level the embedded DNS server (`hickory_server`) is capped at `WARN` because it logs every inbound query at `INFO` - including routine `NXDomain` for non-`.test` names the OS resolver forwards - which would flood the log. Raising `-v` lifts that cap. The install is **idempotent**: the `try_init` error (fired when a subscriber already exists, e.g. test re-entry) is intentionally swallowed.

## Privilege boundary

`yerdd` runs **entirely unprivileged**. It never `sudo`s, never installs trust stores or resolver config itself, and never binds privileged ports by escalating. When a privileged operation is needed it is performed by [`yerd-helper`](./yerd-helper), invoked through the [`yerd-platform`](../crates/yerd-platform) abstractions (`TrustStore`, `ResolverInstaller`, `PortRedirector`, etc.). The daemon's role for those is read-only: `build_status_report` *probes* whether the CA is trusted, the resolver is installed, and the port redirect is active (each on a blocking thread, errors collapsing to `None`), so `Status`/`Diagnose` can report drift without ever holding elevated capability. See [Elevation & Privileges](../../guide/elevation) for the full model.

## Tests & invariants

* **`tests/lifecycle.rs`** (Unix) brings the daemon up against a tempdir `PlatformDirs` and exercises the real socket end-to-end: a `Ping`/`Pong` boot round-trip with clean shutdown; a `Park` round-trip that asserts the discovered child site appears in `ListSites` and the canonical path is persisted to `yerd.toml`; and a `SetSecure` round-trip asserting the parked site stays parked, is persisted under an `[[overrides]]` table, and is **not** promoted to `[[linked]]`.
* **`tests/no_runtime_deps.rs`** is a dependency-graph invariant: the daemon's default-features runtime graph must not pull `anyhow`, the OpenSSL/native-tls family (`openssl`, `openssl-sys`, `native-tls`, `hyper-tls`, `tokio-native-tls`), or the deprecated `fs2`; and `hyper`/`rustls`/`tokio`/`time` must each resolve to a single version. `webpki-roots` is explicitly allowed (the PHP-install client hits public hosts over rustls). This keeps the install path OpenSSL-free. (`notify` + `notify-debouncer-mini`, added for the watcher, pull none of the forbidden crates.) The actual graph walk is shared with five other crates/binaries - see [`yerd-depcheck`](../crates/yerd-depcheck).
* Module unit tests pin the site-scan/override/web-root-detection semantics (`startup`), the `SetWebRoot` dispatch paths (explicit/auto/escape/not-found, in `ipc_server`), the freshness-stamped detection cache (`detect_cache`), exit codes (`error`), cert issue/cache identity (`cert_store`), mode enforcement (`secure_fs`), lock acquisition (`single_instance`), and idempotent tracing (`tracing_init`).
* **`test_support.rs`** holds daemon-wide test fixtures shared across every module's own `#[cfg(test)]` block: `dirs_in`/`state_in` build a tempdir-rooted `PlatformDirs`/fully-populated `DaemonState` (previously copy-pasted per module - seven near-identical ~80-line copies before consolidation); `sign_manifest` mints a throwaway minisign keypair for tests exercising the signed-`php.json` fetch path. A test needing a non-default `DaemonState` field (e.g. a configured `wordpress_login_prepend_script`) mutates the returned value directly rather than this function growing per-caller parameters.

## See also

* [The Daemon](../../guide/daemon) - operational/user view.
* [IPC Protocol](../ipc-protocol) - the request/response wire contract this binary serves.
* [yerd (CLI)](./yerd) - the primary IPC client.
* [yerd-helper (privileged)](./yerd-helper) - where privileged work happens.
* [Architecture](../architecture) and [Cross-Platform Model](../cross-platform).

---

---
url: 'https://yerd.app/developer/binaries/yerd.md'
---
# yerd (CLI)

`yerd` is the command-line client. It is deliberately thin: it parses
arguments, maps each command to exactly one [`yerd-ipc`](../crates/yerd-ipc)
`Request`, exchanges that request with the [`yerdd`](./yerdd) daemon over a
local socket, and renders the `Response` as either a human-readable block or
`--json`. Almost no domain logic lives here - the daemon owns state and all
privileged work happens in [`yerd-helper`](./yerd-helper).

The one exception is `yerd elevate` / `yerd unelevate`, which do not map to a
single IPC round-trip: they orchestrate the privileged helper locally (under
`sudo`). That path lives in `elevate.rs` and is described in detail
[below](#elevate-the-privileged-orchestrator).

::: info Crate facts
Source: [`bin/yerd`](https://github.com/forjedio/yerd/tree/main/bin/yerd) ·
binary `yerd` (`src/main.rs`), library `yerd` (`src/lib.rs`). Depends on
[`yerd-core`](../crates/yerd-core), [`yerd-ipc`](../crates/yerd-ipc) (with the
`transport` feature) and [`yerd-platform`](../crates/yerd-platform). The user-
facing command catalogue lives in the [CLI Reference](../../reference/cli/).
:::

::: tip Designed fresh, not ported
The v2 command surface was designed from scratch around the daemon/IPC model -
it is **not** a port of the Yerd v1 commands. If you are migrating, see the
[Upgrade Guide](../../guide/upgrading-from-v1).
:::

## Module map

The binary is a one-line wrapper; everything testable lives in the library so
the `tests/cli_e2e.rs` integration test can drive the same code paths.

| File | Role |
| --- | --- |
| `src/main.rs` | Parse args, build a current-thread tokio runtime, call `yerd::run`. |
| `src/lib.rs` | `run()` - the orchestration: branch `elevate`, map, exchange, render, set the exit code. |
| `src/cli.rs` | The clap-derived `Cli` / `Command` surface (no I/O). |
| `src/map.rs` | Pure `to_request` (command → `Request`) and `render` (`Response` → text + exit code). |
| `src/transport.rs` | Resolve the socket path and perform one framed request/response exchange. |
| `src/elevate.rs` | `yerd elevate` / `unelevate`: local privileged orchestration of `yerd-helper`. |
| `src/cover_shim.rs` | Multi-call dispatch: when `argv[0]` is a `phpcover`/`php<ver>cover` alias, exec PHP with pcov enabled (Unix-only). Runs before clap. |
| `src/composer_shim.rs` | Multi-call dispatch: when `argv[0]` is `composer`, exec the default PHP against `{data}/tools/composer/composer.phar` (Unix-only). Runs before clap. See [Dev-tool installers](../dev-tools). |
| `src/wp_shim.rs` | Multi-call dispatch: when `argv[0]` is `wp`, exec WP-CLI - site-aware if cwd is inside a registered site (pins that site's PHP, scopes via `--path=`) (Unix-only). Runs before clap. |
| `src/shim.rs` | Shared PHP-resolution helpers for the cover, composer, and `wp` multi-call shims (default-version resolution, highest-installed fallback). |
| `src/path_cmd.rs` | `yerd path install`/`uninstall`/`print`: edit the user's shell startup file to add `{data}/bin` to `PATH` (local, no IPC; Unix-only). |
| `src/error.rs` | `ClientError` - the client's error type. |

```mermaid
flowchart LR
    args["args"] --> cli["cli::Cli (clap)"]
    cli -->|"Elevate / Unelevate"| elev["elevate::run_elevate"]
    elev --> helper["spawn yerd-helper (sudo)"]
    cli -->|"everything else"| toreq["map::to_request"]
    toreq --> exch["transport::exchange"]
    exch --> render["map::render"]
    render --> out["stdout/stderr + exit code"]
```

## The command surface (`cli.rs`)

`Cli` is the top-level clap parser. The only global flag is `--json`; every
subcommand is one variant of `Command`.

```rust
#[derive(clap::Parser, Debug)]
#[command(name = "yerd", version, about = "Yerd CLI - talks to the yerdd daemon")]
pub struct Cli {
    /// Emit machine-readable JSON instead of human-readable text.
    #[arg(long, global = true)]
    pub json: bool,
    #[command(subcommand)]
    pub command: Command,
}
```

Several commands take a *target* subcommand rather than a positional argument,
which keeps room for non-PHP components later (e.g. `install php 8.5`,
`restart daemon`). The current shape:

| Command | Args / target | Notes |
| --- | --- | --- |
| `ping` | - | Liveness check. |
| `sites` | - | List parked + linked sites. |
| `park <path>` | directory | Each child directory becomes a `.test` site. |
| `link <name> <path>` | name + directory | One named site. |
| `unlink <name>` | name | Remove a linked site. |
| `unpark <path>` | directory | Remove a parked root (see canonicalisation below). |
| `use <first> [version]` | one or two args | One arg = global default PHP; two = a site's version. |
| `set php <setting> <value>` | `SetTarget::Php` | Global PHP ini default. |
| `unset php <setting>` | `UnsetTarget::Php` | Reset to PHP's built-in. |
| `install php <version>` | `InstallTarget::Php` | Download a prebuilt static build. |
| `restart php [version]` / `restart daemon` | `RestartTarget` | Pool(s), or the daemon itself. |
| `uninstall php <version>` | `UninstallTarget::Php` | Remove files; blocked if in use. |
| `list php [--check] [--available]` / `list parked` | `ListTarget` | See flag precedence below. |
| `update php [version]` | `UpdateTarget::Php` | Upgrade to latest; omit version = all. |
| `status` | - | Live daemon/proxy/DNS/ports/CA/PHP snapshot. |
| `doctor [fix]` | optional `DoctorAction::Fix` | Diagnose; `fix` attempts safe repairs. |
| `secure <name>` / `unsecure <name>` | name | Toggle HTTPS for a site. |
| `root <name> [path] [--auto]` | name + optional path | Set/reset a site's served web root → `SetWebRoot`. |
| `domain <action>` | `DomainAction`: `list [site]` / `add <site> <domain>` / `remove <site> <domain>` / `primary <site> <domain>` / `reset <site>` | Manage a site's routable domains, subdomains, and wildcards. All but `list` map to a domain `Request`; `list` is rendered locally (it needs the TLD to synthesize default `{name}.{tld}` domains). |
| `elevate [target]` / `unelevate [target]` | optional `ElevateTarget` | Privileged setup - handled locally. |

The `ElevateTarget` enum enumerates the three privileges: `Trust` (system CA
store), `Resolver` (`*.<tld>` DNS routing) and `Ports` (bind 80/443). Omitting
the target means "all three".

## Cover shims: `yerd` as a multi-call binary (`cover_shim.rs`)

`yerd` doubles as the pcov **code-coverage** launcher. In `{data}/bin` the daemon
maintains a set of *cover* symlinks - `phpcover` (the default PHP version) and
`php<major>.<minor>cover` (e.g. `php8.4cover`) - each pointing back at the `yerd`
binary itself. Running one of those names makes `yerd` behave as a thin PHP
wrapper that turns coverage on, while the clean `php` / `php<ver>` shims stay
untouched so ordinary PHP carries **no coverage overhead**.

This is dispatched in `main.rs` **before clap ever parses**:

```rust
#[cfg(unix)]
if let Some(code) = yerd::cover_shim::dispatch() {
    return code;
}
```

`dispatch` inspects `argv[0]`'s basename:

* `parse_cover_name` matches `phpcover` (→ default) and `php<major>.<minor>cover`
  (→ that explicit version) **exactly**. Any other name - `php`, a clean
  `php8.4`, `phpunit`, malformed forms like `php8.cover` - returns `None`, so the
  call falls straight through to the normal `Cli::parse()` CLI. `yerd <subcommand>`
  is never intercepted.
* On a match it resolves `(php_binary, "major.minor")`. For an explicit version
  that is `{data}/php/php-<ver>/bin/php` (erroring if the version isn't
  installed). For the default it reads the `php` shim's link target (falling back
  to the highest installed minor whose CLI binary exists).
* It then locates that version's `{data}/php-ext/php-<ver>/pcov.so` (the daemon
  bundles it; see [yerdd · cover-shim reconciliation](./yerdd#cover-shim-reconciliation-and-pcov)),
  reads Yerd's CLI ini (`{data}/php-cli.ini`, treating a missing file as empty),
  appends pcov's `extension`/`pcov.enabled` directives
  (`yerd_core::php_settings::render_cover_ini`), and atomically writes the
  result to `{data}/php-ext/php-<ver>/cover.ini`. This read-render-write happens
  on **every** invocation - `cover.ini` is never cached or diffed against the
  last run, so it can't drift out of sync with `php-cli.ini` (whose contents
  change whenever a PHP setting is edited). It then `exec`s PHP with `PHPRC`
  set to that path, followed by the caller's own args. `exec` replaces the
  process, so on success it never returns; a missing binary, missing
  `pcov.so`, or a write failure prints a `yerd:` diagnostic and returns
  `ExitCode::FAILURE`.

`PHPRC` rather than `-d` flags is deliberate: `-d` only affects the exec'd
process itself, but `PHPRC` is an environment variable, so it's inherited by
any PHP process that process spawns in turn (e.g. `php artisan test`'s child
PHPUnit/Pest/paratest run, launched via `PHP_BINARY` by a Symfony `Process`
that inherits the parent's environment) - which is what actually needs pcov
loaded to produce a coverage report. Setting `PHPRC` on the `Command` overrides
that one key and leaves the rest of the environment inherited (no
`env_clear()` is called), so if the caller's shell already has its own `PHPRC`
(for example from the `yerd path install` rc-block, which points the plain
`php` shim at `{data}/php-cli.ini`), the cover shim's value wins for the
exec'd process - intentional, not a conflict to resolve.

The same logic also backs the `yerd coverage <args…>` **subcommand**, which
reaches it from the other direction. Rather than being keyed on `argv[0]`,
`lib.rs::run` intercepts `Command::Coverage` locally (like `elevate`/`path`,
before the daemon round-trip) and calls `cover_shim::run_coverage`, which is just
`run(&CoverSpec::Default, args)` with the clap-captured passthrough args. So the
subcommand and the `phpcover` shim share one implementation and one code path;
the only difference is where the forwarded args come from (`argv[0]` dispatch
forwards `env::args_os().skip(1)`, the subcommand forwards its `Vec<OsString>`).

::: info Unix-only
The `dispatch()` call is `#[cfg(unix)]` and the cover symlinks are only ever
created on Unix - on other platforms `yerd` is always just the CLI. PHP itself
reads `PHP_BINARY` from `/proc/self/exe`, so although the process was launched
via the cover alias, `argv[0]` (left at the real `php` path) and `PHP_BINARY`
both report the genuine interpreter, not the shim name.
:::

`composer` works the same way (`composer_shim.rs`): when `argv[0]` is `composer`,
`yerd` resolves the default PHP (sharing the helpers in `shim.rs`) and `exec`s it
against `{data}/tools/composer/composer.phar`. Its `dispatch()` runs in `main.rs`
just before the cover dispatch. See [Dev-tool installers](../dev-tools) for how
the daemon installs the phar and creates the `composer` symlink.

`wp` is a third multi-call shim (`wp_shim.rs`), for **WP-CLI**. Unlike the cover
and composer shims it is *site-aware*: when the current directory is inside a
registered site, it asks the daemon for the live site list (`Request::ListSites`,
bounded to 300ms so a slow or unreachable daemon never stalls an ordinary `wp`
invocation) and, on a match, runs WP-CLI under *that site's* pinned PHP version,
scoped to its served root via `--path=` - so `wp option get siteurl` and friends
behave the way the site is actually served, with no `--path` flag or `cd`-ing
into `public/` needed. Outside any registered site, or if the daemon is
unreachable, slow, or finds no match, it falls back to the default managed PHP
with no working-directory change, identical to the cover and composer shims. If
cwd *is* inside a site but that site's pinned PHP version isn't installed, it
fails loudly rather than silently running under an unrelated version.

WP-CLI re-invokes its own entry point for some subcommands
(`WP_CLI::launch_self()`, used by `rewrite structure` among others) via a raw
shell string built from `argv[0]` - on macOS that path always runs through
`~/Library/Application Support/...`, which always contains a space and would
silently split the re-invoked shell command. The shim works around this by
exec'ing WP-CLI's boot script under its bare file name with `cwd` set to the
script's own directory rather than the site, keeping "which WordPress install"
and "process cwd" decoupled via `--path=` - see
[`bin/yerdd/src/create_site/wordpress.rs`](https://github.com/forjedio/yerd/blob/main/bin/yerdd/src/create_site/wordpress.rs)
for the daemon-side scaffolding path that hits the same bug and works around it
the same way.

## Pure mapping and rendering (`map.rs`)

`map.rs` is the heart of the client and is entirely I/O-free, which is what
makes it exhaustively unit-testable. It has two directions.

### `to_request` - command → `Request`

```rust
pub fn to_request(cmd: &Command) -> Result<Request, ClientError>
```

Each `Command` arm produces exactly one `yerd_ipc::Request`. Crucially, this is
also where **client-side validation** happens, so a bad site name or PHP
version is a clean usage error *before* any socket connect:

* `validate_name` constructs a throwaway `Site::linked(name, "/", …)` purely to
  run the same name rules the daemon would.
* `parse_php` parses the version through `PhpVersion::FromStr`.
* `validate_php_setting` checks the setting against
  `yerd_core::php_settings::is_supported` and validates the value with
  `validate_value`.

A handful of mappings encode real design decisions worth knowing:

* **`use`** is overloaded by arity. One argument (`yerd use 8.5`) maps to
  `Request::SetDefaultPhp`; two (`yerd use blog 8.5`) maps to `Request::SetPhp`.
* **`unset php <setting>`** maps to `Request::SetPhpSettings` with an *empty
  string* value - empty value is the wire convention for "remove / reset".
* **`root <name> [path] [--auto]`** maps to `Request::SetWebRoot { name, path }`,
  where `--auto` (or omitting the path) sends `path: None` to reset the site to
  auto-detection. The name is validated client-side like `secure`/`link`.
* **`domain`** maps each sub-action through `domain_request`: `add`/`remove`/`primary`/`reset` become `AddDomain`/`RemoveDomain`/`SetPrimaryDomain`/`ResetDomains`, each validating the site name and (for the first three) the domain shape client-side (`validate_domain`) before any socket connect. `domain list` is *not* mapped to a request - it is rendered locally by `render_domains`/`site_domains`, which needs the TLD (from a `DaemonInfo` round-trip) to synthesize a default site's `{name}.{tld}` domains.
* **`list php`** flag precedence: `--available` wins over `--check`. With
  neither, it sends `Request::ListPhp` (cached); `--check` polls the
  distribution (`CheckPhpUpdates`); `--available` lists installable versions.
* **`unpark`** passes the path through as a string here (pure); the actual
  canonicalisation happens at the I/O boundary in `run` (see below).
* **`elevate` / `unelevate`** are deliberately *not* mapped to a single
  request. Their arms return `ClientError::Usage(...)` to keep the `match`
  total; `run` branches to `elevate::run_elevate` before ever calling
  `to_request`.

### `render` - `Response` → text + exit code

```rust
pub fn render(resp: &Response, json: bool) -> Rendered

pub struct Rendered { pub stdout: String, pub stderr: String, pub code: u8 }
```

`render` formats a `Response` into stdout/stderr and a process exit code. Two
properties are intentional and tested:

1. **The exit code is computed once, before branching on `--json`,** so the
   JSON and human paths always agree. `doctor_exit_code` returns `1` for a
   `Response::Error`, `1` for any `Severity::Fail` doctor finding (in
   `Diagnoses` or a `DoctorFix` report's `manual` list), else `0`.
2. **`Response` is `#[non_exhaustive]`.** An unknown variant from a newer daemon
   falls through to a benign `"unexpected response from daemon"` on stderr
   rather than panicking.

The formatters render tab-separated tables (`sites`), annotated version lists
(marking the default and any available updates), and a multi-line `status`
block. `status` carries small but real semantics - for example `fmt_port`
distinguishes a plain rootless fallback (`80 → 8080 (fallback)`) from a macOS
`pf` redirect that makes the privileged port reachable (`80 → 8080
(redirected)`), and empty `daemon_version` (an older daemon, `#[serde(default)]`)
renders as `unknown` rather than blank.

## Transport (`transport.rs`)

The client and daemon must agree on the socket path *without* a config
exchange. They do so by deriving it identically from
`yerd_platform::Paths::resolve()`:

```rust
#[cfg(unix)]
pub async fn exchange(req: &Request) -> Result<Response, ClientError> {
    let dirs = ActivePaths::new().resolve()?;
    exchange_at(&dirs.runtime.join("yerd.sock"), req).await
}
```

`exchange_at` is factored out so integration tests can target a tempdir socket.
It connects with `interprocess` (`GenericFilePath`), then frames one request and
reads one response using `yerd-ipc`'s `write_message` / `read_message` /
`FrameDecoder` with `DEFAULT_MAX_FRAME`. A closed connection with no reply
becomes `ClientError::DaemonUnreachable`.

::: warning Windows is not yet a client
`exchange` on non-Unix targets returns `DaemonUnreachable` immediately: the
daemon's Windows pipe name is currently PID-based and not derivable by a client.
This is tracked as a Phase-2 follow-up - treat Windows CLI support as roadmap.
:::

## Orchestration and exit codes (`lib.rs`)

`run` ties the pieces together. It does **not** auto-start the daemon - if the
socket is unreachable it reports an error (or, for `doctor`, a synthetic FAIL).
The flow:

1. Branch `Elevate` / `Unelevate` to `elevate::run_elevate` and return.
2. `map::to_request`; on `Err` print `yerd: <e>` and exit `2`.
3. `canonicalize_unpark` rewrites an `Unpark` request's path to its canonical
   form at the I/O boundary, so a relative/symlinked path the user typed matches
   the canonical string the daemon stored when the directory was parked. (The
   daemon matches `unpark` *exactly* and deliberately does not canonicalise, so
   an already-deleted directory is still removable by its stored path.)
4. `transport::exchange`, then `map::render`, then print and exit with the
   rendered code.

Two extra behaviours live here:

* After a successful global `yerd use <ver>` (human output only),
  `print_php_path_hint` prints where the managed `php` shim lives and warns if a
  different `php` shadows it earlier on `PATH`.
* For `doctor` specifically, a down daemon is itself a FAIL: `run` synthesises a
  `DiagnosisCode::DaemonDown` `Diagnoses` response and renders it through the
  normal path, so `--json` and the exit code behave like any other doctor run
  (exit `1`) instead of the generic "unreachable" code.

### Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. |
| `1` | Daemon error response, or a doctor `Fail` finding. |
| `2` | Client-side usage error (bad name/version/setting - before connecting). |
| `69` | Daemon unreachable (`EX_UNAVAILABLE`). |
| `70` | Could not build the tokio runtime (`main.rs`). |
| `74` | Other transport/IO failure (`EX_IOERR`). |
| `77` | `elevate` not run as root (`EX_NOPERM`). |
| `78` | `elevate` on a non-Unix host / unsupported target (`EX_CONFIG`). |

The `ClientError` enum (`error.rs`) is `#[non_exhaustive]` and covers `Usage`,
`DaemonUnreachable`, `Ipc` (from `yerd_ipc::IpcError`), `Platform` and
`Fingerprint`.

## `elevate`: the privileged orchestrator

`yerd elevate` is run via `sudo` and is the one command that does not map to a
single IPC request. Its design follows a strict trust model (see
[Elevation & Privileges](../../guide/elevation)):

* It runs as root **only to orchestrate.** It fetches read-only facts
  (`Request::DaemonInfo` → `Response::Info`: DNS address, TLD, CA path +
  fingerprint, bound HTTP/HTTPS ports) from the *invoking user's* daemon, then
  spawns the audited `yerd-helper` once per target. The daemon itself is never
  restarted as root.
* Under `sudo` the process env points at root, so the user's socket is
  reconstructed from `SUDO_UID` (uid-based, home-independent):
  `/run/user/<uid>/yerd/yerd.sock` then `/tmp/yerd-<uid>/yerd.sock`.
* The `yerdd` and `yerd-helper` binaries are derived from `yerd`'s own trusted
  `current_exe` siblings - never from the daemon - so a forged daemon cannot
  point root's `setcap` at an arbitrary binary.
* Before trusting the CA pem, the path (the only one taken from the daemon) is
  owner-checked against the invoking uid and rejected if group/world-writable.
* The helper is spawned with `env_clear()` and re-validates every argument
  independently.

`plan_invocation` is a pure function mapping `(ElevateTarget, undo)` to a
`yerd_platform::HelperInvocation`, and it is cfg-gated per OS:

| Target | macOS | Linux |
| --- | --- | --- |
| `trust` | `InstallCa` / `UninstallCa` | same |
| `resolver` | `InstallResolver` / `UninstallResolver` | same |
| `ports` | `InstallPortRedirect` / `UninstallPortRedirect` (a `pf` redirect 80→http, 443→https; reversible) | `Setcap` (grants `cap_net_bind_service` to `yerdd`); **no clean reverse**, so `unelevate ports` prints `setcap -r` guidance |

Helper exit codes are classified: `0` is success, `78` (`EX_CONFIG`) is treated
as a *skip* ("unsupported on this host", e.g. resolver without
a supported Linux resolver manager), and anything else is a failure that flips the run's exit
code to `1`.

## Tests and invariants

The crate is tested at two levels.

**Unit tests in `map.rs`** assert the pure invariants directly:

* `maps_each_command_to_its_request` - one assertion per command arm, including
  the `use` arity split, `--available` winning over `--check`, and `restart php`
  (specific) vs. `restart php` with no version (`RestartAllPhp`).
* `rejects_bad_version_and_name_before_connect` - bad names, versions and PHP
  settings produce `ClientError::Usage` with no I/O.
* Rendering tests pin the human output and, importantly,
  `renders_doctor_and_sets_exit_code_on_fail` /
  `json_rendering_is_valid_and_codes_match` verify the JSON and human paths
  produce the **same** exit code.

**`tests/cli_e2e.rs`** boots a real daemon on a tempdir (only the IPC task; no
proxy/DNS, since no shipped command touches them) and drives every command
through `map::to_request` + `transport::exchange_at`. It exercises `park` →
`sites`, `link`/`unlink`, per-site `use`, the `secure`/`unsecure` toggle,
`status`, `doctor` (asserting the `NoPhpInstalled` FAIL renders as exit `1`),
`list parked`, and the canonical-path `unpark` round-trip (including idempotent
re-`unpark`). This is the test that justifies the lib/bin split in `lib.rs`:
binary-only crates expose no Rust API to integration tests, so the modules are
published as a library.

## See also

* [CLI Reference](../../reference/cli/) - full command catalogue and examples.
* [yerdd (daemon)](./yerdd) - the server the CLI talks to.
* [yerd-helper (privileged)](./yerd-helper) - what `elevate` spawns.
* [IPC Protocol](../ipc-protocol) - the framing and `Request`/`Response` types.
* [Elevation & Privileges](../../guide/elevation) - the user-facing trust model.

---

---
url: 'https://yerd.app/developer/binaries/yerd-helper.md'
---
# yerd-helper (privileged)

`yerd-helper` is the **only** privileged component in Yerd and therefore the project's single security boundary. The daemon ([`yerdd`](./yerdd)) and the CLI ([`yerd`](./yerd)) run entirely as your user; the small set of operations that genuinely require root - trusting the local CA, redirecting `.test` DNS, granting the daemon permission to bind low ports - are handed to this binary, which validates everything, performs exactly one operation, and exits.

For the user-facing model of when and how elevation happens, see [Elevation & Privileges](../../guide/elevation). This page is the contributor-level reference: the module map, the hard rules, the argv wire contract, the per-operation implementations, and the invariants enforced by tests.

::: info One-line summary
`yerd-helper` is a stateless, no-network, no-shell, one-shot. It takes a typed operation over a frozen argv contract, re-validates it from scratch (it does not trust the daemon), does the work, and returns a `sysexits.h` exit code the daemon interprets.
:::

## Where it sits

```mermaid
flowchart LR
    cli["yerd (CLI)<br/>unprivileged"] -->|IPC socket| daemon["yerdd<br/>unprivileged"]
    cli -->|"sudo yerd elevate (elevation only)"| helper["yerd-helper<br/>privileged, one-shot"]
```

The daemon never spawns `yerd-helper` for itself under ambient privilege. Elevation is driven by `yerd elevate` (`yerd elevate [trust|resolver|ports]`), which is the moment a user supplies `sudo` / an admin prompt. The helper inherits that elevated context, does one job, and exits. There is no resident privileged process.

Source: [`bin/yerd-helper`](https://github.com/forjedio/yerd/tree/main/bin/yerd-helper).

## The hard rules

These are not aspirational - they are enforced by code structure, lints, and tests.

1. **Strict typed args; never shell out.** Every external command goes through `ops::run_command`, which builds a `std::process::Command` with arguments pushed one at a time. There is no `sh -c`, no string interpolation, no glob expansion. The child's environment is wiped with `env_clear()` and given a single pinned `PATH`.
2. **Never take remote network input.** The helper reads only its argv and known local files. The resolver installer performs one bounded loopback DNS probe against `127.0.0.1:53`; it opens no remote connection.
3. **One operation, then exit.** No event loop, no daemonization, no persisted state. `main` parses one invocation, dispatches it once, and returns an `ExitCode`.
4. **Minimal, auditable dependencies.** The runtime crate graph is tiny: `clap`, `thiserror`, `hex`, `pem`, plus the workspace's own `yerd-core` and `yerd-platform`. A test (`tests/no_runtime_deps.rs`) walks `cargo metadata` and **fails the build** if `tokio`, `reqwest`, `openssl`, `openssl-sys`, or `native-tls` ever appear in the normal-dependency graph.
5. **Effective-UID check, debug-only bypass.** Before any side effect the helper confirms its effective UID is 0. The only way to skip the check is a hidden `--skip-priv-check` flag that **does not exist in release builds** (it is compiled out by `cfg(debug_assertions)`).
6. **Defence in depth.** The helper does not trust the daemon. Every typed value is re-parsed and re-validated here, even though the daemon already validated it.

`#![forbid(unsafe_code)]` is set at the crate root, so even the UID lookup avoids raw FFI to `geteuid`.

## Module map

| File | Responsibility |
|---|---|
| `src/main.rs` | Entry point: parse → drop privileges' cwd → UID check → dispatch → exit code |
| `src/cli.rs` | clap-derived CLI; maps subcommands to `HelperInvocation`; debug-build wire-drift cross-check |
| `src/privilege.rs` | `is_privileged()` - effective-UID == 0 check, per-OS |
| `src/validate.rs` | Defence-in-depth validators (absolute path, file exists, basename, TLD, PEM↔fingerprint) |
| `src/exec.rs` | `dispatch(HelperInvocation)` → the right `ops::*` function |
| `src/ops/mod.rs` | `run_command` (pinned-`PATH` subprocess) and `atomic_write` |
| `src/ops/ca.rs` | `install-ca` / `uninstall-ca` (Linux trust anchors, macOS System keychain) |
| `src/ops/resolver.rs` | `install-resolver` / `uninstall-resolver` (systemd-resolved, NetworkManager dnsmasq, `/etc/resolver/<tld>`) |
| `src/ops/setcap.rs` | `setcap` (Linux only) |
| `src/ops/port_redirect.rs` | `install-port-redirect` / `uninstall-port-redirect` (macOS pf, only) |
| `src/error.rs` | `HelperError`, `ValidationReason`, `CommandReason`, and the exhaustive `exit_code` mapping |

## main: the control flow

`main.rs` is intentionally short. On an unsupported OS (anything but Linux/macOS in Phase 1) it prints a message and exits `78` (`EX_CONFIG`). On a supported OS:

```rust
fn run() -> ExitCode {
    let parsed = match cli::parse(std::env::args_os()) {
        Ok(p) => p,
        Err(e) => {
            eprintln!("yerd-helper: {e}");
            return ExitCode::from(error::exit_code(&e));
        }
    };

    // Defang any relative-path argv before doing any per-op work.
    let _ = std::env::set_current_dir("/");

    if !parsed.skip_priv_check && !privilege::is_privileged() {
        let e = error::HelperError::NotPrivileged;
        eprintln!("yerd-helper: {e}");
        return ExitCode::from(error::exit_code(&e));
    }

    if let Err(e) = exec::dispatch(parsed.invocation) {
        eprintln!("yerd-helper: {e}");
        return ExitCode::from(error::exit_code(&e));
    }
    ExitCode::SUCCESS
}
```

Two details worth calling out:

* The `set_current_dir("/")` before any per-op work neutralises any relative-path surprises in the inherited working directory.
* `main` is the **only** place that converts a `HelperError` into an exit code. Everything else returns `Result<(), HelperError>`.

## Effective-UID check (`privilege.rs`)

```rust
#[must_use]
pub fn is_privileged() -> bool {
    effective_uid() == Some(0)
}
```

The implementation is per-OS and deliberately avoids `unsafe`:

* **Linux** parses `/proc/self/status` for the `Uid:` line (`real effective saved fsuid`) and reads the effective field. If `/proc` is missing (chroot, minimal container), it conservatively returns `None` → `is_privileged()` is `false`. Failing closed with `NotPrivileged` is safer than assuming root.
* **macOS** shells out to `/usr/bin/id -u` **by absolute path with `env_clear()`**, so a poisoned `PATH` from the elevation mechanism cannot redirect the lookup.

### The debug-only bypass

The bypass flag exists only so integration tests can exercise the dispatch path without actually being root:

```rust
#[cfg(debug_assertions)]
#[arg(long, global = true, hide = true)]
pub skip_priv_check: bool,
```

In release builds the field is not compiled at all, and `skip_priv_check_value()` is a `const false`. A shipped binary therefore cannot be told to skip the UID check - passing `--skip-priv-check` to a release build is simply an unknown flag (rejected as `EX_USAGE`).

::: warning
`--skip-priv-check` is debug-only and hidden. It never reaches a release artifact. If you are reading this in a packaged build, the flag does not exist.
:::

## The argv wire contract

The daemon and helper communicate by argv, not by a serialization format. The shape is **frozen** and owned by `yerd_platform::HelperInvocation`:

* The daemon builds an invocation and calls `HelperInvocation::to_argv()` to render argv.
* The helper consumes argv. Its primary parser is the clap layer in `cli.rs`; `HelperInvocation::from_argv` is the lower-level reference parser that the contract is defined against.

`HelperInvocation` (in [`crates/yerd-platform/src/helper.rs`](https://github.com/forjedio/yerd/tree/main/crates/yerd-platform/src/helper.rs)) has one variant per operation:

```rust
#[non_exhaustive]
pub enum HelperInvocation {
    InstallCa { ca_pem_path: PathBuf, fp: CaFingerprint },
    UninstallCa { fp: CaFingerprint },
    InstallResolver { tld: String, addr: SocketAddr },
    UninstallResolver { tld: String },
    Setcap { daemon_binary: PathBuf },
    InstallPortRedirect { http_from: u16, http_to: u16, https_from: u16, https_to: u16 },
    UninstallPortRedirect,
}
```

`to_argv` always emits the operation tag first (one of the `&str` constants in `yerd_platform::error::ops`), then alternating `--flag` / value pairs. Fingerprints render as 64 lowercase hex chars; socket addresses use their `Display` form; paths pass through as native `OsString`; TLDs verbatim.

### CLI surface

The clap layer mirrors the enum one-for-one:

| Subcommand | Flags | OS |
|---|---|---|
| `install-ca` | `--pem <PATH>` `--fingerprint <HEX>` | Linux, macOS |
| `uninstall-ca` | `--fingerprint <HEX>` | Linux, macOS |
| `install-resolver` | `--tld <NAME>` `--addr <SOCKETADDR>` | Linux, macOS |
| `uninstall-resolver` | `--tld <NAME>` | Linux, macOS |
| `setcap` | `--binary <PATH>` | Linux only (macOS → `Unsupported`) |
| `install-port-redirect` | `--http-from` `--http-to` `--https-from` `--https-to` (all `<PORT>`) | macOS only |
| `uninstall-port-redirect` | (none) | macOS only |

The parser is configured `arg_required_else_help = true` and `disable_help_subcommand = true`. Unknown subcommands and unknown flags are rejected by clap and surface as `HelperError::ArgvUsage` (exit `64`).

### Debug-build wire-drift cross-check

clap and `from_argv` are two independent parsers of the same argv. If a clap upgrade ever normalised argv differently from the hand-written `from_argv`, the two could silently diverge - a wire-contract drift bug. `cli::parse` guards against this in **debug builds only**:

```rust
#[cfg(debug_assertions)]
{
    if argv.len() > 1 {
        let tail: Vec<OsString> = argv.iter().skip(1).cloned().collect();
        // Strip the global debug-only flag before handing to from_argv.
        let filtered: Vec<OsString> = tail
            .into_iter()
            .filter(|a| a != "--skip-priv-check")
            .collect();
        if let Ok(parsed) = HelperInvocation::from_argv(&filtered) {
            if invocation_tag(&parsed) != invocation_tag(&invocation) {
                return Err(HelperError::WireDrift {
                    clap: invocation_tag(&invocation),
                    from_argv: invocation_tag(&parsed),
                });
            }
        }
    }
}
```

If the two parsers disagree on the operation tag, dev/CI builds fire `HelperError::WireDrift` (exit `70`, `EX_SOFTWARE`). The check is `cfg(debug_assertions)`-gated so that a benign clap upgrade can never brick a shipped release binary - at worst CI catches the drift first.

The integration test `tests/argv_contract.rs` is the twin of this in-source check: for every variant it asserts `from_argv(inv.to_argv())` round-trips back to the same operation tag and re-serialises to the identical argv.

## Validation (`validate.rs`)

The helper re-validates from scratch. Highlights:

```rust
pub fn require_existing_file(path: &Path) -> Result<(), HelperError> {
    if !path.is_absolute() { /* PathNotAbsolute */ }
    let meta = fs::symlink_metadata(path) /* PathMissing */;
    if !meta.file_type().is_file() { /* PathNotFile */ }
    Ok(())
}
```

* **Paths must be absolute and exist**, and must be a regular file. The helper **deliberately does not canonicalise** - canonicalising a path an attacker may control between the `canonicalize` and the `open` introduces a TOCTOU window. It uses `symlink_metadata` and operates on the path as given.
* **`setcap` basename must be `yerdd`** (`require_basename_yerdd`). This bounds the blast radius: even if the daemon were tricked into requesting `setcap` on an arbitrary binary, the helper refuses anything not named `yerdd`.
* **TLD re-parsed through `yerd_core::Tld`** (`require_valid_tld`), so traversal-style inputs like `../etc/passwd` are rejected by the helper's own validation, not just the daemon's.
* **PEM ↔ fingerprint binding** (`require_pem_matches_fingerprint`): the helper reads the PEM, requires **exactly one** `CERTIFICATE` block, computes its SHA-256, and compares it against the argv-supplied fingerprint. A mismatch is `HelperError::FingerprintMismatch`. This closes the "swap a different PEM into the runtime dir" attack: the helper provably installs the certificate whose fingerprint the daemon chose, and on Linux it re-emits the PEM from the validated DER rather than copying any bytes the daemon may have prepended outside the certificate block.

## Subprocess hygiene (`ops/mod.rs`)

Two shared primitives back every operation.

`run_command` pins the environment for every external tool:

```rust
const PINNED_PATH: &str = "/usr/sbin:/usr/bin:/sbin:/bin";

let mut cmd = Command::new(program);
cmd.env_clear().env("PATH", PINNED_PATH);
for a in args { cmd.arg(a); }
```

Failure modes are typed: a `NotFound` spawn error becomes `CommandReason::NotFound`, other spawn errors `Spawn`, a non-zero exit `NonZero(code)`, and a signal kill `Signal`.

`atomic_write` writes to a `.tmp` sibling in the same directory, `fsync`s it, then `rename(2)`s into place - no partial-write or replace race. The mode is set **at creation time** via `OpenOptionsExt::mode` (no create-then-chmod window): `0o600` for anchor PEMs, `0o644` for world-readable resolver files and drop-ins.

## Operations

Each op lives in one file with its per-OS branches behind `#[cfg(target_os = ...)]`, so it can be audited end-to-end in one place. All ops are **idempotent**: re-running an install is a no-op or benign, and uninstalling something already absent returns success.

### install-ca / uninstall-ca

**Linux.** Picks the first present anchor directory in precedence order - `/usr/local/share/ca-certificates` (Debian/Ubuntu/Alpine), `/etc/pki/ca-trust/source/anchors` (RHEL/Fedora), `/etc/ca-certificates/trust-source/anchors` (Arch) - writes `yerd-<first-16-hex-of-fp>.crt`, then runs the matching refresh command (`update-ca-certificates`, `update-ca-trust extract`, or `trust extract-compat`). Uninstall reads the anchor dir, matches by fingerprint, removes the file, and refreshes. An unrecognised layout returns `ValidationReason::NoAnchorDir`.

**macOS.** Runs `security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <pem>` (mkcert's approach). `add-trusted-cert` exits non-zero when the cert is already present (`errSecDuplicateItem`); the helper tolerates that **only** after confirming via `security find-certificate -Z -a` that the cert really is in the System keychain. Uninstall probes the keychain first (idempotent) then `security delete-certificate -Z <FP> …`.

### install-resolver / uninstall-resolver

**Linux.** The helper prefers systemd-resolved, detected from `/etc/resolv.conf` or `/run/systemd/resolve`; it writes `/etc/systemd/resolved.conf.d/yerd-<tld>.conf` and reloads resolved. Otherwise it supports NetworkManager only when `/etc/resolv.conf` positively identifies NetworkManager as its generator. It requires `dnsmasq` and `nmcli`, then atomically writes `/etc/NetworkManager/conf.d/yerd-dnsmasq.conf` plus `/etc/NetworkManager/dnsmasq.d/yerd-<tld>.conf`. After `nmcli general reload conf dns-full`, the helper polls for up to five seconds until resolv.conf points to `127.0.0.1` and a loopback DNS query for Yerd's TLD returns `127.0.0.1`; command success without that post-condition triggers rollback. Rollback failures are reported. Uninstall removes all Yerd-owned artifacts regardless of which manager is currently active and reloads only managers whose files changed.

**macOS.** Writes `/etc/resolver/<tld>`. If a foreign file already exists there (Valet/Herd/an older Yerd) and does not already point at our responder, it is backed up best-effort into the system backups dir as `<tld>-<unixsecs>.conf` before being overwritten; a backup failure is logged and swallowed, never fatal. No reload is needed - macOS picks up the new file on the next query.

`uninstall-resolver` on macOS is a **restore**, not a bare delete: it puts the newest backup back over `/etc/resolver/<tld>` (then clears all of that tld's backups), falling back to a plain removal when there's nothing to restore. Because the helper runs as root and the backups dir is world-traversable (`0755`), restore is **guarded** - the dir and chosen file must be root-owned, the file a non-symlink regular file with no group/other write bit, and its bytes must pass `resolver_file::restorable` (parse as a real resolver file). The destination is replaced atomically; on a write failure the live file and backups are left intact. This closes a local DNS-hijack vector (a planted future-stamped backup) and never restores empty/garbage content.

### setcap (Linux only)

```rust
validate::require_existing_file(binary)?;
validate::require_basename_yerdd(binary)?;
run_command("setcap", "setcap", ["cap_net_bind_service=+ep", binary_str.as_ref()])
```

Grants `yerdd` the ability to bind ports 80/443 without being root. On macOS this op returns `HelperError::Unsupported { operation: SETCAP }` (macOS uses the pf port redirect instead).

### install-port-redirect / uninstall-port-redirect (macOS only)

macOS has no `setcap`, so the rootless daemon cannot bind 80/443 directly. Instead the helper installs a pf `rdr` redirect (rule text composed by `yerd_platform::pure::pf_anchor`) plus a `LaunchDaemon` to re-apply it at boot. The flow is carefully ordered for safety:

1. Reject any zero port (`ValidationReason::PortInvalid`).
2. Write the inert anchor-rules file.
3. Edit the canonical `/etc/pf.conf` to reference the anchor (preserving its contents and Apple's default anchors), keeping the original for rollback.
4. `pfctl -f /etc/pf.conf` both validates and loads; if it rejects the edited config the helper **rolls the pf.conf edit back** before returning the error, so a broken config is never persisted. `pfctl -e` ("already enabled" is success) is best-effort.
5. Only after a clean load does it install the boot-persistence `LaunchDaemon` (`chown root:wheel`, then `launchctl bootout` for idempotency, then `bootstrap`).

Uninstall reverses this in the safe order: tear down the `LaunchDaemon`, remove the hook lines from `/etc/pf.conf` and reload (leaving pf's enabled state as-is), then delete the anchor and plist files - so pf.conf never references a missing anchor.

## Errors and exit codes

`HelperError` is the single error type; `error::exit_code` maps it to a `sysexits.h` code. The match is **exhaustive** - adding a variant without extending the mapping is a compile error, not a silent default.

| Code | Constant | Meaning |
|---|---|---|
| `0` | - | success |
| `64` | `EX_USAGE` | malformed argv (clap parse failure, unknown subcommand/flag) |
| `65` | `EX_DATAERR` | bad typed data: `ArgvData`, `Validation`, `FingerprintMismatch` |
| `69` | `EX_UNAVAILABLE` | required external tool not on the pinned `PATH` (`Command`/`NotFound`) |
| `70` | `EX_SOFTWARE` | `WireDrift` - debug-build wire-contract drift bug |
| `74` | `EX_IOERR` | `Io` against a known path |
| `75` | `EX_TEMPFAIL` | external command spawn failure / non-zero exit / signal |
| `77` | `EX_NOPERM` | `NotPrivileged` - daemon should retry under elevation |
| `78` | `EX_CONFIG` | `Unsupported` - op not implemented on this OS |

The daemon keys off these codes - for example, `77` tells it elevation is required, while `78` tells it the operation simply isn't available on the current platform.

## Invariants enforced by tests

* **`tests/argv_contract.rs`** - every `HelperInvocation` variant round-trips: `to_argv` → `from_argv` → same op tag → identical re-serialised argv.
* **`tests/no_runtime_deps.rs`** - walks the normal-dependency graph from `cargo metadata --locked --filter-platform <host>` and fails if `tokio`, `reqwest`, `openssl`, `openssl-sys`, or `native-tls` is reachable.
* **Unit tests in `validate.rs`** - relative/missing/non-file paths rejected; basename guard; TLD traversal rejected; PEM fingerprint happy-path, mismatch, multi-cert and zero-cert rejection.
* **Unit tests in `error.rs`** - every `HelperError` variant maps to its expected exit code.
* **In-source debug cross-check** - `cli.rs` fires `WireDrift` if clap and `from_argv` disagree (debug builds only).

## Platform scope and roadmap

Windows is not supported in Phase 1: the `main` stub exits `78`. Real Windows behaviour is planned for Phase 2 alongside `yerd-platform`'s Windows implementations. Also planned: a macOS Authorization Services entitlements wrapper, and broader Linux distro coverage (unknown anchor-dir layouts currently return `Unsupported`). There is intentionally no `tracing` subscriber - `eprintln!` to stderr is enough for a process that lives for milliseconds.

## See also

* [Elevation & Privileges](../../guide/elevation) - the user-facing model
* [yerdd (daemon)](./yerdd) - the unprivileged process that issues invocations
* [yerd (CLI)](./yerd) - drives `yerd elevate` / `yerd unelevate`
* [yerd-platform](../crates/yerd-platform) - owns `HelperInvocation`, the argv contract, and the pure composers
* [Cross-Platform Model](../cross-platform) - how per-OS branches are organised
* [HTTPS & Certificates](../../guide/https) and [DNS & .test Domains](../../guide/dns) - what the privileged ops ultimately enable

---

---
url: 'https://yerd.app/developer/gui.md'
---
# Desktop App Internals

The Yerd desktop app (`apps/yerd-gui`) is a **Tauri v2** application: a Rust
bridge wrapping a system webview that renders a **Vue 3 + TypeScript + Tailwind**
frontend. Its single architectural rule, shared with the CLI, is that it is a
**thin `yerd-ipc` client of the `yerdd` daemon** - it contains no business logic
of its own and **never runs as root**. Everything the app does to your machine
goes through the daemon over a local socket, or through the audited `yerd` CLI
under OS elevation.

For the user-facing tour of the app, see the [Features guide](../guide/desktop-app).
This page is the contributor's reference to the two layers and the contract that
keeps them aligned.

::: info Two layers, one contract
The Rust `src-tauri` layer is a **transport bridge**: one Tauri command per
`yerd-ipc` `Request`. The Vue frontend is a **typed client**: a hand-pinned
TypeScript mirror of the same wire JSON. The whole design exists to keep both
sides agreeing with the Rust IPC contract while never duplicating daemon logic.
:::

## Module map

```
apps/yerd-gui/
├── package.json            yerd-gui (workspace version) - "a thin IPC client of the yerdd daemon"
├── vite.config.ts          Vite + Vitest (one config; vitest/config augments it)
├── tailwind.config.js      Tailwind 3 theme
├── tsconfig.json           "@/*" -> src/*
├── src-tauri/              Rust BRIDGE
│   ├── Cargo.toml          crate yerd-gui (bin yerd-gui), edition 2024, rustc ≥ 1.85
│   ├── tauri.conf.json     windows (main + dumps + mails), CSP, bundle targets
│   ├── capabilities/default.json   permission allowlist
│   └── src/
│       ├── main.rs         Builder, plugins, invoke_handler, tray, window events; show_dumps window helper
│       ├── mail_window.rs  show_mails_window command (show+focus the static `mails` window)
│       ├── commands.rs     one #[tauri::command] per Request; finish() error mapping
│       ├── ipc.rs          exchange() - socket transport, mirrors the CLI's
│       ├── elevate.rs      OS-elevated `yerd <verb> <target>` (pkexec / osascript)
│       ├── daemon.rs       locate / download-install / start / stop yerdd (host-side)
│       ├── autostart.rs    per-user service + autostart plugin + gui-settings.json
│       └── error.rs        GuiError { code, message }
└── src/                    Vue FRONTEND
    ├── main.ts             createApp + router; initTheme(); initDesktopChrome()
    ├── App.vue             AppShell + Toaster; shared daemon poller; first-run daemon start
    ├── router.ts           hash router: /overview (default) /general /php /sites /tooling /services /dumps /mail /doctor /about (+ /dumps-window, /mails-viewer standalone routes)
    ├── ipc/
    │   ├── types.ts        TypeScript mirror of the yerd-ipc wire JSON
    │   ├── client.ts       typed wrappers around invoke() + IpcError
    │   └── client.test.ts  command-mapping + error-categorisation tests
    ├── composables/        useDaemon (singleton poller), usePoll, useToast
    ├── components/         AppShell, SideNav, NavLink, TitleBar, StatusPill, ComingSoon, EnvironmentCard, ManageDomainsModal, ui/ (incl. AsyncState, EmptyState)
    ├── views/              OverviewView, GeneralView, PhpView, SitesView, ToolingView, ServicesView, LaravelDumpsView, DumpsWindowView, MailView, MailsViewerView, DoctorView, AboutView
    └── lib/                utils (cn, humanisers), theme, desktop chrome, domainValidation (client-side domain-shape checks)
```

## The Rust bridge (`src-tauri`)

The bridge is a small, deliberately logic-free crate. Its
[`Cargo.toml`](https://github.com/forjedio/yerd) depends on the same internal
crates the CLI uses - `yerd-core`, `yerd-ipc` (with the `transport` feature),
and `yerd-platform` - because the GUI is "a client of the same contract the CLI
uses." It bans `unwrap`/`expect`/`panic` in its own code via Clippy lints;
`unsafe` is allowed only for one documented `geteuid` FFI call in `elevate.rs`.

### Commands: one per `Request`

`commands.rs` is the heart of the bridge. Each daemon-backed Tauri command maps
`command → Request`, calls [`ipc::exchange`](#the-transport-exchange), and runs
the result through `finish`, which converts a `Response::Error` into a typed
`GuiError` so the frontend only ever sees a success variant or a typed failure:

```rust
/// Convert a daemon `Response::Error` into a `GuiError`; pass success through.
fn finish(resp: Response) -> Result<Response, GuiError> {
    if let Response::Error { code, message } = &resp {
        return Err(GuiError::daemon(code_str(code), message.clone()));
    }
    Ok(resp)
}
```

The error code is rendered to its snake\_case wire string **via serde**, not a
hand-written match - so a new `ErrorCode` variant needs no change here:

```rust
fn code_str(code: &ErrorCode) -> String {
    serde_json::to_value(code)
        .ok()
        .and_then(|v| v.as_str().map(str::to_owned))
        .unwrap_or_else(|| "internal".to_owned())
}
```

A representative command shows the pattern - no logic, just `Request`
construction and `finish`:

```rust
#[tauri::command]
pub async fn link(name: String, path: String) -> Result<Response, GuiError> {
    finish(exchange(&Request::Link { name, path: PathBuf::from(path) }).await?)
}
```

The main command groups registered via `main.rs`'s `tauri::generate_handler!` (the full list - ~50 commands spanning sites, PHP, services, databases, dumps, mail, tools, site-creation jobs, and the host-only daemon/autostart/CLI-on-PATH commands - lives in `main.rs`):

| Command | `Request` | Notes |
| --- | --- | --- |
| `ping` | `Ping` | liveness |
| `list_sites` | `ListSites` | |
| `park` | `Park { path }` | path wrapped as `PathBuf` |
| `link` | `Link { name, path }` | |
| `unlink` | `Unlink { name }` | |
| `list_parked` | `ListParked` | |
| `unpark` | `Unpark { path }` | path sent **verbatim as `String`** (matched exactly, not canonicalised, so a deleted folder is still removable) |
| `set_php` | `SetPhp { name, version }` | |
| `set_secure` | `SetSecure { name, secure }` | |
| `set_web_root` | `SetWebRoot { name, path }` | `path: Option<String>`; `null` = reset to auto-detect |
| `list_php` | `ListPhp` | |
| `check_php_updates` | `CheckPhpUpdates` | |
| `available_php` | `AvailablePhp` | |
| `install_php` | `InstallPhp { version }` | |
| `set_default_php` | `SetDefaultPhp { version }` | |
| `update_php` | `UpdatePhp { version }` | `version: Option<PhpVersion>`; `None` = update all |
| `set_php_settings` | `SetPhpSettings { settings }` | `BTreeMap<String, String>` |
| `restart_php` | `RestartPhp { version }` | |
| `restart_all_php` | `RestartAllPhp` | |
| `uninstall_php` | `UninstallPhp { version }` | |
| `restart_daemon` | `RestartDaemon` | |
| `status` | `Status` | |
| `diagnose` | `Diagnose` | |
| `doctor_fix` | `DoctorFix` | |
| `daemon_info` | `DaemonInfo` | |

Three commands are **host-only helpers** with no daemon IPC:

| Command | Returns | Purpose |
| --- | --- | --- |
| `protocol_version` | `u32` (`yerd_ipc::PROTOCOL_VERSION`) | the negotiated IPC protocol version, for the About view |
| `host_platform` | `&'static str` (`std::env::consts::OS`) | `"linux"` / `"macos"` / `"windows"` to gate platform UI |
| `elevate` / `unelevate` | `()` | run `yerd elevate <target>` / `yerd unelevate <target>` under OS elevation (see below) |

The Settings page (route `/general`) adds further host-only commands (no daemon IPC) for daemon lifecycle and autostart - `daemon_installed`, `start_daemon`, `stop_daemon`, `cli_path_status`, `install_cli_to_path`, `remove_cli_from_path`, `open_login_items`, `get_autostart`, `set_autostart_daemon`, `set_autostart_gui`, `set_gui_minimized`, `daemon_self_repair_busy` - implemented in `daemon.rs` (resolve the bundled binaries, start/stop, install the `yerd` CLI on PATH) and `autostart.rs` (per-user service + run-at-login; macOS uses `smappservice.rs`). The daemon is **bundled** in the app, so there's no download/install command.

On macOS, `autostart.rs` also self-repairs the daemon's SMAppService registration
on every launch (`ensure_daemon_registration`, run from a background thread in
`setup_app`). It folds the GUI/daemon version
comparison (`decide`) and a phantom-job check into a `RegAction`: `Refuse` when
the registered daemon is newer than this GUI (a downgrade guard - the running
daemon is left alone and the version conflict is surfaced on the Overview
banner); `NoOp` when the registration already matches this GUI and the launchd
job is healthy; `Reregister` (unregister, `register_repairing`, kickstart)
either when the version needs to reconcile, or when the version is already
up to date but SMAppService reports the registration `.enabled` while
`launchctl print` shows no job for it - a **phantom registration** (a BTM
hiccup, a crash, or a manual `bootout`) that a plain kickstart can't recover
from since there's no job to kick. Every branch logs to
`{cache}/yerd-gui-repair.log`, which `daemon_diagnostics`/"Copy diagnostics"
surfaces - the first place to check when a daemon doesn't come back after an
update.

Because this thread runs unconditionally on every launch - including when
onboarding is still showing (a prior "Install" click can leave a registration
behind even if the journey wasn't finished) - it can be doing real,
multi-second work (or opening Login Items) with no user click involved. The
thread brackets its call to `ensure_daemon_registration` with a
`DAEMON_SELF_REPAIR_BUSY` atomic flag and a `daemon-self-repair` Tauri event
(`true` before, `false` after), which `useDaemonStart.ts`'s `backgroundBusy`
signal (below) ORs into the Install/Start button's busy state, so the button
never sits idle while this is happening. `DAEMON_REG_LOCK` is what actually
serializes registration/kickstart calls against a concurrent manual start; the
flag/event are purely a UX signal layered on top, not a correctness mechanism.

::: tip No `Request` is ever built in the frontend
The `Request` enum is intentionally **not** mirrored into TypeScript. The
frontend never constructs raw requests; it invokes named commands and the
bridge builds the `Request`. Only `Response` (and the domain types it carries)
crosses to the webview.
:::

### The transport: `exchange`

`ipc.rs` is "a near-verbatim mirror of `bin/yerd/src/transport.rs`." It resolves
the socket path identically to the daemon and CLI - `<runtime>/yerd.sock`, where
`<runtime>` comes from `yerd_platform`'s `ActivePaths::resolve` - so client and
server always agree on the location:

```rust
#[cfg(unix)]
pub async fn exchange(req: &Request) -> Result<Response, GuiError> {
    use yerd_platform::{ActivePaths, Paths};
    let dirs = ActivePaths::new()
        .resolve()
        .map_err(|e| GuiError::unreachable(format!("cannot resolve runtime dir: {e}")))?;
    exchange_at(&dirs.runtime.join("yerd.sock"), req).await
}
```

`exchange_at` connects with `interprocess` local sockets, writes a single framed
request with `yerd_ipc::write_message` (bounded by `DEFAULT_MAX_FRAME`), and
reads one framed `Response` back with a `FrameDecoder`. It is factored out so
tests can target a tempdir socket. Failure handling distinguishes categories:

* a connect/resolve failure becomes `GuiError::unreachable(..)` - this is what
  flips the frontend's "Daemon not running" state;
* a read/write failure becomes `GuiError::internal(..)`;
* the daemon closing the connection without replying becomes an `unreachable`
  error.

On non-Unix targets `exchange` is a stub returning an `unreachable` error,
because the Windows named-pipe name is not client-derivable yet - the GUI is
macOS/Linux-only for the same reason the CLI transport is. See the
[IPC Protocol](./ipc-protocol) and [Cross-Platform Model](./cross-platform) pages.

### `GuiError` and the wire shape

`error.rs` defines the one error type every command returns. It carries only a
machine-readable `code` and a human `message`, and serialises **manually** so
the wire shape is exactly `{ code, message }`:

```rust
pub struct GuiError {
    /// daemon `ErrorCode` (snake_case), `"unreachable"`, or `"internal"`.
    pub code: String,
    pub message: String,
}
```

The three constructors - `unreachable`, `internal`, `daemon(code, message)` -
are the only categories the frontend's `IpcError` needs to distinguish.

### App lifecycle, plugins, and the tray (`main.rs`)

`main.rs` wires the Tauri `Builder`:

* **`tauri-plugin-single-instance` is registered first**: a second launch shows
  and focuses the existing `main` window instead of spawning a duplicate (which
  would risk a duplicate daemon connection or tray).
* **Launch-time update check** (`tray::spawn_launch_update_check`): fired from
  both `setup_app` and the single-instance callback, so it runs on a cold start
  and on every re-invoke of an already-running app. It asks the daemon for the
  cached self-update status and, only if `yerd_update::is_check_due` says the
  last check is stale (the same 4h threshold the daemon's own background poll
  uses), kicks a bounded live check. Silent and non-blocking - an unreachable
  daemon or fetch failure is swallowed exactly like the daemon's own
  failure-tolerant polling.
* `tauri-plugin-opener` and `tauri-plugin-dialog` back the host helpers
  (`openInBrowser`, `openPath`, `pickDirectory`).
* **Close-to-tray**: `WindowEvent::CloseRequested` hides the window and calls
  `api.prevent_close()`. The tray's **Quit** item is the real exit; **Open Yerd**
  reshows the window. (On Linux AppIndicator, clicks aren't delivered, so the
  menu item is the only way in.)
* **Dynamic tray menu** (`tray.rs`): the menu is rebuilt from live daemon state,
  not static. A Rust-side poll over the same `yerd-ipc` socket the commands use
  (the frontend poller pauses when the window is hidden to tray) diffs a snapshot
  and `set_menu`s a fresh menu only on change - showing daemon status + ports,
  Start/Restart/Stop, an inline default-PHP switcher, update items, the Mail/Dumps
  viewers, site actions, and nav shortcuts. A `TRANSITION`/`MENU_LOCK` guard keeps
  a tray-initiated lifecycle action's transient menu from being stomped by a
  late poll tick. The same poll composites status badges onto the tray icon: a red
  dot for a waiting update and an orange dot for unread mail (`draw_dot`). Menu
  item icons are recoloured per-build for the desktop's dark/light state
  (`menu_icon`/`dark_menu_bar`), since `muda`'s menu icons aren't templates and
  won't auto-tint themselves: on macOS this reads the `AppleInterfaceStyle` user
  default (unchanged); on Linux it probes the xdg-desktop-portal `Settings`
  `color-scheme` preference via the `dark-light` crate, a bounded D-Bus round
  trip taken by the caller *before* `MENU_LOCK` is acquired (see the module doc
  comment) so it never runs lock-held. Any read failure (no portal, older
  desktop) falls back to light, i.e. today's black glyphs.
* On **Linux**, before GTK initialises, `glib::set_prgname("yerd-gui")` pins the
  Wayland `app_id` so the dock matches `yerd-gui.desktop`, and a `with_webview`
  block clamps WebKitGTK's zoom level (the only place that can intercept
  Ctrl+wheel / pinch zoom, which WebKit handles below the DOM).

The window itself (`tauri.conf.json`) is **decorationless and transparent**
(`"decorations": false`, `"transparent": true`, `macOSPrivateApi: true`), which
is why the frontend ships a custom `TitleBar.vue`. Its control layout isn't
hardcoded to the host OS - it's a user preference. `lib/titleBarStyle.ts` holds
a `TitleBarStyle` (`"auto" | "macos" | "linux" | "linux-reversed" | "windows"`),
persisted host-side in `gui-settings.json` via the `get_title_bar_style` /
`set_title_bar_style` commands (mirroring the tray icon variant setting) and
broadcast to every open window so the main, mails, and dumps windows switch in
lockstep. `"auto"` (the default) resolves from `host_platform`; any other value
forces that layout regardless of the actual host, driving which controls
`TitleBar.vue` renders on which side (macOS traffic lights; Linux close-left,
minimize/maximize-right; Linux Reversed the mirror of that; Windows
minimize/maximize/close all on the right). The CSP is locked down to
`default-src 'self'` (plus inline styles and `data:` images). Bundle targets are
`deb` and `app` - the macOS `.dmg` is **not** a Tauri bundle target; it's built
as a separate headless step (`apps/yerd-gui/scripts/build-macos-dmg.sh`, via
`appdmg`) after the `.app` is signed, since Tauri's own dmg bundler drives
Finder via AppleScript to style the background/icon layout, which isn't
reliable outside an interactive session. See
[Packaging and releasing](./building#packaging-and-releasing). For `.deb`, the
privileged-port capability is **not**
baked into the artifact: the `postinst` script grants
`cap_net_bind_service=+ep` on the installed `yerdd` at configure time (and
re-applies it on every upgrade, since dpkg wipes file capabilities) - falling
back to ports 8080/8443 if `setcap` is missing or the filesystem can't hold
caps. There's no AppImage target because its ephemeral mount can't host a
`postinst` step, so the daemon's `setcap` can't be persisted that way. The native
Arch package (`.pkg.tar.zst`) is **not** a Tauri bundle target (Tauri has no
pacman bundler) - it's built separately from
[`packaging/arch/PKGBUILD`](https://github.com/forjedio/yerd/blob/main/packaging/arch)
in the release workflow's `arch` job, with a `.install` scriptlet doing the same
`setcap`. The Fedora `.rpm`, by contrast, **is** a Tauri bundle target (Tauri v2
has an rpm bundler): the `fedora` jobs run `tauri build` with the
`tauri.bundle-linux-rpm.conf.json` overlay and an `rpm/postinst.sh` `%post` doing
the same `setcap`. See [Packaging and releasing](./building#the-fedora-package-rpm).

::: info Three windows, one bundle
The app is no longer single-window. `tauri.conf.json` declares **three** windows,
all loading the same SPA bundle at different hash routes and all hidden until
shown:

* **`main`** - the app shell (`index.html`, default route).
* **`mails`** - the standalone Mails viewer (`#/mails-viewer`), declared
  statically.
* **`dumps`** - the live Laravel Dumps viewer (`#/dumps-window`). It is also
  declared statically, but `main.rs`'s `show_dumps` helper *lazily (re)creates* it
  if it has been destroyed, so the "Show Dumps" path is robust either way.

The auxiliary windows are **shown, not spawned**: `mail_window::show_mails_window`
and `show_dumps_window` just `get_webview_window(label)` then `show()` + focus.
When a window isn't already open, the shared `reveal_aux_window` helper first
centres it on the monitor under the cursor (the active screen), so it appears
where the user is looking rather than on whatever display it last lived on.
The `CloseRequested` handler is **global** (fires for every window) and hides
rather than closes each one, so the windows persist across opens. Crucially it
gates the close-to-tray + Dock-accessory behaviour on `window.label() == "main"`:
closing an auxiliary window must not yank the main app's Dock presence or
minimise the whole app to the tray. On the frontend side, `App.vue` detects the
auxiliary windows (`getCurrentWindow().label === "dumps"`, or a route with
`meta.standalone`) and renders the bare viewer with **no SideNav/TitleBar shell
and no daemon poller**, so an auxiliary window never runs a second `status` loop.
The dynamic tray menu opens both auxiliary windows directly (its **Mail** and
**Dumps** items call the same reveal helpers).
:::

### Capabilities

`capabilities/default.json` is the permission allowlist. Our own
`#[tauri::command]`s are permitted by registration; the file additionally grants
`core:default`, the `opener:default` / `dialog:default` plugin commands, and the
specific `core:window:*` commands the custom titlebar drives
(`start-dragging`, `minimize`, `maximize`/`unmaximize`/`toggle-maximize`,
`is-maximized`, `close`).

## In-app elevation

`elevate.rs` is the only privileged path, and it is careful. The GUI process
never becomes root; instead it **elevates the audited `yerd` CLI** to run one of
a fixed allowlist of verbs against a fixed allowlist of targets:

```rust
const TARGETS: [&str; 3] = ["trust", "resolver", "ports"];
const VERBS: [&str; 2] = ["elevate", "unelevate"];
```

`run(verb, target)` rejects anything not in those allowlists (both are
interpolated into the macOS AppleScript, so both must be validated), resolves the
trusted CLI, and spawns the blocking, prompt-driven process off the async runtime
via `spawn_blocking`. The `elevate` command passes `"elevate"`; `unelevate` (the
Services-tab "Unelevate" buttons) passes `"unelevate"`. The
invariants (grounded in `bin/yerd/src/elevate.rs`) are:

1. **Elevate the CLI, not the GUI.**
2. **Resolve `yerd` as a sibling of our own `current_exe`**, never from `PATH`
   or the daemon - an anti-forgery measure matching the CLI. If no `yerd` sits
   beside the app binary, the command fails with an explanatory error.
3. **Thread the real uid through `env SUDO_UID=<uid>`** because the elevation
   tool clears the environment, and `yerd elevate` relies on `SUDO_UID` to
   locate the user's socket and owner-check the CA.

Per platform:

```sh
# Linux (<verb> is elevate or unelevate)
pkexec /usr/bin/env SUDO_UID=<uid> <yerd> <verb> <target>

# macOS - built on osascript's stdin, with `quoted form of` for shell safety
osascript:  do shell script "env SUDO_UID=<uid> " & quoted form of "<yerd>" \
            & " <verb> <target>" with administrator privileges
```

The macOS branch reads `SUDO_UID` from `libc::geteuid()` and embeds it because
`osascript … with administrator privileges` runs as root with a clean env and
does **not** set `SUDO_UID` (that is a `sudo`-ism). Cancellation is detected from
exit codes (`pkexec` 126/127) or stderr text (`User canceled` / `-128`), since on
macOS the exit code alone can't separate "dismissed" from "elevate failed". On
unsupported platforms the helper returns an error telling the user to run
`yerd elevate` in a terminal. See [Elevation & Privileges](../guide/elevation).

## The Vue frontend (`src`)

### The typed IPC client

`ipc/types.ts` is "a *contract*, pinned by hand to the Rust source." It mirrors
the `yerd-ipc` wire JSON and documents each type's origin so review catches
drift; the file's header names `crates/yerd-ipc/src/{request,response,status}.rs`
and `crates/yerd-core/src/site.rs` as the source of truth, with
`yerd-ipc`'s `tests/wire_stability.rs` guarding the Rust side. Wire conventions:
enums are internally tagged on `type`, `snake_case`; `PhpVersion` is the bare
string `"8.5"`; `Option<T>` is `T | null`. It mirrors the additive `SiteEntry`
domain fields (`primary_domain?`, `domains?`, `apex_shadowed_by?`) and the
`DomainShadow` type carried in `StatusReport.shadows`.

`Response` is the central discriminated union:

```ts
export type Response =
  | { type: "pong" }
  | { type: "sites"; sites: Site[] }
  | { type: "ok" }
  | { type: "error"; code: ErrorCode; message: string }
  | { type: "parked"; paths: string[] }
  | { type: "info"; dns_addr: string; tld: string; ca_path: string; ca_fingerprint: string }
  | { type: "php_versions"; installed: PhpVersion[]; default: PhpVersion;
      updates?: PhpUpdate[]; settings?: Record<string, string> }
  | { type: "available_php"; available: PhpVersion[]; installed: PhpVersion[] }
  | { type: "status"; report: StatusReport }
  | { type: "diagnoses"; items: Diagnosis[] }
  | { type: "doctor_fix"; report: FixReport };
```

`ipc/client.ts` wraps each Tauri command in a typed function and narrows the
`Response` for callers - including the domain mutators
`addDomain` / `removeDomain` / `setPrimaryDomain` / `resetDomains` that back
`ManageDomainsModal.vue`. A low-level `call` normalises every rejection into an
`IpcError`, and `ensureOk` defensively throws if a `type:"error"` ever slips
through:

```ts
async function call<T>(cmd: string, args?: Record<string, unknown>): Promise<T> {
  try { return await tauriInvoke<T>(cmd, args); }
  catch (e) { throw toIpcError(e); }
}
```

`IpcError` categorises failures so the UI can react. Its `unreachable` flag is
set when the code is `"unreachable"` **or** the message matches a
daemon-down pattern - that flag is what drives the global "Daemon not running"
card:

```ts
this.unreachable =
  code === "unreachable" || /daemon (is )?unreachable|not running/i.test(message);
```

The client also exposes host helpers that are **Tauri plugins, not daemon IPC**:
`openInBrowser` / `openPath` (opener plugin), `pickDirectory` (dialog plugin),
and `elevate` (the `elevate` command above), typed to the
`ElevateTarget = "trust" | "resolver" | "ports"` union.

### Composables

| Composable | Role |
| --- | --- |
| `useDaemon` | **Singleton** daemon store. One poller for the whole app (connection pill, views) so the daemon isn't hit by N independent `status` loops. `status` doubles as the liveness probe; only a genuine **unreachable** error flips `connected` to `false` - a typed daemon error still means the daemon is up. Started/stopped from `App.vue`. |
| `useDaemonStart` | **Singleton** "start the daemon, wait for it to connect, diagnose on failure" flow shared by onboarding step 1, `DaemonDownHero`, and Doctor. `phase` (click-driven, fed by the Rust `daemon-start-phase` event) and `backgroundBusy` (fed by macOS's launch-time self-repair thread's `daemon-self-repair` event, see above) both OR into `starting`/`activeLabel` so every consumer's button reflects either kind of in-flight work - but `start()`'s own re-entrancy guard reads `phase` alone, so a same-tick self-repair no-op can never suppress `App.vue`'s automatic start. |
| `usePoll` | Generic mount-scoped poller. Never overlaps in-flight calls, **pauses while the document is hidden** (background tab / tray), refreshes on becoming visible, and clears its timer on unmount. Default cadence 4s; callers should not go below ~3s for `status`. |
| `useToast` | Module-level toast store rendered by the single `<Toaster>` in `App.vue`. Errors linger (8s), success/info auto-dismiss (4s). |

Both pollers gate on `document.visibilityState === "hidden"` to avoid hammering
the daemon when the window is hidden to the tray - a real cost, since each
`status` reads the trust store and live FPM state.

### Views, components, and `lib`

The hash router (`createWebHashHistory`, because the webview loads from a
file/asset origin) maps the in-shell routes - **OverviewView** (`/overview`, the
default landing dashboard), **GeneralView** (`/general`, the **Settings** page),
**PhpView**, **SitesView**, **ToolingView** (`/tooling`), **ServicesView**,
**LaravelDumpsView** (`/dumps`), **MailView** (`/mail`), **DoctorView** (which
also hosts the OS-privileges **EnvironmentCard** - CA trust / resolver / ports),
**AboutView** - plus two **standalone** routes that the auxiliary windows load:

* **DumpsWindowView** (`/dumps-window`) - the live Laravel Dumps viewer that
  fills the separate `dumps` window: tabbed by `DumpCategory`, incrementally
  paging the daemon's ring via `listDumps({ since_id })`, with search, persist
  and always-on-top toggles, and an "open in editor" jump. `LaravelDumpsView`
  (the in-shell `/dumps` page) is the *settings* surface - it drives
  `dumpsStatus` / `setDumpsEnabled` / `setDumpsPort` / `setDumpFeature` and shows
  per-PHP-version extension presence, with a "Show Dumps" button that opens the
  standalone window via `showDumpsWindow`.
* **MailsViewerView** (`/mails-viewer`, `meta.standalone`) - the captured-mail
  inbox that fills the separate `mails` window: lists `listMails`, loads a
  selected message with `getMail`, renders the HTML body in a **sandboxed iframe**
  (strict child CSP, no scripts, no same-origin), groups by sending application,
  and supports clear/delete. `MailView` (the in-shell `/mail` page) is the
  settings surface - it reads mail status off the shared `status` poll, drives
  `setMailEnabled` / `setMailPort`, and opens the viewer window via
  `showMailsWindow`.

Components are split into app components (`AppShell`, `SideNav`, `TitleBar`,
`StatusPill`, `PageHeader`, `ComingSoon`) and hand-rolled
**shadcn-vue-style `ui/` primitives** (`Button`, `Card`, `Input`, `Select`,
`Switch`, `Modal`, `Spinner`, `Toaster`, `Badge`, plus `dropdown-menu/`,
`tabs/` and `tooltip/` built on `reka-ui`). `lib/utils.ts` holds the shadcn `cn` helper and
the display humanisers - note `poolStateLabel`/`poolStateTone`, which render an
installed-but-not-serving FPM pool as **"idle"** (neutral) rather than the
alarming wire value `stopped`, reserving red **"failed"** for an actual crash.

### "Coming soon" affordances

`ComingSoon.vue` renders a deliberately non-interactive `<span>`
(`aria-disabled="true"`, a native `title` tooltip, no clickable element) so a
gated control reads as intentional rather than broken. It has a **single** use
today: on a platform without in-app elevation - i.e. a future Windows build,
since the GUI ships only on macOS/Linux - the Doctor page's **Environment**
*Fix* action falls back to a "soon" pill pointing at `yerd elevate`. On the
supported platforms every control is fully wired (the earlier Logs / restart
stubs are gone now that their IPC exists).

::: warning The GUI is a client of the daemon's state
When the socket is unreachable, `AppShell.vue` replaces the route view with a
"Daemon not running" panel offering **Start** (which launches `yerdd` through
the per-user service via the `start_daemon` host command) and **Retry**; the
Overview, Settings, and About routes stay reachable while down (`DAEMON_FREE`).
The app can drive the daemon's *lifecycle* but never reimplements its runtime
logic - the daemon stays the single source of truth - and it expects the `yerd`
CLI installed **beside** it for the elevation path.
:::

## Testing and the type-check gate

The frontend is tested with **Vitest** (jsdom environment, configured in the
single `vite.config.ts` via `vitest/config`):

* `ipc/client.test.ts` mocks `@tauri-apps/api/core`'s `invoke` and asserts the
  **command-mapping contract** (e.g. `listSites` unwraps the array,
  `updatePhp(null)` sends `{ version: null }`), that a daemon `Response::Error`
  becomes an `IpcError` carrying its `code`, and the `IpcError` unreachable
  categorisation.
* `components/components.test.ts` mounts components with `@vue/test-utils`
  (e.g. `ComingSoon` is non-interactive; `StatusPill` tri-state tones).
* `lib/utils.test.ts` covers the humanisers.

```sh
npm run test       # vitest run
npm run build      # vue-tsc --noEmit && vite build  - type-check is part of build
npm run typecheck  # vue-tsc --noEmit standalone
```

`npm run build` runs **`vue-tsc --noEmit`** before `vite build`, so a frontend
type error - including drift between `ipc/types.ts` and how the views consume
`Response` - **fails the build**. The Rust bridge has its own unit tests
(`finish` passes success through, maps a daemon error to the right code,
`code_str` renders snake\_case for known variants):

```sh
cargo test -p yerd-gui    # needs the Linux -dev packages listed in the README
```

Together, the Vitest command-mapping tests, the `vue-tsc` gate, the bridge unit
tests, and `yerd-ipc`'s own `wire_stability` tests are what keep the
TypeScript contract pinned to the Rust contract on both sides.

---

---
url: 'https://yerd.app/developer/xtask.md'
---
# Build Automation (xtask)

Yerd's repository-local build automation lives in the [`xtask`](https://github.com/forjedio/yerd/tree/main/xtask) crate. It follows the well-known [cargo-xtask](https://github.com/matklad/cargo-xtask) pattern: instead of shell scripts or a Makefile, build tasks are ordinary Rust programs run through a cargo alias. There is no extra tool to install - if you can build the workspace, you can run every task.

```sh
cargo xtask <command>
```

The alias is declared in the repository's `.cargo/config.toml`:

```toml
[alias]
# Run build-automation tasks: `cargo xtask <cmd>` (e.g. `cargo xtask bump`).
xtask = "run --package xtask --"
```

So `cargo xtask bump` expands to `cargo run --package xtask -- bump`. The crate is a normal workspace member (listed in the root `Cargo.toml` `members` array) and inherits the workspace version, edition, MSRV, license, and lint configuration. Its only dependencies are `clap` (argument parsing) and `anyhow` (error handling). That small surface is deliberate.

## What it does today

`xtask` exposes exactly two subcommands. They are declared as a `clap` enum in `xtask/src/main.rs`:

| Command | Purpose |
|---|---|
| `cargo xtask bump <version>` | Set the project version across all three manifests. |
| `cargo xtask version-check <version>` | Assert a tag/version matches all three manifests (release gate). |

```rust
/// `xtask` subcommands.
#[derive(clap::Subcommand, Debug)]
pub enum Command {
    /// Set the project version across Cargo.toml, tauri.conf.json, package.json.
    Bump {
        /// The new version, e.g. `2.0.2` or `2.0.2-rc.1` (a leading `v` is fine).
        version: String,
    },
    /// Assert the given tag/version matches all three manifests (release gate).
    VersionCheck {
        /// The tag/version to check, e.g. `v2.0.2` (a leading `v` is stripped).
        version: String,
    },
}
```

::: info Scope
`xtask` only keeps **versions in sync**. It does *not* build any artifacts - the shipped products are the **GUI bundle** (`.dmg` on macOS, `.deb` on Linux) with the three binaries (`yerd`/`yerdd`/`yerd-helper`) embedded via `externalBin` (per-platform overlays in `apps/yerd-gui/src-tauri/`), plus a native **Arch package** (`.pkg.tar.zst`, x86-64) built from `packaging/arch/PKGBUILD` in the workflow's `arch` job. Tauri builds the `.app` (macOS) and `.deb` (Linux) directly; the macOS `.dmg` is packaged as a separate headless step (`apps/yerd-gui/scripts/build-macos-dmg.sh`, via `appdmg`) since Tauri's own dmg bundler drives Finder via AppleScript, which isn't reliable outside an interactive session. There is no standalone CLI tarball/`.deb`. `xtask` also doesn't download or cache PHP - PHP builds are fetched at runtime by the daemon (see [yerd-php](./crates/yerd-php)). Cross-platform release artifacts and checksums are assembled by the GitHub Actions workflows.
:::

## Module map

The crate is split into a **pure helper** (deterministic, I/O-free, unit-tested) and **thin orchestration** (the glue that reads/writes files and prints).

```
xtask/
├── Cargo.toml
└── src/
    ├── main.rs      orchestration: CLI parse + bump/version-check I/O glue
    └── version.rs   PURE: in-place version edits/reads + sync assertion
```

This mirrors the project-wide convention: **pure logic in functions you can test in-memory; I/O pushed to the edges.** `version.rs` carries the logic with no `std::fs` calls; `main.rs` does the reading and writing.

## Version sync - `bump` and `version-check`

Yerd declares its version in **three** manifests that must never drift:

| Manifest | Key |
|---|---|
| `Cargo.toml` (workspace root) | `[workspace.package].version` |
| `apps/yerd-gui/src-tauri/tauri.conf.json` | top-level `"version"` |
| `apps/yerd-gui/package.json` | top-level `"version"` |

`main.rs` locates all three relative to the crate's manifest directory (the workspace root is `xtask`'s parent), and `version.rs` provides the pure string transforms.

### `cargo xtask bump <version>`

```sh
cargo xtask bump 2.0.2        # or 2.0.2-rc.1, or v2.0.2 (the leading v is fine)
```

This sets the version in all three files and prints a reminder to commit and tag. The leading `v` is stripped by `version::normalise`. The edit is **surgical**: it rewrites only the single version line in each file, preserving indentation, the key, any trailing comma, and the original trailing-newline behaviour - it never reformats the whole document. The same `replace_last_string` helper works for both TOML (`version = "X"`) and JSON (`"version": "X",`) because in both cases the value is the *last* double-quoted string on the line.

```rust
/// Set `[workspace.package].version` in a `Cargo.toml`.
pub fn set_cargo(content: &str, version: &str) -> Result<String>;
/// Set the top-level `"version"` in a JSON manifest (tauri.conf.json / package.json).
pub fn set_json(content: &str, version: &str) -> Result<String>;
```

The Cargo helper specifically scans for the `version` key **inside the `[workspace.package]` table**, so a `version = "1"` in `[workspace.dependencies]` is never touched - a behaviour pinned by a unit test.

### `cargo xtask version-check <version>`

This is the **release gate**. It reads the version out of all three manifests and asserts they all equal the (normalised) expected version:

```rust
/// Assert all three found versions equal `expected`. Returns a human-readable
/// error listing every mismatch when they don't.
pub fn assert_all_match(expected: &str, found: &[Found]) -> Result<()>;
```

On success it prints `OK: all manifests are at <version>`. On mismatch it lists *every* offending manifest (omitting the ones that match) and tells you to run `cargo xtask bump <expected>`, commit, and re-tag.

## Release workflow

The version commands exist to make tagged releases safe, but cutting a release
is a single command: [`scripts/release.sh`](https://github.com/forjedio/yerd/blob/main/scripts/release.sh).

```sh
./scripts/release.sh --version v2.0.3           # final release
./scripts/release.sh --version 2.0.2-rc.5       # prerelease (leading v optional)
./scripts/release.sh --version v2.0.3 --dry-run # print the plan, change nothing
./scripts/release.sh --version v2.0.3 --tag-only # push the tag only, not the branch
```

It normalises the version (strips a leading `v`) and validates it against
`MAJOR.MINOR.PATCH[-prerelease]` - the exact shape the release workflow's tag
filter accepts (`v2.0.2.rc-5` is rejected; use `v2.0.2-rc.5`). Before touching
anything it checks the tree is clean (`git diff` / `git diff --cached`), that
you're on a real branch (not detached `HEAD`), and that the tag doesn't already
exist locally or on the remote. It then:

1. Runs `cargo xtask bump <version>` to set `Cargo.toml`, `tauri.conf.json`,
   and `package.json`.
2. Runs `cargo update --workspace` to refresh `Cargo.lock` to match (a failure
   here, e.g. offline, is a warning, not fatal).
3. Runs `cargo xtask version-check <tag>` - the same gate CI runs - to confirm
   every manifest actually landed on the new version.
4. Commits the bump as `Release: vX.Y.Z`, tags it (`git tag -a`), and pushes -
   the branch and the tag by default, or just the tag with `--tag-only`.

The release CI builds the single GUI bundle for macOS (`arm64`) and Linux (`amd64` and `arm64`) - each embedding the three binaries - and a mismatched tag fails fast via `cargo xtask version-check`. Because `version-check` strips the leading `v`, it accepts both the tag form (`v2.0.2`) and the bare version (`2.0.2`). See [Building from Source](./building) and [Contributing](./contributing) for the full developer gate.

## Conventions and invariants

* **Pure / orchestration split.** Version parsing/editing and the sync assertion live in `version.rs` and are unit-tested in-memory; `main.rs` only does I/O. This matches the [architecture](./architecture) principle used across the codebase.
* **No `unsafe`.** `main.rs` declares `#![forbid(unsafe_code)]`.
* **`anyhow` at the top level.** As a binary, `xtask` uses `anyhow::Result` with `.with_context(...)` for actionable messages, rather than the `thiserror` enums libraries use.

## Source

* Crate root: [`xtask/`](https://github.com/forjedio/yerd/tree/main/xtask)
* Orchestration: [`xtask/src/main.rs`](https://github.com/forjedio/yerd/blob/main/xtask/src/main.rs)
* Pure helper: [`xtask/src/version.rs`](https://github.com/forjedio/yerd/blob/main/xtask/src/version.rs)