Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Diagnose connection and runtime problems

Start by checking health and logs on the app's checkout computer:
fleet --version fleet doctor fleet list --json fleet inspect notes fleet logs notes
Keep device codes, private setup URLs, credentials, and app data out of shared bug reports.

.fleet addresses don't resolve

  1. Confirm Tailscale is connected on both the gateway and the device opening the app.
  2. Check that the device accepts Tailscale DNS settings.
  3. In Tailscale DNS settings, confirm the restricted nameserver for fleet matches the exact IP printed by fleet setup.
  4. If you use an exit node, enable Use with exit node on that restricted nameserver.
  5. Make sure your gateway computer is awake and reachable on UDP and TCP port 53 over Tailscale.
Unregistered .fleet names are intentionally rejected. On Linux, Fleet leaves /etc/resolv.conf untouched and relies on Tailscale split DNS; on macOS, fleet setup --install writes /etc/resolver/fleet.

The browser shows a certificate error

DNS resolution and certificate trust are separate steps:
  • On iPhone, installing the profile isn't enough — you must also enable Fleet private apps in Settings → General → About → Certificate Trust Settings.
  • After reinstalling or resetting ~/.fleet/v2, your gateway generates a new root CA, so previously enrolled devices need the updated root certificate.
  • Never click through certificate warnings or downgrade to HTTP. Re-run fleet setup --install (on computers) or fleet phone (on iPhone) to install the matching public root.

Gate asks me to sign in again

Sessions last 30 days unless revoked with fleet gate reset. Run fleet gate on your gateway to generate a fresh 10-minute code and enter it at https://gate.fleet, or run fleet open notes on the gateway to sign in your local browser automatically.

My edit doesn't show up

  1. Run fleet logs notes — if the new edit failed to compile, Fleet keeps the last working build live so the app stays usable.
  2. Confirm your agent edited the registered checkout shown by fleet list --json, not a separate copy.
  3. Make sure the agent didn't start a separate Vite or dev server.
Once a build succeeds, open browsers reload automatically.

An app on another computer is unavailable

Both your gateway and the checkout computer must be awake and connected to Tailscale, and your tailnet policy must allow the gateway to reach TCP port 42174 on the checkout computer. Run fleet logs and fleet inspect directly on the checkout computer. See multiple computers.

fleet phone won't start

  • Make sure you're running fleet phone on your gateway, not a secondary computer.
  • If Tailscale reports access denied, grant your user Serve permissions once with sudo tailscale set --operator=$USER and rerun fleet phone.
  • If port 8444 is already used by another Tailscale Serve route, Fleet refuses to overwrite it — inspect tailscale serve status before changing anything.
  • Setup links expire after 15 minutes; rerun fleet phone for a fresh link, or run fleet phone off to remove Fleet's temporary route manually.

A scheduled job didn't run

Jobs only run while the checkout computer is awake. Check fleet inspect APP and fleet logs APP, and confirm the job name in fleet.json matches an exported function under jobs in server/index.ts. Remember that overdue jobs run one catch-up execution after restart, and interrupted runs retry with the same ctx.runId.

Remove Fleet

Run this on each computer you want to clean up:
fleet uninstall
This stops the background service and removes local startup entries and computer certificate trust, while leaving your app checkouts and SQLite data intact.
If you're retiring your gateway completely, also remove:
  • The restricted fleet nameserver in Tailscale DNS settings
  • The Fleet private apps profile on any connected iPhones (Settings → General → VPN & Device Management)
  • Optionally ~/.fleet/runtime and ~/.fleet/v2 after backing up anything you want to keep