Hardware awareness for small infrastructure environments.
Experimental • Home Lab Tool • Quiet Infrastructure
Harry is a lightweight hardware awareness layer for small multi-node environments.
It exists because a thing happened:
I was no longer managing infrastructure — I was remembering it.
Harry reduces cognitive overload by keeping a fleet visible, comparable, and contract-validated.
If it runs quietly for years, we’ve won. Boring is good.
Download the latest installer from this repository's Releases page.
Run:
HarryBrainSetup.exe
The installer will:
• install Harry Brain
• install the local Agent
• configure services
• open firewall ports as needed
• start everything automatically
• open the dashboard
Then open:
Your machine will automatically register as the first node.
If you need the discovery-aware Windows installer downloads directly from the Downloads page, use the Brain or Agent installer links and let them find Harry Brain automatically.
Advanced: if you want to rebuild the Windows installer EXEs themselves, run:
pwsh -File scripts/build-windows-installer.ps1
pwsh -File scripts/build-windows-brain-installer.ps1
That script expects Inno Setup 6 (ISCC.exe) to be available.
That refreshes the packaged Windows artifacts and writes:
downloads/HarryAgentSetup.exe
downloads/HarryAgentSetup.manifest.json
downloads/HarryBrainSetup.exe
downloads/HarryBrainSetup.manifest.json
To verify the installer path:
downloads/HarryAgentSetup.exe
downloads/HarryBrainSetup.exe
The installers reflect Brain 2026.08.12, Agent 0.3.2, and Schema 0.2.3.
Harry’s stable Windows installer artifacts are committed in downloads/, so a normal git pull or sudo /opt/harry/scripts/update-harry.sh refreshes them with the repo.
For an optional manual build-and-copy flow:
pwsh -File scripts/release-windows-installer.ps1 -TargetHost <brain-host> -TargetUser <ssh-user>
For optional manual copy:
scp downloads\HarryAgentSetup.exe <ssh-user>@<brain-host>:/opt/harry/downloads/
scp downloads\HarryAgentSetup.manifest.json <ssh-user>@<brain-host>:/opt/harry/downloads/
scp downloads\HarryBrainSetup.exe <ssh-user>@<brain-host>:/opt/harry/downloads/
scp downloads\HarryBrainSetup.manifest.json <ssh-user>@<brain-host>:/opt/harry/downloads/
On the Brain, verify the artifact and served download:
cat /opt/harry/downloads/HarryAgentSetup.manifest.json
cat /opt/harry/downloads/HarryBrainSetup.manifest.json
curl -o /tmp/HarryAgentSetup.exe http://127.0.0.1:8789/downloads/windows-agent
curl -o /tmp/HarryBrainSetup.exe http://127.0.0.1:8789/downloads/windows-brain
Notes:
HarryAgentSetup.exe and HarryBrainSetup.exe are generated, but committed here as the latest stable artifacts.
The manifests prevent stale installers from being served silently.
The build step requires Inno Setup 6 and ISCC.exe on PATH or installed in the default location.
The deploy helper is optional for manual copies, not required for normal updates.
Windows install logs are written to:
C:\ProgramData\Harry\logs\HarryAgent.install.log
C:\ProgramData\Harry\logs\HarryAgent.runtime.log
C:\ProgramData\Harry\logs\HarryAgentService.wrapper.log
C:\ProgramData\Harry\logs\HarryAgentService.out.log
C:\ProgramData\Harry\logs\HarryAgentService.err.log
C:\ProgramData\Harry\diagnose.ps1
During install, the Windows wizard lets you choose automatic discovery or a manual Brain address. After install, the Windows agent validates its first telemetry send automatically. For local diagnostics on an installed machine:
C:\ProgramData\Harry\diagnose.ps1
C:\ProgramData\Harry\harry_agent.exe --diagnostics
C:\ProgramData\Harry\harry_agent.exe --send-once
C:\ProgramData\Harry\harry_agent.exe --once
If an install is interrupted, files are deleted manually, or Windows security software blocks the runtime, run:
pwsh -ExecutionPolicy Bypass -File scripts/windows/repair-harry-install.ps1
Pass -RemoveData only if you want to remove C:\ProgramData\Harry too.
Harry's current Windows installers are unsigned in this release line. Windows SmartScreen and antivirus tools may warn about or block unsigned installers that are not yet well known.
To stay safe:
• download installers only from the official GitHub Releases page
• use the SHA256 values published in the matching *.manifest.json files
• allow or quarantine only the specific Harry installer/runtime if you trust the source
• do not disable antivirus globally just to install Harry
The manifest files already include release checksums for the installer source and payloads, and future releases should also publish standalone release asset checksums from GitHub Actions.
Follow-up work:
• sign Windows installers • publish SHA256 checksums alongside each release asset • build reputation with Windows security vendors • avoid suspicious installer behavior where possible
git clone cd Harry ./install.sh
After install:
UI: http://localhost:8787 Health: http://localhost:8787/health Public agent address example: HARRY_PUBLIC_BASE_URL=http://:8789 Public agent LAN override: HARRY_BRAIN_LAN_IP= HARRY_PUBLIC_PORT=8789
When you want to refresh a local Brain checkout safely:
sudo /opt/harry/scripts/update-harry.sh
Optional alias:
alias update-harry='sudo /opt/harry/scripts/update-harry.sh'
Use the Downloads page.
It provides:
• discovery-aware installers • the correct Brain association • step-by-step onboarding
For a new secure enrolment, open Downloads → Add Machine, sign in with an enrolment-administrator credential, and copy/download the Linux or Windows bootstrap. This is the normal zero-SSH path for administrators.
Provision an enrolment-administrator credential once (the command runs inside the actual Brain container image and prints the secret once):
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py issue-admin ops
Use the same credential lifecycle commands for all long-lived credential
types. list returns safe metadata only, identifying api_read, agent, and
enrolment_admin entries without token material or hashes. Revoke any entry
by its metadata ID; revoking an enrolment_admin credential immediately
invalidates every Add Machine browser session derived from it:
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py list
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py revoke <credential-id>
The Add Machine UI issues only short-lived single-use hry_enrol_… tokens. It
does not expose a public token-minting API. If you need a CLI-only workflow,
the same documented Docker invocation can issue a token directly:
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py issue-enrolment forge
The command prints a short-lived hry_enrol_… token once. It is not the
Agent's permanent credential. Use it in one of the following bootstrap links.
curl -fsSL http://<brain-ip>:8789/install/<hry_enrol_token> | sudo bash
The installer receives the Brain address from the link, exchanges the token for a durable Agent-only credential, installs the Agent and independent systemd watchdog, then verifies first telemetry. No environment variables or Harry config editing are needed.
Enable SSH on the NAS, then run the Linux installer command from a shell:
sudo HARRY_PLATFORM="synology-dsm" curl -fsSL "http://<brain-ip>:8789/downloads/linux-agent" | bash
If DSM scheduling is needed, create a Control Panel > Task Scheduler > Create > Scheduled Task > User-defined script task, run it as the install owner (usually root when installed with sudo), and paste the command printed by the installer. Synology self-update is disabled by default for safety.
irm http://<brain-ip>:8789/install/<hry_enrol_token>/windows.ps1 | iex
This downloads the normal installer, enrols automatically, configures Windows
Service Recovery and the independent HarryAgentWatchdog scheduled task, then
verifies first telemetry. The regular Windows installer remains compatible
with existing and trusted-LAN Agents and can still discover a Brain without a
token during migration.
For a non-enrolled legacy install, the regular installer will still try Brain discovery before offering a manual address.
Harry consists of two components:
- Brain — central service that collects, stores, and visualises data
- Agent — lightweight process installed on each machine
Agents send hardware and health data to the Brain over HTTP.
The Brain provides a UI to:
• view your fleet
• compare hardware
• detect issues early
Fleet
• overview
• nodes
• trends
• hidden nodes
Inventory
• summary
• comparison table
• node details
Diagnostics
• summary
• recommendations
• statistics
Downloads
• installers
• Brain address
• onboarding steps
Harry Agents must reach the Brain over HTTP.
Default Brain listen port: 8789
Example public agent-facing address: HARRY_PUBLIC_BASE_URL=http://:8789 HARRY_BRAIN_LAN_IP= HARRY_PUBLIC_PORT=8789
Requirements:
• allow TCP port 8789 through firewall • ensure machines can reach the Brain
Different subnets?
• routing must be enabled
• firewall rules must allow traffic
Test connectivity (from the machine you're installing an Agent on):
Test-NetConnection -Port 8789
Agent cannot connect:
• check Brain is running
• open Brain URL from Agent machine
• ensure port 8789 is open
Node not appearing:
• wait ~30 seconds
• refresh Fleet page
Diagram (Mermaid):
flowchart LR
A[Nodes] --> B[Harry Agent] B --> C[Harry Brain]
C --> D[Snapshot Store (SQLite)] C --> E[Advice Engine] C --> F[Schema Distribution]
C --> G[Fleet Dashboard UI]
Brain:
• ingest validated snapshots
• compute node health
• store historical data
• expose UI and APIs
Agent:
Linux:
• bash + embedded Python
• systemd timer (5 min)
Windows:
• compiled executable
• WinSW service
UI: / Health: /health Version: /version Nodes: /nodes Doctor: /doctor /doctor.json
Agent: • /dist/harry_agent.sh • /scripts/install-agent.sh • /install/{enrolment-token}
/api/v1 is the stable, machine-consumer surface for Jarvis, Oracle and Home
Assistant. It is deliberately read-only: Harry observes and explains state;
it never becomes a remote-execution or orchestration service.
Issue a credential locally on the Brain (the token is printed once):
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py issue-api jarvis
Use it only as a bearer token:
curl -H "Authorization: Bearer hry_api_…" http://<brain-ip>:8789/api/v1/summary
List safe metadata for every credential kind (api_read, agent, and
enrolment_admin), then revoke any long-lived credential by its metadata ID.
The output never includes token material or hashes:
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py list
cd /opt/harry && docker compose exec -T harry-brain python /app/scripts/harry-credentials.py revoke <credential-id>
The first API version includes fleet, node, hardware, metrics, service, event, version and compact summary resources:
/api/v1/fleet, /api/v1/fleet/health, /api/v1/fleet/issues,
/api/v1/nodes, /api/v1/nodes/{node}, /api/v1/nodes/{node}/hardware,
/api/v1/nodes/{node}/metrics, /api/v1/nodes/{node}/services,
/api/v1/nodes/{node}/events, /api/v1/services, /api/v1/events,
/api/v1/versions, and /api/v1/summary.
Every response carries generation/observation provenance. Unknown values stay
null; stale snapshots are marked as stale rather than presented as current.
/api/v1/summary is intentionally compact enough to ground an AI response to
“Is everything okay with the servers?”
Linux uses a normal systemd Agent timer plus a separate
harry-agent-watchdog.timer. The watchdog checks stopped or damaged installs,
stale telemetry, Brain reachability and discovery; recovery actions are backed
off and recorded in /var/lib/harry-agent/recovery.json and
/var/log/harry-agent-recovery.log. The Agent's own logs and status are in
/opt/harry/agent/logs/harry-agent.log and
/opt/harry/agent/status/status.json.
Windows configures Service Recovery and runs HarryAgentWatchdog every five
minutes as LocalSystem. Its independently retained diagnostics are in
C:\ProgramData\Harry\logs\HarryAgent.recovery.log and
C:\ProgramData\Harry\recovery-state.json, alongside the existing install,
runtime and wrapper logs.
A recovery is only recorded as healthy after telemetry generated after the recovery action is accepted and the expected supervisor state is present. An enrolled watchdog can independently send its bounded attempt/failure events to Brain using its Agent identity when the main Agent is down; it can never report success. Brain records success only from the later authenticated telemetry.
The guarded recovery acceptance runbook defines the first production canary. Its Linux and Windows helpers perform read-only preflight unless their explicit recovery-test confirmation switch is supplied; they stop only the normal Agent supervisor and trigger the existing independent watchdog.
Existing Linux and Windows Agents continue to post to /ingest without an
Agent credential, and the legacy /nodes, /doctor.json, /api/services and
/api/events endpoints remain available. A normal upgrade to Agent 0.3.2
idempotently installs the Linux systemd watchdog or Windows service/watchdog
foundation; no manual reinstall is required. Windows repair refreshes the
Agent executable, WinSW wrapper, watchdog, updater and support files while
preserving agent_config.json. New enrolled Agents send their stored
agent_id with telemetry and Brain verifies it against their Agent-only
credential, so hostname changes do not change durable identity. Windows
protects that durable credential file to LocalSystem and local Administrators.
Windows Agent 0.3.2 checks Brain discovery once at startup and then at most
once every five minutes while its normal 30-second telemetry loop continues.
When a newer Agent is advertised, it downloads the current updater script to a
temporary path, validates the expected updater contract and PowerShell syntax,
then schedules exactly one updater process. A failed discovery or updater
refresh is logged safely and retried only on the normal bounded cadence.
Legacy unauthenticated Agents remain compatible during migration; enrol them
later if/when enforcing a credentialed fleet becomes desirable.
Deferred roadmap work: richer workload/service discovery, snapshot diffs, network topology, SMART intelligence, canonical machine identities, dependency mapping, capacity reasoning, Home Assistant events, Jarvis/MCP integration, and any write/orchestration APIs.
Harry exists to reduce cognitive load.
You shouldn’t need to remember your infrastructure.
You should be able to see it.
If it runs quietly for years — we’ve won.
Linux Agent: Stable
Windows Agent: Supported
Linux Brain: Stable
Windows Brain: Supported
• Agents only push data; Brain never SSHs into nodes
• Enrolment tokens are short-lived, single-use and exchanged for a durable
Agent-only credential
• /api/v1 requires revocable read-only integration credentials
• Token material is never included in Brain diagnostic APIs or normal logs
• Use HTTPS/reverse-proxy TLS before exposing Harry beyond a trusted network
If the system fades into the background and just quietly works — Harry has done its job.