docs: a setup guide for people who are not us - #15
Conversation
v2 locked the agent down and made it meaningfully harder to reach. The address changed scheme, every browser now throws a full-page security warning, and nothing works until you find a token file you were never told existed. The README explains the system. It does not walk anyone through that. START-HERE.md does, in plain language: install, get past the warning and why the warning is correct-but-wrong-here, find the token, reach it from a phone, and the errors people will actually hit, quoted the way the screen words them. It is also honest about the three things that currently look broken and are not. The Machines page reads zero because self-signed peers fail verification silently and because each install generates its own token while the login box asks for a shared one. And a Windows installer upgrade orphans the database (#14), which is called out before the upgrade step rather than after. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c238e8234e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| | Your setup | What to download | What to do | | ||
| |---|---|---| | ||
| | **Windows, normal** | `HumWatch-Setup-v2.0.2.exe` | Double-click it. Click Yes when Windows asks for permission. | | ||
| | **Windows, no installer** | `HumWatch-v2.0.2.zip` | Unzip it anywhere. Run `setup.bat`, then `run.bat`. | |
There was a problem hiding this comment.
For the Windows ZIP path, setup.bat defaults to installing the background service (setup.bat:155-180), and the service installer starts it before returning (installer/service-setup.ps1:663-689). Telling the user to run run.bat immediately afterward therefore launches another HumWatch process on port 9100, which exits with an address-in-use error. Direct users to open the dashboard after the default service installation, and reserve run.bat for users who explicitly decline the service.
Useful? React with 👍 / 👎.
| | **Windows, normal** | `HumWatch-Setup-v2.0.2.exe` | Double-click it. Click Yes when Windows asks for permission. | | ||
| | **Windows, no installer** | `HumWatch-v2.0.2.zip` | Unzip it anywhere. Run `setup.bat`, then `run.bat`. | | ||
| | **Debian or Ubuntu Linux** | `humwatch_2.0.2_amd64.deb` | `sudo apt install ./humwatch_2.0.2_amd64.deb` | | ||
| | **Other Linux** | `HumWatch-v2.0.2-linux.tar.gz` | Unpack it. Run `./setup.sh`, then `./run.sh`. | |
There was a problem hiding this comment.
Following this exact non-root Linux flow only creates a checkout-local virtual environment (setup.sh:21-27) and makes run.sh select its development profile, whose token is under .humwatch and whose listener is forced to 127.0.0.1 (run.sh:18-31,54-57). It neither installs an auto-starting service nor permits the phone/other-computer flow described below, and the documented /etc/humwatch/auth-token will not exist. Either document the root provisioning and systemd steps for this download or identify it as a local-only foreground development mode.
Useful? React with 👍 / 👎.
|
|
||
| A self-hosted, local-first hardware monitoring system for Windows and Linux PCs. | ||
|
|
||
| > **New here? Read [Start Here](docs/START-HERE.md) instead of this file.** |
There was a problem hiding this comment.
The new primary link works in the GitHub checkout but is broken in every packaged copy of this README: scripts/build-release.ps1 stages only agent, static, scripts, and installer; scripts/build-linux-portable.sh likewise omits docs; and scripts/build-installer.ps1 stages the README without the docs directory. Users opening the README delivered by the ZIP, Linux tarball, or installer therefore cannot reach docs/START-HERE.md; stage that file in each artifact or use an absolute GitHub link.
Useful? React with 👍 / 👎.
A new user never saw the old version, so telling them what the address used to be, what changed, and which release changed it is trivia they have to read past to reach the instruction. Every "this used to be X" is now just X. The Windows backup warning stays, reframed. It is not history, it is an action someone takes now that loses their data if they take it in the wrong order. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 692c95a2f1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| HumWatch has a **Machines** page meant to show every computer you are running it on, side by side. | ||
|
|
||
| **Fair warning: this probably shows zero right now.** Two reasons, and both are fixable. |
There was a problem hiding this comment.
For manually added machines, the dashboard fetches the peer directly from the browser (static/js/pages/machines.js:234-243), while cors_origins defaults to an empty list and the server permits only explicitly listed origins (agent/main.py:149-156). Matching tokens and trusted certificates therefore still leave these cards unable to load across origins. Add the README's cors_origins/HUMWATCH_CORS_ORIGINS step rather than describing tokens and certificates as the only two blockers.
Useful? React with 👍 / 👎.
| Or paste this into PowerShell: | ||
|
|
||
| ```powershell | ||
| Get-Content C:\ProgramData\HumWatch\auth-token | ||
| ``` |
There was a problem hiding this comment.
When the Windows installer or service setup path was used, provisioning removes ordinary Users and Authenticated Users from the runtime tree and grants access only to SYSTEM and Administrators (scripts/provision-security.ps1:74-109). A normal PowerShell window therefore returns Access Denied for this suggested command, even though it is presented as the easy alternative to elevated Notepad; explicitly require an Administrator PowerShell session here.
Useful? React with 👍 / 👎.
|
|
||
| Paste it into the box on the page and click **Retry**. | ||
|
|
||
| That is it. You are in. Your browser remembers the token, so you will not have to do this again on that browser. |
There was a problem hiding this comment.
The dashboard stores the token in window.sessionStorage (static/js/auth.js:14-27), not persistent browser storage. After the user closes the relevant tab/window and later returns, the token prompt can appear again, so promising they will never need the token again on that browser leaves them without the credential they were told they could forget; describe this as browser-session persistence instead.
Useful? React with 👍 / 👎.
|
Parking this rather than polishing docs for a flow the 2.1 fleet hub plan (#17) deletes. Nobody is on the 2.0 setup path right now. The getting-started content gets rewritten against owner login and enrollment at the end of the 2.1 task sequence. Branch kept for salvage. |
1 participant
Jeff got lost reaching his own dashboard after the v2 rollout. If the person who wrote it is lost, everyone else is worse off.
The problem
v2 locked the agent down, and three things changed that all look like breakage:
http://bookmark is now dead with no redirect and no explanation.The README documents the system accurately. It does not walk anyone through any of that.
What this adds
docs/START-HERE.md, written for someone with no background. Install by platform, get past the warning (including why the warning fires and why it is safe to click through here specifically), find the token, reach it from a phone, and keep it updated.The troubleshooting section quotes errors the way the screen words them, not the way we would describe them, so people can match on the string they are staring at.
It is honest about what looks broken
Three things currently read as failure and are not, so the guide names them rather than letting people think they broke it:
README
Adds a pointer at the top and above Installation. A guide nobody links to is a guide nobody reads.
Worth a second opinion
🤖 Generated with Claude Code