Troubleshooting
On a diskless box a reboot is a clean restore of the last saved state, safe at any time. Most of this page is knowing when that is the fix.
What a healthy first boot looks like
Within a minute of power, http://pipeos.local/ answers on a phone and a laptop, with no certificate warning. A second Machine sees the new one in its lobby within seconds as pipeos-xxxx.local. After the claim the recovery phrase is shown once; the Overview reads all green; Setup shows the name and a Claude pill that says signed in; one question in the chat gets one answer.
Boot report verdicts
Every boot self-checks and writes a report: the verdict on the Overview, the full text under Services there, a DM to the owner when pipe is on.
| all green | nothing to do |
| green with N warning(s) | the warnings name what to look at: a disk filling, a stale update origin, wake-on-LAN not armed. Known-good is still promoted |
| recovered (N fix(es) applied) | the check put something right; the report says what |
| DEGRADED: N critical | something the box needs is down or missing and it could not fix it; each critical line names the thing. Known-good is not promoted |
went down: says how the last run ended: clean shutdown; power loss / hard reset; watchdog or power loss when the dog was armed and cannot tell; kernel panic: the watchdog rebooted us when a panic record exists. this boot is a self-applied image update means the hourly update flashed and rebooted. chassis mismatch with vault is LOCKED means the stick is in a different box than it was claimed in; type the recovery phrase under Secrets. The hourly live check writes the same shape of verdict while the box is up.
Repair remote access
System → Maintenance → Repair remote access puts /root/.ssh/authorized_keys back from the copy on /data if it vanished or is empty, restarts sshd, and saves so the key does not vanish again at the next boot. It says what it did.
The two reboots
| Reboot the box | the last saved state comes back, and only that; anything not saved is gone. Back in about a minute |
| Reboot into BIOS | straight into firmware setup, for the two switches on hardware notes. Plug in a keyboard and a screen first |
The watchdog and power loss
If the box hangs, the hardware watchdog resets it within a minute and the next report says so. If the mains went, the report says power loss, /data recovers from its journal, and at most an hour of logs is missing. If it keeps happening, the Logs picker under System (selfcheck first) shows the pattern. With After Power Loss set to Power On a Machine comes back by itself; otherwise a sibling can Wake it.
Common ones
| not at pipeos.local | give it two minutes; check mDNS (ping pipeos.local), or find the address in the router's DHCP table and open http://<ip>/. Networking |
| does not boot | UEFI on, Secure Boot off. Two pipeOS sticks attached is a coin toss; remove one |
| Claude not answering | Setup shows the sign-in pill. A locked vault is unlocked under Secrets; a paused cap is named under Usage |
| a job says waiting | it needs a secret it does not have; the ask is under Secrets → Share requests on the holder |
| pipeos status says NEW IMAGE APPLIED | a flash is waiting for the reboot; saves are fenced until then. Reboot |
| a stick died, or a flash lost power | recovery: the generic image on a fresh stick, then Restore identity |
Stuck beyond that: flip vendor support access on and tell your vendor, or open an issue with the boot report text.