Diagnosing Connectivity
swarmfile-doctor checks that a hub, or your own community server, is reachable and correctly configured, from a machine with no mount. It runs the same probe core the desktop app's Doctor uses (shared through the open swarmfile-lib) and prints the same report (--json for scripts).
Install#
curl -fsSL https://get.swarmfile.com/doctor | sh
Use#
# reachability + the server's descriptor, unauthenticated
swarmfile-doctor --hub-url https://hub.swarmfile.com
# add the block-path probe (needs a key and a project)
SWARMFILE_API_KEY=sf_key_… swarmfile-doctor \
--hub-url https://your-server --org-id my-org --project-id <id>
# machine-readable, and to a file
swarmfile-doctor --hub-url https://your-server --json --report /tmp/doctor.json
--hub-url defaults from $SWARMFILE_HUB_URL; --token from $SWARMFILE_API_KEY.
The checks#
| Check | What it proves |
|---|---|
dns <host> | the hub hostname resolves |
hub https /health | GET /health (or /healthz) answers 2xx over TLS |
hub deep health | GET /healthz/deep (a 404 is expected for a community server) |
cloud path | the block route answers 404 for a never-written content id (the storage path is open) |
oidc token | an authenticated project metadata read against the active project (a valid session or token) |
server_profile | the profile descriptor at GET /api/profile (core on a community server, hosted on the hosted service) |
With the engine running#
The same binary completes the full picture when a swarmfile-engine is running (the desktop app, or a seed node). It finds the engine through its cache-dir control.json and asks it over the local control socket for the checks that need it (peer-to-peer connectivity and local-network peer discovery, the mount, transfer stats, the host firewall, the engine socket) against whatever hub the engine is configured for, the hosted cloud or a community server. Those checks come back real; with no engine running they appear with the same names as pass + "skipped (requires the engine)". A --hub-url still runs the engine-free probes against that hub and merges in the engine's engine-only checks, so you can check one hub while still getting local engine/network state.
Options and exit codes#
Flags mirror the desktop doctor (--json, --quiet, --report <path>, --hub-url, --no-iroh, --no-mdns, --iroh-peer, --cache-dir, --latency, --verbose), plus the headless inputs --token, --org-id, --project-id and --timeout (seconds). --latency adds the per-route timing probe above (three samples each, 2 s per sample, 6 s overall); the desktop tray's Run doctor sends the same flag. No report file is written unless you pass --report <path>.
--repair (with --yes to skip the prompt) reinstalls the Swarmfile desktop app from the update channel it was installed from, after verifying the download; on a machine without the desktop app it refuses and points you at the downloads page. See swarmfile-doctor --repair.
Exit codes match the desktop doctor: 0 every check pass, 1 at least one failure, 2 warnings only. With --repair: 0 reinstalled, 1 a step failed, 3 refused or canceled with nothing changed. A connection failure or a refused key prints a hint naming what to look at.