Skip to content

fghj doctor

Terminal window
fghj doctor # report only
fghj doctor --fix # and fix what it can

fghj takes more from your machine than most dev tools do: a Docker daemon new enough for BuildKit, ports 80 and 443 bound on a loopback address of its own, OS DNS routing for *.fghj.internal, and a root CA trusted by your system and your browsers.

Each of those can go missing on its own — a Docker upgrade, an OS update that resets /etc/resolver or restarts systemd-resolved, a keychain reset, a new browser profile, another process grabbing 443 — and when one does, every one of them produces the same symptom: the browser says the connection was refused, and nothing says why.

fghj doctor checks them all and tells you which one it is.

On macOS:

$ fghj doctor
✓ fghjd control socket: connected to /var/run/fghjd.sock
✓ cue CLI on PATH: cue version v0.17.1
✓ Docker Engine reachable: server 29.4.0, API 1.54
✓ BuildKit available: API 1.54 supports the BuildKit session endpoint
✓ fghjd is active: serving DNS, 80 and 443
✓ environment sidecars: all 2 running: shop, files
✓ proxy loopback alias: 127.222.0.1 is up on lo0
✓ proxy listening on 443: 127.222.0.1:443 accepts connections
✓ proxy listening on 80: 127.222.0.1:80 accepts connections
✓ /etc/resolver entries: fghj.internal -> 127.0.0.1:49969, fghj.raw.internal -> 127.0.0.1:49969
✓ raw-zone listeners: fghjd is listening on all 11
✓ fghj.internal resolves through the OS: doctor.fghj.internal -> 127.222.0.1
✓ root CA trusted by the system: /private/var/lib/fghjd/ca/ca-cert.pem verifies against your login keychain
all clear

On Ubuntu the rows that differ read:

✓ proxy loopback alias: 127.222.0.1 needs no alias on this platform
✓ systemd-resolved link fghj0 entries: fghj.internal -> 127.0.0.1:56373, fghj.raw.internal -> 127.0.0.1:56373
✓ root CA trusted by the system: /var/lib/fghjd/ca/ca-cert.pem verifies against the system CA store (/etc/ssl/certs)
✓ browsers trust the root CA: in the browsers' certificate databases under /home/you

There’s one sidecar line for all workspaces with an environment, and it names only the sidecars with a problem. It warns when a sidecar is missing (fghjd brings it back within a second), when it predates traffic capture, or when its network predates fixed sidecar addresses; the last two go away when you recreate the environment. It fails, with the error, when fghjd can’t start it again.

A failing check prints what it found and what to do about it:

✗ proxy listening on 443: 127.222.0.1:443 is not accepting connections: Connection refused
→ run `fghj daemon start`; if it reports the port is in use, something else
on this machine has 80/443 (another dev proxy, nginx, Docker Desktop's own
port binding)
MarkMeaning
✓Checked, and it’s the way it should be.
·Not set up yet, and nothing to do: your first fghj wire sets it up.
!Not how it should be, but nothing is broken yet — it affects one feature, or fghj will fix it on the next start.
✗Something fghj needs is missing or wrong, and it will visibly misbehave until it’s fixed.

Only a ✗ sets a non-zero exit code, so fghj doctor && … gates on “is fghj broken”, not on “is anything less than perfect”.

Your first fghj wire is what finishes setup: it tells fghjd which Docker is yours and trusts the CA. Until something is wired, the Docker and CA checks show · — not set up yet, nothing to fix — and the summary says so:

· Docker Engine reachable: not set up yet — your first `fghj wire` tells fghjd which Docker to use
· BuildKit available: checked once Docker is set up
· root CA trusted by the system: /private/var/lib/fghjd/ca/ca-cert.pem isn't trusted yet — your first `fghj wire` asks to trust it
nothing broken; 3 check(s) wait for your first `fghj wire`

Once something is wired, the same two fail with ✗ if they go missing, because then something really is wrong.

The two things that warn rather than fail:

  • fghjd is active warns when the daemon is idle. That’s a state you can ask for with fghj daemon stop, and every host check below it then fails correctly — so being idle is reported as a warning with the rest of the failures following from it, not as a broken install.
  • cue CLI on PATH warns when cue is missing. Only fghj validate needs it; fghjd resolves and runs workspaces without it.

fghjd’s DNS server listens on a port the OS assigns fresh every time it starts, and the OS resolver config (/etc/resolver/fghj.internal on macOS, the fghj0 link on Linux) is the only place that port is recorded. So config left behind by a previous fghjd process looks completely healthy — the file or link is there, the zone is correct — and points at a port nothing is listening on. Every *.fghj.internal name then fails to resolve, with no visible cause.

That’s why the fghj.internal resolves through the OS check doesn’t inspect the file. It asks your OS to resolve a name in the zone, exactly as a browser would, and checks that the answer is fghj’s proxy address. fghj daemon restart is the fix, and the hint says so.

Plain fghj doctor changes nothing on your machine. That’s deliberate: its output goes into bug reports, and a doctor that fixes things as it finds them is always green on the second run, which makes a problem that keeps coming back invisible.

fghj doctor --fix runs the checks, fixes the ones it knows how to, says what it did, then runs the checks again and prints the result:

  • Docker — points fghjd at the Docker your docker command uses, as fghj wire does. fghjd restarts onto it if it changed.
  • fghjd idle — activates it, as fghj daemon start does.
  • CA not trusted — on macOS, trusts it from your terminal, which is the password dialog.
  • Browsers don’t trust the CA (Linux) — asks fghjd to add it to every workspace owner’s Firefox and Chrome databases again.

Everything else — a port taken by another process, Docker not running at all — it can’t fix, and the hint says what to do. Most of those point at fghj daemon start or restart, because activating re-adds the loopback alias, rebinds 80/443 and rewrites the resolver files every time it runs.

The web UI’s telemetry drawer (the ⚡ button in the header) has a Doctor tab showing the same report, with a re-run button. It’s fetched when you open the tab rather than polled — nothing it measures changes on its own, so the useful loop is read it, go fix the thing, press re-run.

The UI’s version omits the two client-side checks (fghjd is obviously reachable if the page loaded, and cue is a property of your shell, not the daemon’s).