Proposal: a built-in "Doctor" for self-host and Cookbook troubleshooting

[ooovenenoso]

Odysseus already has the right philosophy: local-first, privacy-first, self-hosted, and actually owned by the user.

But one thing that still feels too fragile for new and non-technical users is this:

when something breaks, it is often unclear what broke, where it broke, and what to do next.

A lot of support pain seems to cluster around the same family of problems:

• Cookbook downloads fail with little useful feedback
• GPU / VRAM detection is confusing or wrong
• a backend looks installed but still shows up as unavailable
• Windows / self-host setups fail in ways that are hard to classify
• users end up guessing whether the problem is Python, Docker, drivers, permissions, network, model compatibility, or something else

Examples:

• Discussions: Cookbook #1031, Error when installing dependencies in cookbook help? #859, Enabling GPU support for Odysseus #789
• Issues: Cookbook fails when downloading any model and doesnt supply any error message and fails to detect VRAM #494, Trying to download any dependecies or module with the cookbook doesnt work and says crashed on w11 AND vram detection is partly not working #758, Cookbook Download Errors! Windows PC HELP #884, need help 9070 XT amd GPU not detected, windows manual installation #483, llama_cpp flagged as not installed and cant figure out how to fix it #1020

There is already useful work in this general direction:

• PR Add admin system diagnostics panel #523 (system diagnostics panel)
• PR feat(self-host): Ollama preflight + degraded-state diagnostics + GPU-error surfacing #807 (preflight / degraded-state diagnostics)
• Issue [Feature] Admin sidebar section — app logs viewer (v1) #981 (UI logs viewer)

Proposal

Introduce a built-in Doctor flow for self-host and Cookbook troubleshooting.

Not a giant observability dashboard.
Not an enterprise admin panel.
Just a very practical “tell me what’s wrong” path.

What Doctor should do

A first version could answer three simple questions:

1. What failed?
2. Why did it probably fail?
3. What should I do next?

For example, Doctor could check:

• Python / venv / dependency state
• backend availability (llama.cpp, vLLM, Ollama, etc.)
• GPU / VRAM detection sanity
• Docker ↔ host connectivity where relevant
• failed downloads / zero-file downloads / missing files
• whether useful logs or recent task output exist

UX direction

The important part is not “more diagnostics”.
It is guided recovery in plain English.

Example output:

• Problem: download failed before transfer started
• Likely cause: backend dependency missing or provider unreachable
• Next step: exact command / exact page / exact fix
• Optional: copy a support bundle for a Discussion or Issue

Why this feels worth discussing

Odysseus is strongest when it feels like your own AI workspace rather than a black box.

A built-in Doctor would support that philosophy:

• less guessing
• less terminal archaeology
• less “it crashed idk why”
• more user ownership of the system they are running

Questions

• Should Doctor be exposed directly in Cookbook, or as a shared self-host troubleshooting entry point?
• Should the first version focus on guided fixes rather than broad diagnostics coverage?
• What 3 checks would remove the most support friction immediately?
• Should Doctor produce a shareable support summary for Discussions / Issues?

Non-goals for v1

• full observability
• replacing all logs
• auto-fixing everything
• solving every backend/platform edge case

A narrow first pass that handles the most common self-host and Cookbook failures would already be a big win.

[CoolJohn-lab]

Agreed, but bear in mind most of the feedback about stuff being broken is from Windows users, and this project currently has no actual Windows port, instead relying on WSL to emulate Linux and run inside a docker Ubuntu container. As a Windows user myself that meant that the Cookbook stuff simply didn't work, installing it on an emulated instance of Ubuntu was way too slow and the installer just timed out, assuming it was stalled.

It wasn't, it was just waiting forever for emulated Ubuntu and Bash and whatnot to do their thing... Over the last 2 days we've seen a dozen or so pull requests raised that will fix much of that, but nothing about a full Windows compiled executable build with a proper InstallSheild installer, starting vLLM as a proper Windows Service, and whatnot. So right now even if the Windows build did work, it would be dog slow.

For now this remains a "Linux and Mac" tool with limited "yeah it sort of works on Windows too if you install 70GB of Linux emulator framework around it" support.

I'm building a dedicated Linux box for this app to run on, to mitigate the fact there's no native Windows support, and once up and running with it, I'll aim to use that dedicated Linux box to try and improve the Windows user experience and installation process, in so far as I can.

Not becuase I'm a Bill Gates fan, but because most big GPUs which are already in the world live inside Windows boxes, and people won't change to Linux so readily as I will just to use Odysseus, I don't think anyway. So it's important to get it working well on Microslop to drive adoption IMO.

[ooovenenoso]

Yeah — I don’t see this as replacing the broader Doctor idea.

If anything, I think it helps define what a high-value first cut of it could be.

What I was trying to get at with the Doctor idea is less “build a giant diagnostics surface” and more:

• tell the user what reality they are actually in
• explain what kind of behavior is expected there
• tell them what to do next in plain English

Your Windows point fits that really well.

If someone is on a Windows → WSL → Docker path, that seems like something Odysseus should be honest about upfront, instead of letting the user interpret slow setup, long waits, or timeouts as random breakage.

So maybe the first useful slice is not “Doctor does everything”, but something narrower like:

• detect the actual environment/path
• label it clearly as native, degraded, or experimental
• set expectations around slowdown / timeout behavior
• recommend the next best path plainly

That feels very in line with the spirit of the project to me:
not pretending every setup is equally supported,
not doing black-box magic,
just telling the truth about the system in front of the user.

So I still like the broader Doctor direction.

I just think your comment identifies a very strong v1:
honest environment detection + expectation-setting + actionable next-step guidance.

That seems like a much better first win than trying to jump straight to a huge all-purpose diagnostics flow.