netris-nestri/apps/nesdoctor/README.md

nesdoctor

Is this machine any good — as a Nestri host, or as a client?

# macOS and Linux
curl -fsSL https://doctor.nestri.io/install.sh | sh

# Windows
powershell -c "irm https://doctor.nestri.io/install.ps1 | iex"

Both download one binary, verify its checksum, run it, and delete it. They install nothing, need no administrator rights, and touch no system directory. The scripts those URLs serve are the files in install/ — the worker fetches them from this repository, so you can read exactly what you are about to run before you run it.

They pin a release tag rather than using releases/latest, because this repository ships product releases too and latest is whichever went out most recently. NESDOCTOR_TAG overrides it.

Or build it yourself:

cargo run --release -p nesdoctor

Checks every hard requirement for running a Nestri box, measures what your connection actually does when it is busy, and asks at most five questions.

Nothing is uploaded

There is no server. No telemetry endpoint exists, and there is no build of this program that reports home — the network test talks to Cloudflare's public speed-test sink and to 1.1.1.1, neither of which is ours.

The output is a line on your terminal. If you want us to have it, you paste it somewhere. If you do not, we never had it. That is a property of the design rather than a promise about our intentions: there is nothing to switch on later.

The shareable line carries no hostname, no IP, no username, no game titles and no file paths — a size band rather than a size, and an hour histogram rather than timestamps. It is put on your clipboard at the end so pasting it is one keystroke.

The long version lands in nesdoctor.json: every check with its reason, the full latency series, and your installed titles with sizes and launch times if you said yes to Steam. That file is considerably more useful to us than the line — it is what lets us size a game library and see which requirement actually stops people — so do have a read through it and send it along if nothing in there bothers you. Plain JSON, entirely optional, and the one-line version is already plenty.

Reading your Steam library needs an explicit yes, and the question is asked last, after you have seen what this program does.

The number worth running it for

Everybody knows their download speed. Almost nobody has seen how much latency their connection adds when it is busy, and for anything interactive that is the figure that decides it:

  upstream            28 Mbps
  latency, idle      179 ms
  latency, loaded    198 ms
  added under load   +19 ms   grade B

A 500 Mbps uplink that queues for 300 ms under load cannot carry a game. A 25 Mbps one with fq_codel or CAKE can. If your grade is C or F it is almost always a router setting rather than a line you need to upgrade.

Options

--no-net	Skip the network test (it uploads ~100 MB)
--no-steam	Never look at Steam, and do not ask
--yes	Take the defaults — for a second run, not a first
--json <PATH>	Where to write the full report
--quiet	Only the summary line, for scripting
--no-open	Do not offer to open a browser; just print the link
--submit-url	Where the submit link points (default https://doctor.nestri.io)

Verdicts

HOST-READY	Passes everything, and close enough to the network to serve others
HOST-READY-LOCAL	Passes everything, but far enough out that it can only serve players nearby
HOST-NET	Good machine; the connection is in the way
HOST-FIXABLE	Nothing is a hardware limit — what is missing can be installed
CLIENT	Not a host. A complete answer, and what most machines are
UNKNOWN	A blocking check could not be run. An unknown is not a no

Sending it back

At the end it prints a link, lists in plain English what the link contains, and opens it when you press Enter. That is the whole submission — no account, no form, no email client.

One thing worth knowing if you are reading install/install.sh: it reopens stdin on /dev/tty before handing over. Piped into a shell the documented way, the script's stdin is the pipe and the pipe is at end of file, so without that line nesdoctor correctly sees a non-terminal stdin and skips every question — a run that completes, looks fine, and answers nothing. Running the script from a file works perfectly, which is what makes it worth a comment.

The link is built from readable query parameters rather than an encoded blob. A blob would be shorter and would let us send more; it would also mean you cannot read what you are sending, which is the one thing this program has going for it.

If you would rather not click a link we wrote, the short line is printed too and put on your clipboard.

What it deliberately does not tell you

• A pass is not a promise. Every check is a necessary condition. Nothing here runs under load, so a machine that passes can still fail on block I/O.
• vulkaninfo reporting the encode extension is not proof the path works. We have had a correct extension list over a broken path before.
• The host's virglrenderer and Mesa are not checked at all, on purpose. The box carries its own inside the image it runs in, so the host's copies are not on the path — and a row that could only ever say "present, patch state unknown" told prospective hosts their machine was wrong when it was not.

Building

cargo build --release -p nesdoctor

Four dependencies, three of them serde/clap/anyhow. Everything that could be done with std is: the VDF parser, the platform probes and the text wrapping are all in-tree, because a binary handed to strangers has a dependency tree that is part of its interface.

A static build, for a release someone downloads rather than compiles:

cargo build --release -p nesdoctor --target x86_64-unknown-linux-musl