Testing a Laravel Herd API on a Real Phone with Tailscale

Manassé Ngudia — Mon, 28 Sep 2026 20:14:34 +0000

How to get a physical device talking to your local Laravel site — and to the Ionic/Capacitor app that consumes it — without a public tunnel, without a LAN IP, and without TLS warnings.

You have a Laravel API running beautifully under Herd at https://myapp.test. You have a mobile app that talks to it. You plug in a phone, launch the app, and every request fails.

This is the moment a lot of Laravel developers first discover that their local development environment is, from the phone's point of view, completely invisible.

This article walks through fixing that with Tailscale. Along the way we'll hit one failure that is genuinely hard to diagnose — the site keeps working perfectly in your Mac's browser while returning 404 to every request from the phone — and understanding why is most of the value here.

Scope: this covers a physical device reaching a Herd site over Tailscale. Emulators and simulators have different networking models and aren't covered. Where I'm reasoning rather than reporting something I tested, I say so explicitly.

Why your phone can't see `myapp.test`

It's tempting to think of this as one problem. It's actually three, and they fail independently.

1. DNS. The .test TLD isn't real. Herd runs a dnsmasq resolver on your Mac that resolves *.test to 127.0.0.1, and configures macOS to use it. Your phone has never heard of that resolver. To your phone, myapp.test is not a slow host or a refused connection — it's a name that does not resolve.

2. Routing. Even with the name resolved, 127.0.0.1 means "this device". On the phone it means the phone. And Herd's nginx binds to the loopback interface only:

lsof -nP -iTCP:443 -sTCP:LISTEN
# nginx ... TCP 127.0.0.1:443 (LISTEN)

That's 127.0.0.1:443, not 0.0.0.0:443. Nothing outside the Mac can open that socket, whatever address it asks for.

3. TLS trust. Herd serves .test sites over HTTPS using a certificate from its own local CA, which it installs into your Mac's keychain during setup. Your phone doesn't have that CA. Even once DNS and routing work, you get certificate errors — and on iOS, installing a custom CA profile on a device is a genuine nuisance.

Any solution has to answer all three.

Why the usual answers disappoint

Use the LAN IP. Bind the dev server to 0.0.0.0, point the phone at http://192.168.1.42:8000. This works, right up until it doesn't:

Both devices must be on the same network. Guest wifi, corporate wifi with client isolation, and phone-on-cellular all break it.
DHCP reassigns your Mac's address and every hardcoded URL goes stale.
It's plain HTTP. On Android you must enable cleartext; on iOS you fight App Transport Security.
It doesn't give you myapp.test, so any Host-based routing or absolute-URL generation behaves differently than in your browser.

Use a public tunnel (ngrok, Expose, Cloudflare Tunnel). These genuinely solve DNS, routing and TLS in one step, which is why people reach for them. The costs: the URL usually changes on every restart, so you're re-editing config constantly; free tiers add latency and rate limits; and — the part worth pausing on — your in-development app, with its debug output and half-finished auth, is now on the public internet, reachable by anyone who guesses or is handed the URL.

Tailscale is a different shape of answer. It's a WireGuard-based mesh VPN: every device you log in becomes a node on a private network with a stable address and a stable DNS name. Nothing is exposed publicly. And the part that matters most here — Tailscale can terminate TLS for you with a publicly trusted certificate, so phones accept it with no profile to install.

	LAN IP	Public tunnel	Tailscale
Works off your network	✗	✓	✓
Stable address	✗	Usually ✗	✓
Trusted TLS	✗	✓	✓
Stays private	✓	✗	✓

What we're building

Two separate paths, and keeping them separate in your head is the single most useful idea in this article:

  Phone / tablet (on your tailnet)
    │
    ├── app bundle  ──►  http://100.x.y.z:8101
    │                    (Vite dev server, plain HTTP, live reload)
    │
    └── API calls   ──►  https://my-mac.tailnet-name.ts.net/api
                              │   tailscale serve  (TLS terminated here)
                              ▼
                         https://myapp.test
                         (Herd nginx → Valet → Laravel)

The API hop gets a real hostname and a real certificate. The dev server hop is plain HTTP to a raw address. They have different transport rules, they fail in different ways, and you debug them separately.

If you only have a web app and no mobile app, you only need the right-hand path — skip the live-reload section entirely.

Prerequisites

Herd serving your site locally: https://myapp.test loads in your Mac's browser.
Tailscale installed on both the Mac and the phone, logged into the same tailnet.
HTTPS enabled for your tailnet (Tailscale admin console → DNS → Enable HTTPS). This is what makes the trusted certificate possible.

Confirm both devices are visible:

tailscale status

100.64.0.10   my-mac              you@   macOS    -
100.64.0.11   my-tablet           you@   android  -

If the phone isn't listed, stop here and fix that first — everything below depends on it.

Step 1 — Expose Herd on your tailnet

One command:

tailscale serve --bg "https+insecure://myapp.test"

Available within your tailnet:

https://my-mac.tailnet-name.ts.net/
|-- proxy https+insecure://myapp.test

Serve started and running in the background.

Two details worth understanding rather than copying.

Why https+insecure. Tailscale connects to Herd over loopback, and Herd presents its own local-CA certificate. Tailscale has no reason to trust that CA, so without +insecure the hop fails. This is not a security compromise: the "insecure" part is a connection from your Mac to itself. The certificate that your phone sees is a completely different one, issued by Let's Encrypt for your ts.net name, and it's fully validated. That's the trick that makes this pleasant — a publicly trusted cert on a privately reachable host.

--bg persists. The proxy survives reboots until you explicitly turn it off. Check it any time with tailscale serve status.

The first request triggers certificate issuance, which can take long enough to look like a hang. Warm it up:

tailscale cert my-mac.tailnet-name.ts.net

Now test it:

curl -s -o /dev/null -w "%{http_code}\n" https://my-mac.tailnet-name.ts.net/api/user

If that returns 401 — congratulations, you're done, skip to Step 3. If it returns 404, read on, because this is the interesting part.

Step 2 — The 404 that isn't a routing problem

Here's the symptom that costs people an afternoon:

# Through Tailscale — 404
curl -s -o /dev/null -w "%{http_code}\n" https://my-mac.tailnet-name.ts.net/api/user
404

# The exact same route, locally — 401
curl -s -o /dev/null -w "%{http_code}\n" -k https://myapp.test/api/user
401

Same nginx. Same PHP-FPM. Same Laravel. Same route. One works, one doesn't.

What's actually happening

tailscale serve is a reverse proxy, and like most reverse proxies it forwards the original Host header. Even though you told it to proxy to myapp.test, the request arriving at nginx carries:

Host: my-mac.tailnet-name.ts.net

You can prove this in one command, no Tailscale involved — just lie about the Host:

curl -s -o /dev/null -w "%{http_code}\n" -k -H "Host: myapp.test" https://127.0.0.1/api/user
# 401  ← correct

curl -s -o /dev/null -w "%{http_code}\n" -k -H "Host: my-mac.tailnet-name.ts.net" https://127.0.0.1/api/user
# 404  ← reproduced, with Tailscale entirely out of the picture

That's the whole bug. The Host header doesn't match any site Herd knows about.

Why the obvious fix doesn't work

The instinct is to add the hostname to nginx's server_name. This will not work, and understanding why saves you from chasing it.

Look at a Herd vhost:

server {
    listen 127.0.0.1:443 ssl;
    server_name myapp.test www.myapp.test *.myapp.test;
    root /;

    location / {
        rewrite ^ "/Applications/Herd.app/Contents/Resources/valet/server.php" last;
    }
}

Note root / and that every request is rewritten to a single server.php. Herd (like Valet, which it's built on) doesn't use nginx to map hostnames to directories. nginx is a thin shell; server.php reads the Host header itself and resolves which project to serve. Adding a server_name alias gets you past nginx and straight into a PHP front controller that looks at Host, doesn't recognise my-mac.tailnet-name.ts.net, and falls through.

The fix

Valet has a default site: the project served when no site matches the incoming host. Set it to your project and the fallthrough lands where you want.

Find your config — Herd keeps it separately from a standalone Valet install:

# Herd
~/Library/Application\ Support/Herd/config/valet/config.json

# Standalone Valet
~/.config/valet/config.json

Back it up, then add a default key pointing at the project root (not public/):

{
    "tld": "test",
    "loopback": "127.0.0.1",
    "paths": [ "..." ],
    "default": "/Users/you/Projects/myapp"
}

No restart needed — server.php reads this per request. Re-run the curl:

curl -s -o /dev/null -w "%{http_code}\n" https://my-mac.tailnet-name.ts.net/api/user
# 401

401 is the goal. It means the request reached Laravel and Laravel declined it, which is exactly correct for an unauthenticated call.

Know the side effect. default is global. Every unmatched hostname on your machine now serves this project instead of 404ing. Sites you reach by name are unaffected, but if you juggle many local projects, remember you've set this — and that a Herd update could silently drop the key, at which point the tailnet 404s return while local still works. That asymmetry is the tell.

A dead end, so you don't repeat it

My first attempt was a custom nginx server block on a spare port that rewrote the Host and proxied onward — a reasonable design. Herd's config directory does glob-include extra files, so it should have worked.

It didn't. Herd's CLI reported Nginx has been restarted, but the master process ID never changed and the listener never appeared. The config was simply never loaded, with no error anywhere. If you ever add custom nginx config to Herd, verify the PID actually changed rather than trusting the success message.

The Valet default approach is one JSON key and needs no restart at all. Prefer it.

Step 3 — Point the mobile app at it

With the API reachable, the app needs two things: the right API URL, and its own bundle delivered to the device.

The API URL

Put the tailnet URL wherever your app reads its API base. In a Vite-based Ionic app that's an env var:

VITE_API_BASE_URL=https://my-mac.tailnet-name.ts.net/api

Check which env file actually wins. Vite's precedence is .env → .env.[mode] → .env.local → .env.[mode].local, later winning. A forgotten .env.local overriding the .env you're carefully editing is a classic way to lose twenty minutes. A machine-specific tailnet URL belongs in .env.local anyway — it's gitignored, and it shouldn't be in anyone else's checkout.

Live reload, and where the dev-server URL really lives

For live reload, Capacitor loads your app from the Vite dev server instead of the bundled files. The Ionic CLI arranges this — and it's worth knowing exactly how, because the mechanism produces a confusing failure mode.

Your committed capacitor.config.ts has no server key and shouldn't. At run time, the CLI writes one into the generated native config:

android/app/src/main/assets/capacitor.config.json
ios/App/App/capacitor.config.json

Both are gitignored. It writes:

{ "server": { "url": "http://192.168.1.42:8101" } }

and strips it again on clean shutdown.

The trap: that cleanup only runs on a clean exit. Kill the process — close the terminal, force-quit, lose the SSH session — and the stale URL stays in the native config. The app then keeps trying to load from a dev server that moved or died, and shows a blank screen. If a device build mysteriously loads nothing, check that file first.

This is also why you should never ship an APK built from a live-reload run: it has a dev-server URL baked in.

By default the CLI picks the address by enumerating your network interfaces and prompting you — its own help text says to "make sure your device is on the same Wi-Fi network as your computer", which is precisely the assumption we're removing. Two flags take control:

--external binds the dev server to all interfaces (including the Tailscale one).
--public-host=<host> sets the address written into the native config, used verbatim.

So rather than hardcoding an address, derive it:

{
  "scripts": {
    "dev:android:tailscale": "ionic capacitor run android -l --external --public-host=$(tailscale ip -4 | head -1)"
  }
}

tailscale ip -4 returns this machine's tailnet address. No hardcoded IP, works on any machine with Tailscale, no edit when anything changes.

npm run dev:android:tailscale

Verify the dev server is genuinely reachable over the tailnet:

curl -s -o /dev/null -w "%{http_code}\n" http://100.x.y.z:8101/
# 200

Step 4 — Verify each hop separately

When something fails, resist testing "the app". Test the chain one link at a time — the status code tells you exactly which link broke.

# 1. Herd itself, bypassing everything
curl -s -o /dev/null -w "%{http_code}\n" -k https://myapp.test/api/user

# 2. Host-header routing, still bypassing Tailscale
curl -s -o /dev/null -w "%{http_code}\n" -k \
  -H "Host: my-mac.tailnet-name.ts.net" https://127.0.0.1/api/user

# 3. The full path through Tailscale
curl -s -o /dev/null -w "%{http_code}\n" https://my-mac.tailnet-name.ts.net/api/user

# 4. The dev server over the tailnet
curl -s -o /dev/null -w "%{http_code}\n" http://100.x.y.z:8101/

# 5. From the Mac, can you actually see the phone?
tailscale ping my-tablet

Reading the results:

Code	Meaning
`401` / `422`	Good. You reached Laravel; it responded. An auth error is a successful round trip.
`404`	Reached nginx, wrong site. Host-header routing — Step 2.
`000`	Never got an HTTP response: DNS, connection refused, or TLS handshake failure.
`502` / `504`	Tailscale reached nginx but the upstream failed. Is Herd running?

Send a real request body to see an actual response rather than a bare code:

curl -s -X POST https://my-mac.tailnet-name.ts.net/api/auth/login \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"email":"nope@example.com","password":"wrong"}'
# {"error":"Unauthorized"}

A JSON error body from your application is the strongest possible signal: every hop works and you're talking to Laravel.

Platform notes

Android: cleartext

The API hop is HTTPS, so it's fine. The dev-server hop is plain HTTP to a raw address, and modern Android blocks cleartext by default. Capacitor's template enables it globally, but the better pattern is per-build-type overlays — permissive in debug, hardened in release:

<!-- android/app/src/debug/AndroidManifest.xml -->
<application android:usesCleartextTraffic="true"
    tools:replace="android:usesCleartextTraffic" />

<!-- android/app/src/release/AndroidManifest.xml -->
<application android:usesCleartextTraffic="false"
    tools:replace="android:usesCleartextTraffic" />

Build-type overlays aren't touched by cap sync, so the hardened release value survives every regeneration. Production rejects plaintext; development doesn't have to care.

iOS: App Transport Security — a caveat, not a recipe

I verified the Android path end to end. I did not test iOS. What follows is reasoning from Apple's documented rules, and you should confirm it on a device before relying on it.

A common ATS relaxation for local development is:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

This permits cleartext to private ranges — 10/8, 172.16/12, 192.168/16, link-local and .local. It's a good setting because it isn't pinned to a specific IP.

But Tailscale addresses are in the CGNAT range 100.64.0.0/10, which is not in that list. So http://100.x.y.z:8101 would be expected to fail ATS on iOS even though it works on Android.

The API is unaffected — it goes over HTTPS to a ts.net name with a publicly trusted certificate, which ATS is perfectly happy with. It's only the plain-HTTP dev-server hop that's in question.

If you hit this, the clean fix is to stop using plain HTTP for that hop too — put the dev server behind Tailscale Serve on a second port so it also gets a real certificate:

tailscale serve --bg --https=8443 http://127.0.0.1:8101

then point --public-host at the ts.net name instead of the raw IP. That removes the cleartext question on both platforms. I haven't tested this variant either — it follows from how Serve works, but verify before trusting it.

CORS

Capacitor runs your app in a WebView with a real origin, so browser CORS rules genuinely apply. A permissive config/cors.php is typical:

'paths' => ['api/*'],
'allowed_origins' => ['*'],
'supports_credentials' => false,

Worth being precise about why this is acceptable rather than just convenient: with token auth — a JWT or bearer token in an Authorization header — and supports_credentials => false, there is no cookie or session riding along on cross-origin requests. A wildcard origin can't be abused to make authenticated requests on a victim's behalf, because nothing is attached automatically.

If you use cookie-based session auth instead, this reasoning does not hold — you'd need supports_credentials => true, an explicit origin list (the spec forbids * with credentials), and proper SESSION_DOMAIN handling.

WebSockets are a separate problem

If you use Laravel Reverb for broadcasting, note that getting HTTP working does nothing for it. A config left at REVERB_HOST=127.0.0.1 points the phone at itself. You'd need Reverb bound to a reachable interface and its own Serve mapping. Easy to overlook, because HTTP works fine and only realtime features quietly fail.

Troubleshooting

Symptom	Cause	Fix
`404` over the tailnet, site fine locally	Host header doesn't match any Herd site	Set Valet's `default` (Step 2)
`000` / TLS error on first request	Certificate not issued yet	`tailscale cert my-mac.tailnet-name.ts.net`, retry
Device can't resolve the `ts.net` name	MagicDNS off, or device not on the tailnet	Check `tailscale status` on both
App loads, all API calls fail	Wrong env file, or app not rebuilt	Check env precedence; `.env.local` beats `.env`
App shows a blank screen	Stale `server.url` from a killed live-reload run	Check the generated native `capacitor.config.json`
Custom nginx config ignored	Herd reports a restart that didn't happen	Verify the master PID changed; prefer the Valet `default`
Works on wifi, fails on cellular	Device dropped off the tailnet	Check the Tailscale app is connected

Security

The default here is genuinely private. tailscale serve publishes only within your tailnet — devices logged into your account. Nothing is on the public internet, and tailscale serve status says so explicitly:

https://my-mac.tailnet-name.ts.net (tailnet only)

Its sibling, tailscale funnel, is the opposite: it puts the same service on the public internet. It's a legitimate tool for webhook testing, but it is not what you want for routine device testing, and it deserves real caution — a dev environment typically has debug mode on, verbose errors, seeded accounts with weak passwords, and no rate limiting.

Two rules worth keeping:

Never point Serve or Funnel at a production site.
Tear down what you're not using.

Teardown

# Stop the proxy
tailscale serve --https=443 off

# Confirm
tailscale serve status

Then remove the default key from your Valet config if you don't want the global fallback.

Wrapping up

The mechanics reduce to two commands and one JSON key:

tailscale serve --bg "https+insecure://myapp.test"
npm run dev:android:tailscale

plus "default" in your Valet config so Herd knows which project an unfamiliar hostname belongs to.

The idea worth keeping is the one from the diagram: your API and your dev server are two different hops with two different transport rules. The API gets a real hostname and a real certificate and works anywhere. The dev server is plain HTTP to a raw address and needs platform permission to be reached at all. When something breaks, find out which hop it was before you change anything — the status codes in Step 4 will tell you in about ten seconds.

And if you see a 404 from your phone while the same URL loads perfectly in your browser: it's the Host header. It's almost always the Host header.

DEV Community: Manassé Ngudia