Operations agent: chat-driven infrastructure control with confirm-on-write
A local AI assistant that performs homelab and media-pipeline operations for a single admin, behind a confirmation framework.
AI-agent solutions Governance Auditability Systems operations Admin gating Tool design
This page covers the homelab operations layer I built into the HAI orchestrator (the local AI assistant). The assistant performs infrastructure and media-library tasks through chat. It runs as a container beside the services it operates and reaches their APIs directly, with no shell in that path. Everything is live in the lab, admin-gated, and every write requires my explicit approval.
The confirmation framework, built first
The keystone was a confirmation framework, built before any write tool existed. The design is simple: every write-capable tool returns a preview and an action token. Nothing executes until a follow-up call with that token confirms the exact change that was previewed, and the web UI surfaces pending confirmations so I can approve or deny from a browser.
Because every write inherits this behavior, a new write tool gets the confirmation step by construction. A single-admin homelab does not need a policy engine; the approval click is the safety control. An append-only audit file records every preview, confirmation, and denial as a JSON line, each carrying a risk level, so any change can be reconstructed after the fact. The preview itself shows a warning banner for medium- and high-risk actions.
The foundations were built in this order. First, a generic HTTP client for the media-management apps' APIs: base URL, key configuration, the standard methods, and the submit-then-poll pattern their command endpoints use. I then moved secrets out of config at deploy time so they are never exposed in chat or the retrieval index. I split the write-capable client layer from read-only access and put the confirmation framework on top, and admin gating and audit logging came next. Each module carries wiring tests that check the tool is correctly registered, plus behavioral tests against mocked clients, the same pattern as the assistant's other tool modules.
What the assistant can do
Simple one-shot actions run on the quick 8-9B tier with tools. Complex multi-step flows (search, select, import, verify) escalate to the 27B tier.
| Capability | Access |
|---|---|
| Series lookup and indexer search | Read-only |
| Download-client listing | Read-only |
| List candidate releases for a series or season, with metadata including audio languages | Read-only |
| Search-and-fetch a release | Preview, then confirm |
| Fetch one specific release by its identifier | Preview, then confirm |
| Pause, resume, recheck on the download client | Preview, then confirm |
| Add a release with a required category; defaults to paused | Preview, then confirm |
What it cannot do
I explicitly excluded these from exposure:
- Destructive download-client actions (remove, delete).
- Automatic release grabbing.
- Manual import.
- Media probing.
The media stack page covers the services being operated and the request-and-fulfillment workflow they support.
Constraints I set
- No general unsandboxed shell. An always-on, LAN-reachable chat model does not get a root shell. Structured tools provide the needed outcomes without that risk, and "inspect anything" flexibility is out of scope.
- Build in phases, accept the schedule cost. Contained client modules and the confirmation keystone keep phases additive, with pauses between them.
I left proactive push notifications out deliberately, because an existing update notifier already covers that ground.
Host administration, behind the same gate
The same preview-and-confirm gate reaches past the media stack. A separate admin-only capability lets the assistant run commands on registered hosts over SSH: read commands are ungated, and any host-changing command goes through the identical confirm step, risk-flagged and audited. It runs through the orchestrator's hostops broker, where the broker and its self-deploy machinery are described in full. This is the one place the no-shell rule is relaxed, and it is relaxed behind the confirm click, not around it.
The host-administration extension has been exercised only on routine tasks so far, kept deliberately narrow because broadening a host-mutating path is exactly the kind of change the confirm-on-write design exists to gate. The rules the assistant works under are on the rulebook page.