Doctor Demo

When an agent’s machine fails to set up, someone has to read a long log to find out why. Preconfig Doctor reads it for you. It finds the step that broke and the lines that show why, names the cause, and when the fix belongs in preconfig.yaml, it writes the change and rebuilds every platform’s file. It serves the project’s premise: an agent’s machine should be ready before the agent starts, described once in a spec a person can review and proven on a clean machine by the project’s own tests. Doctor is for the times that proof fails. The failures below were recorded on a clean Ubuntu 24.04 machine, and Doctor’s own engine runs in your browser. Nothing you paste here leaves this page.

Recorded failures, real engine. Eight of the nine failures were planted on purpose in a sample repository, and the ninth comes from the test machine’s own network, which can’t reach NodeSource. Each was run for real with preconfig verify or a Docker build. Every log is what the machine printed, and the diagnosis comes from the engine’s own code.

How to Run It

1. Pick a failure. Nine recorded logs, from the Alpha’s run without Redis to a misspelled package in Cursor’s Dockerfile, or paste a log of your own.
2. Read the diagnosis. The step that broke, the cause, the lines that show it, and where the fix belongs: the spec, the network, the repository, a secret, the code or the machine.
3. Apply the fix. When the fix belongs in the spec, Doctor writes the change and shows the diff, and every platform’s file is rebuilt in the page.
4. See the proof. For a recorded failure that Doctor fixed in the spec, the result of running the fixed spec again on a clean machine.

On a wide screen the log and the diagnosis sit side by side: open it full screen.

What Doctor Reads

The output of preconfig verify, the full log it writes with --log, its --json events, the setup script’s own output, a Docker build, a GitHub Actions job or cloud-init’s log. The full log works best: for a package built from source, the cause can sit further up than the last lines verify repeats on the screen.

How Doctor Decides

Doctor uses rules: 31 of them, each tying a known error format to a cause, tried in order with the most specific first. A rule that fits gives the same answer every time, with the lines it came from. When no rule fits, Doctor says it doesn’t know and shows the lines that look like errors. It never changes the spec on a guess.

On eleven cases recorded after its rules were frozen, Doctor was right eight times, said “unknown” twice and was scored wrong once: it blamed the network correctly, without naming the host. It wrote no wrong change, and every change it wrote that was run again on a clean machine took the setup past the failure. The Doctor page has the method and every figure.

What Is Real Here

Every recorded log is what a clean Ubuntu 24.04 machine printed during a real run on the test machine. Eight of the nine failures were planted on purpose in sample repositories written for the demo, and the ninth comes from the test machine’s network. No coding agent platform runs in this demo. The diagnosis, the change and the rebuilt files come from the engine’s own Go code, compiled to WebAssembly, and a test compares every answer with the command line’s.