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 (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.comURL. 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.
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 unless you set a share password. 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.
yerd tunnel installOnce installed, cloudflared is also available as a command in {data}/bin, so it is on your PATH after yerd path install.
In the desktop app, the Share page offers an Install cloudflared button the first time you visit. Its Setup dialog shows which cloudflared is in use: if Yerd found one on your PATH, it reads Found on PATH and a Use Yerd's copy button switches to the managed, auto-updating copy; when a newer release of Yerd's copy is out, an Update button installs it.
Quick share
The fastest way to put a site online:
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 offlineshare waits until Cloudflare's edge reports the tunnel online and then prints the URL. If it can't come online (for example, no network), the share is stopped and the command fails with the reason, so a share reported as failed never goes live later.
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 are never resumed when the daemon restarts.
- Once online, a quick tunnel whose
cloudflaredcrashes is restarted automatically, but Cloudflare hands out a new URL on every restart. Checkyerd tunnel status(or the Share page) for the current one. - They carry Cloudflare's quick-tunnel limits (around 200 concurrent requests, and no server-sent events), so they're for development, not production traffic.
"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
yerd tunnel loginThis 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
yerd tunnel create my-tunnelYerd supports one named tunnel at a time; remove it before creating another.
3. Expose a site
Create the DNS record for a public hostname on your authorized domain, then map a site to it:
yerd tunnel route my-tunnel app.example.com # create the proxied DNS record
yerd tunnel set-host app app.example.com # record the mapping, go live
yerd tunnel list # show the tunnel, exposed sites, and domainSetting a hostname is all it takes: the daemon starts the named tunnel if it isn't already running. Adding or removing a site never restarts the tunnel, so sites that are already exposed stay up while you change the others.
To stop exposing a site:
yerd tunnel set-host app --clear # remove the mappingClearing the last hostname stops the named tunnel.
Staying online
The daemon supervises the named tunnel for as long as at least one site has a hostname:
- Auto-restart. If
cloudflaredexits or loses its connection to Cloudflare, it is restarted with a backoff of at most 30 seconds, and it keeps retrying for as long as it takes (hours of downtime included). There is no give-up state. - Resume on start. When the daemon starts, it brings the named tunnel back up if any site has a hostname (and you are logged in with a tunnel created). Any stray
cloudflaredleft behind by a daemon that crashed is stopped first, so an old connector can't keep serving stale config. - Stopping.
yerd tunnel unpublishstops the tunnel until the next hostname change or daemon start. To keep the named tunnel offline across restarts, clear its hostnames (set-host <site> --clear).yerd tunnel publishstarts it again (it never restarts a live tunnel).
Tunnel states
yerd tunnel status and the Share page report real edge health, not just whether a process exists:
| State | Meaning |
|---|---|
connecting | cloudflared is starting and has not reached Cloudflare's edge yet. |
online | Connected to the edge and serving requests. |
reconnecting | It was online, but the edge connection dropped; cloudflared is recovering. |
failed | The process exited or never connected. Shown as failed, retrying because it is restarted after the backoff. A quick share that fails to come up at all is removed and reported as an error instead. |
When something went wrong, the most recent error from cloudflared is shown under the tunnel (as an error: line in the CLI).
In the desktop app
The desktop app has a Share page in the sidebar (also reachable from the command palette). When any site is shared, the sidebar item shows a count.
The page lists your shares in two groups: Quick links and Your domain (named after your Cloudflare zone). Each row shows the site, a status dot and its public address. On a narrower window the list becomes a table (site, type, public URL and status) and a share's details open in a drawer.
Selecting a share shows its details: the Public URL with Copy and Open, a Type / Local site / Status strip with the tunnel's state (Connecting, Running, Reconnecting, Failed, retrying) and its last error, any preflight warnings in amber, and, for a quick link, a note on its limits. A quick link has Stop sharing; a domain share has Remove from domain, plus Start tunnel when sites are exposed but no tunnel is running at all (for example after
yerd tunnel unpublish) or Restart tunnel when it failed. A failed tunnel already retries on its own; restarting it picks up a newly installedcloudflared. Other exposed sites are never interrupted.The key button sets or removes the share's share password. Protected shares show a key icon in the list.
Share a site opens one dialog for both kinds: pick a site, then Quick link or Your domain. For your domain the Public hostname is pre-filled with
{site}.{your-domain}and must stay on that domain; until Yerd knows your authorized domain the field stays empty and Share stays off. Sharing creates the DNS record and the daemon brings the tunnel up. Removing the last site takes it back down.Setup holds the rest: the
cloudflaredin use (install, update, or switch to Yerd's copy), connecting your Cloudflare account, and creating, starting or removing the tunnel for your domain. Closing the connect dialog before you authorize in the browser cancels the login.Each site's
⋯menu on the Sites page also has a Share publicly… shortcut that jumps straight to sharing that site, without going to the Share page first:
How requests reach your site
Both tunnel kinds connect to a dedicated, loopback-only listener inside the daemon rather than to the ports that serve .test traffic, so changing port redirects or elevation while sharing doesn't break the tunnel. That listener looks up the public hostname, finds the site it belongs to, and serves it through the same pipeline as local requests (proxy rules, static files, route rules, PHP). A public hostname that isn't mapped to a site gets a 404.
To your application, a tunnelled request looks like this:
HTTP_HOSTandSERVER_NAMEare the public hostname (for exampleapp.example.comorcalm-river-1234.trycloudflare.com), never the.testname, so URLs your app generates point at the public address.HTTPS=onandSERVER_PORT=443, because visitors use HTTPS at Cloudflare's edge. There is no HTTP-to-HTTPS redirect, and frameworks don't needTrustProxiesconfigured to get the host and scheme right.REMOTE_ADDRis127.0.0.1for every visitor.
Localhost-only tools become public
Because every tunnelled visitor appears to come from 127.0.0.1, anything your app only enables for local requests - Laravel Debugbar, Telescope, Clockwork, Symfony's profiler, an IP-gated admin page - is visible to anyone with the share URL. Disable those tools (or set a share password) while a site is shared.
WordPress
WordPress builds links from its stored home and siteurl options, so a site installed as https://app.test would normally redirect public visitors back to .test. For tunnelled requests to a WordPress site, Yerd injects a small auto_prepend_file script that swaps the host in home and siteurl for the public one (keeping each URL's path) for that request only. Local .test requests are unaffected, and nothing in the site's files is changed.
Limits of the override:
- Nothing is written to the database. Saving Settings > General over the tunnel keeps the stored local URL, so the site still works on
.testafterwards. Absolute URLs already stored in post content (images, links) are not rewritten and still point at.test. auto_prepend_fileinteractions. The override is passed to PHP-FPM as a per-requestPHP_VALUE, which FPM keeps on the worker that served it. Until that worker is recycled, it can shadow anauto_prepend_fileyou set in your ownphp.inifor later requests on the same worker (the script itself does nothing on non-tunnel requests). A site-level.user.iniauto_prepend_file(for example, from a security plugin) takes precedence instead, in which case the public-URL override doesn't apply. The one-click WordPress login uses the same mechanism and has the same property.
Password protection
Any shared site can require a password. Visitors are prompted by their browser (HTTP basic auth); any username works with the right password.
yerd tunnel password app 's3cret' # protect app on every tunnel
yerd tunnel password app --clear # remove it- The password applies to the site on both quick and named tunnels, and takes effect on the next request, without restarting anything.
- Local
.testaccess is never prompted. - Yerd checks the password itself and strips the
Authorizationheader before the request reaches PHP. While a share is protected, your app never receives anAuthorizationheader from tunnelled requests, so its own Basic or bearer token auth (an API, say) won't work over that share. - It is stored in plain text in the
0600config file and is never sent back to the CLI or desktop app. Treat it as a lightweight gate for a dev share, not as production authentication. There is no rate limiting of attempts. - Responses served behind the password are kept out of Cloudflare's shared cache: Yerd marks them
Cache-Control: private(droppingpublicands-maxage) and removesCDN-Cache-Control-style headers, since the edge cache does not key on the password. Browsers still cache as your app or response headers say. Pages the edge cached while the share was open can still be served until they expire, so set the password before sharing anything your app marks as publicly cacheable.
Preflight warnings
When a share starts (share, set-host, publish, or the daemon resuming the named tunnel), Yerd checks the site for setups that break for public visitors and shows a warning. Warnings never block the share.
- Vite dev server running. The web root has a
hotfile, so visitors' browsers try to load assets fromlocalhoston their own machine. Stopnpm run devor run a production build before sharing. SESSION_DOMAINpinned to the local TLD. If.envsetsSESSION_DOMAINto.app.test(or anything under your TLD), session cookies are rejected on the public hostname and logins fail. Unset it, or set it tonull, while sharing.
Warnings are computed once, when the share starts. After fixing the cause, they clear the next time the share starts (stop and share again, or set the hostname again).
Removing a named tunnel
yerd tunnel delete my-tunnelThis 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
cloudflaredruns unprivileged, as the daemon user. Sharing never invokes the privileged helper and never opens a public listening port - the tunnel dials out, and the origin listener it connects to is bound to127.0.0.1only.- The account certificate and per-tunnel credentials live in a daemon-owned
0700directory; 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 for every command and flag. The persisted mappings live in the [tunnel] section of the config file.