Homelab Hand AI agents, MCP & API
AI chat and watchers, the MCP server for n8n and Claude, and the REST API.
AI agents
Homelab Hand can use a local language model to answer questions about your lab and to watch it for you. It works with any OpenAI-compatible endpoint that supports tool calling. Nothing is sent to a cloud service unless you point it at one.
Adding a provider
AI Agents → Providers → + Add provider:
| Provider | Base URL | Notes |
|---|---|---|
| Ollama | http://<host>:11434 | Use a tool-capable model: qwen2.5, llama3.1 or later, mistral-nemo… |
| LM Studio | http://<host>:1234 | Start the server (Developer tab) and enable serve on local network. |
| OpenAI-compatible | https://…/v1 | Optional API key. |
Detect lists the models the endpoint offers.
Chat
Ask about your infrastructure ("Which containers restarted today?", "Is anything low on disk?"). The model calls hub tools to read real data, and each tool call is shown under the reply. Pick an autonomy level per conversation.
Autonomy levels
| Level | Behaviour |
|---|---|
| observe | Read-only tools. Changes are only recommended. |
| approve | State-changing tool calls are queued in AI Agents → Approvals and raise ai.action_pending. A human approves or rejects each one. |
| act | The agent may restart, exec and so on by itself. It never removes containers or data. |
Watchers
Watchers run on a schedule (every N minutes) or on events (e.g. container.unhealthy, host.*). Each can be scoped to certain environments and a container name pattern, with its own instructions. The model ends every run with STATUS: OK|WARNING|CRITICAL, and anything but OK becomes an ai.finding alert.
Example watcher. Trigger container.unhealthy, autonomy approve, instructions: "Read the container's logs. If the cause looks transient, restart it; otherwise explain what a human should do."
Tools
| Read | Write (needs approve or act) |
|---|---|
list_hosts, list_containers, get_container_logs, inspect_container, get_host_updates, check_host_updates, get_proxmox_overview, get_synology_status, get_network_map, get_recent_events, send_notification |
container_action, exec_in_container, proxmox_guest_action, run_host_command (off by default; Settings → General) |
MCP server
The hub is also a Model Context Protocol server, so other AI tools can use the same hub tools. The endpoint is https://<hub>/mcp (Streamable HTTP, stateless JSON). Authenticate with Authorization: Bearer <API token>, created under Settings → API tokens.
- Read tokens only see read tools.
- Write tokens see all tools. Whether their calls run straight away or wait for approval is set under Settings → General → MCP autonomy.
n8n
In an AI Agent workflow, add an MCP Client Tool node with the endpoint above, transport HTTP Streamable, and Bearer auth.
LM Studio
{ "mcpServers": { "homelab-hand": { "url": "https://hub.example.com/mcp",
"headers": { "Authorization": "Bearer htk_..." } } } }Claude Code
claude mcp add --transport http homelab-hand https://hub.example.com/mcp --header "Authorization: Bearer htk_..."Behind Cloudflare Access, give MCP and n8n clients an Access service token (CF-Access-Client-Id / CF-Access-Client-Secret headers) rather than bypassing /mcp.
REST API
Everything the UI does goes through the REST API. Browse it interactively at /api/docs (OpenAPI). Authenticate with a session cookie or Authorization: Bearer <token>. Read tokens are read-only, and no token can manage users or other tokens.
| Method | Path | Does |
|---|---|---|
| GET | /api/containers | All environments with containers, stats, health and update status |
| POST | /api/hosts/{id}/containers/{name-or-id}/action | {"action": "restart"}: start, stop, restart, pause, unpause, kill, remove |
| POST | /api/hosts/{id}/containers/{cid}/exec | {"command": "…"} |
| POST | /api/hosts/{id}/image-updates/check | Check image updates |
| POST | /api/hosts/{id}/image-updates/apply | Update everything that has an update (returns a job) |
| PUT | /api/hosts/{id}/stacks/{name} | {"compose": "…", "env": "…"}: deploy a stack (returns a job) |
| POST | /api/hosts/{id}/stacks/{name}/{op} | up, down, restart, stop, start, pull |
| POST | /api/hosts/{id}/updates/check · /apply | OS package updates |
| GET | /api/jobs/{id} | Poll a long-running job (status, output) |
| GET | /api/uptime | Uptime monitors with status and uptime |
| GET | /api/integrations | Connected apps with their latest stats |
| GET | /api/netmap | Network map: nodes, edges, VLANs, traffic |
| GET | /api/events?severity=&event_type= | Event log (event_type accepts * wildcards) |
| POST | /api/events/ingest | Push your own alert through the hub's destinations |
curl -s -X POST https://hub.example.com/api/hosts/2/containers/sonarr/action \
-H "Authorization: Bearer htk_..." -H "Content-Type: application/json" -d '{"action":"restart"}'