hutson/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto-sync: 20260107-000953

Browse Source
This commit is contained in:
Hutson
2026-01-07 00:09:54 -05:00
parent 7eacc846e6
commit 5ac698db0d
3 changed files with 353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
IP-ASSIGNMENTS.md
View File

@@ -72,6 +72,7 @@ This document tracks all IP addresses in the homelab infrastructure.
| Excalidraw | excalidraw.htsn.io | 10.10.10.206:8080 | Traefik-Primary |
| MetaMCP | metamcp.htsn.io | 10.10.10.207:12008 | Traefik-Primary |
| n8n | n8n.htsn.io | 10.10.10.207:5678 | Traefik-Primary |
| PA API | pa.htsn.io | 10.10.10.207:8401 | Traefik-Primary (Tailscale only) |
| Crafty Controller | mc.htsn.io | 10.10.10.207:8443 | Traefik-Primary |
| Plex | plex.htsn.io | 10.10.10.100:32400 | Traefik-Saltbox |
| Sonarr | sonarr.htsn.io | 10.10.10.100:8989 | Traefik-Saltbox |
@@ -132,6 +133,7 @@ This document tracks all IP addresses in the homelab infrastructure.
| Service | Port | Purpose |
|---------|------|---------|
| PA API | 8401 | Personal Assistant API (pa.htsn.io) - Tailscale only |
| MetaMCP | 12008 | MCP Aggregator/Gateway (metamcp.htsn.io) |
| n8n | 5678 | Workflow automation |
| Crafty Controller | 8443 | Minecraft server management (mc.htsn.io) |
@@ -149,6 +151,16 @@ This document tracks all IP addresses in the homelab infrastructure.
| Android Phone | 10.10.10.54 | 8384 | Xxz3jDT4akUJe6psfwZsbZwG2LhfZuDM |
| TrueNAS | 10.10.10.200 | 8384 | (check TrueNAS config) |
## Mac Mini Services (10.10.10.125)
| Service | Port | Purpose |
|---------|------|---------|
| MCP Bridge | 8400 | HTTP bridge for MCP tool execution (PA API backend) |
| Beeper Desktop | 23373 | Message aggregation (Telegram, iMessage, SMS) |
| Proton Bridge IMAP | 1143 | Personal email access |
| Proton Bridge SMTP | 1025 | Personal email sending |
| Syncthing | 8384 | File sync API |
## Notes
- **MTU 9000** (jumbo frames) enabled on storage networks

339
PA-API.md Normal file
View File

@@ -0,0 +1,339 @@
# Personal Assistant API
Backend API for the Personal Assistant system - provides Claude-powered voice/text interface to all PA capabilities (calendar, tasks, messages, smart home, etc.).
---
## Quick Reference
| Setting | Value |
|---------|-------|
| **Domain** | pa.htsn.io |
| **Local IP** | 10.10.10.207:8401 |
| **Server** | docker-host2 (PVE2 VMID 302) |
| **Compose** | `/opt/pa-api/docker-compose.yml` |
| **Access** | Tailscale only (not publicly exposed) |
| **GitHub** | Private repo: `pa-api` |
---
## Architecture
```
Android/Telegram
│
▼
┌─────────────────┐
│ PA API │ ← Claude SDK, model routing
│ docker-host2 │
│ :8401 │
└────────┬────────┘
│
┌────┴────┐
│ │
▼ ▼
┌───────┐ ┌──────────┐
│ Rube │ │MCP Bridge│ ← Mac Mini (Beeper, Proton, etc.)
│ Exa │ │ :8400 │
│ etc. │ └──────────┘
└───────┘
```
**PA API handles:**
- Claude SDK integration (no CLI startup delay)
- Model routing (Haiku/Sonnet/Opus)
- Session management
- Direct API tools (Exa, Ref, Rube, Airtable)
**MCP Bridge handles:**
- Tools requiring Mac Mini (Beeper, Proton Bridge, filesystem)
- Runs on Mac Mini at 10.10.10.125:8400
---
## API Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/chat` | POST | Main query endpoint (streaming SSE) |
| `/health` | GET | Health check |
### POST /chat
**Request:**
```json
{
"message": "What's on my calendar today?",
"session_id": "abc123"
}
```
**Response (Server-Sent Events):**
```
data: {"type": "model", "name": "sonnet"}
data: {"type": "chunk", "text": "You have "}
data: {"type": "chunk", "text": "3 meetings today..."}
data: {"type": "done", "full_text": "You have 3 meetings today..."}
```
### Model Routing
| Query Type | Model | Examples |
|------------|-------|----------|
| Simple facts | Haiku | "How old is X?", "What's 15% of 80?" |
| PA queries | Sonnet | "What's on my calendar?", "Add task" |
| Complex reasoning | Opus | "Help me plan my week" |
**Override:** Say "Use Opus" to force model selection (sticky per session).
---
## Deployment
### Docker Compose
Location: `/opt/pa-api/docker-compose.yml`
```yaml
version: '3.8'
services:
pa-api:
image: pa-api:latest
build: .
container_name: pa-api
restart: unless-stopped
ports:
- "8401:8401"
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
- MCP_BRIDGE_URL=http://10.10.10.125:8400
- EXA_API_KEY=${EXA_API_KEY}
# Add other API keys as needed
volumes:
- ./data:/app/data
networks:
- pa-network
networks:
pa-network:
driver: bridge
```
### Environment Variables
| Variable | Purpose |
|----------|---------|
| `ANTHROPIC_API_KEY` | Claude API access |
| `MCP_BRIDGE_URL` | Mac Mini bridge endpoint |
| `EXA_API_KEY` | Exa web search |
| `AIRTABLE_API_KEY` | Airtable access |
Store in `/opt/pa-api/.env` (not committed to git).
---
## Traefik Configuration
File: `/etc/traefik/conf.d/pa-api.yaml` (on CT 202)
```yaml
http:
routers:
pa-api:
rule: "Host(`pa.htsn.io`)"
entryPoints:
- websecure
service: pa-api
tls:
certResolver: cloudflare
services:
pa-api:
loadBalancer:
servers:
- url: "http://10.10.10.207:8401"
```
**Note:** This service is Tailscale-only. The Traefik route exists for convenience but should not be exposed publicly via Cloudflare.
---
## Common Tasks
### Start/Stop Service
```bash
# SSH to docker-host2
ssh docker-host2
# Start
cd /opt/pa-api && docker-compose up -d
# Stop
cd /opt/pa-api && docker-compose down
# View logs
docker logs -f pa-api
# Restart
docker-compose restart pa-api
```
### Update Service
```bash
ssh docker-host2
cd /opt/pa-api
git pull
docker-compose build
docker-compose up -d
```
### Health Check
```bash
# From any machine on network
curl http://10.10.10.207:8401/health
# Test chat endpoint
curl -X POST http://10.10.10.207:8401/chat \
-H "Content-Type: application/json" \
-d '{"message": "Hello", "session_id": "test"}'
```
---
## MCP Bridge (Mac Mini)
The MCP Bridge runs on Mac Mini and exposes MCP tools as HTTP endpoints.
| Setting | Value |
|---------|-------|
| **Location** | Mac Mini (10.10.10.125) |
| **Port** | 8400 |
| **Purpose** | Execute MCP tools (Beeper, Proton, TickTick, HA, etc.) |
### Bridge Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/tools` | GET | List available tools |
| `/execute` | POST | Execute a tool |
| `/health` | GET | Health check |
### Start MCP Bridge
```bash
# SSH to Mac Mini
ssh macmini
# Start bridge (managed by launchd)
launchctl load ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist
# Check status
curl http://localhost:8400/health
```
---
## Integration Points
### Related Services
| Service | Relationship |
|---------|--------------|
| n8n | Telegram bot uses n8n → Claude CLI (separate path) |
| MetaMCP | PA API does NOT use MetaMCP (direct MCP Bridge) |
| Home Assistant | Controlled via MCP Bridge |
| Claude-Mem | Shared memory database for context |
### Clients
| Client | Connection |
|--------|------------|
| Android App | HTTPS via Tailscale → pa.htsn.io |
| (Future) Web UI | Same endpoint |
---
## Monitoring
### Health Checks
```bash
# PA API
curl -s http://10.10.10.207:8401/health | jq
# MCP Bridge
curl -s http://10.10.10.125:8400/health | jq
```
### Logs
```bash
# PA API logs
ssh docker-host2 'docker logs -f pa-api --tail 100'
# MCP Bridge logs (Mac Mini)
ssh macmini 'tail -f ~/Library/Logs/mcp-bridge.log'
```
---
## Troubleshooting
### PA API Not Responding
1. Check container status:
```bash
ssh docker-host2 'docker ps | grep pa-api'
```
2. Check logs for errors:
```bash
ssh docker-host2 'docker logs pa-api --tail 50'
```
3. Verify network:
```bash
curl http://10.10.10.207:8401/health
```
### MCP Bridge Not Responding
1. Check if Mac Mini is reachable:
```bash
ping 10.10.10.125
```
2. Check bridge process:
```bash
ssh macmini 'pgrep -f mcp-bridge'
```
3. Restart bridge:
```bash
ssh macmini 'launchctl unload ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist'
ssh macmini 'launchctl load ~/Library/LaunchAgents/com.hutson.mcp-bridge.plist'
```
### Model Routing Issues
- Check Claude API key is valid
- Verify Haiku classifier is responding
- Check session storage for stuck model overrides
---
## Related Documentation
- [IP-ASSIGNMENTS.md](IP-ASSIGNMENTS.md) - Service IP mapping
- [VMS.md](VMS.md) - docker-host2 VM details
- [TRAEFIK.md](TRAEFIK.md) - Reverse proxy configuration
- [Personal Assistant Project](~/Projects/personal-assistant/CLAUDE.md) - PA system overview
- [Services Matrix](~/Projects/personal-assistant/docs/services-matrix.md) - All MCP tools
---
**Last Updated**: 2026-01-07

2
README.md
View File

@@ -33,6 +33,7 @@ Documentation for Hutson's home infrastructure - two Proxmox servers running VMs
| [SERVICES.md](SERVICES.md) | Complete service inventory with URLs and credentials |
| [TRAEFIK.md](TRAEFIK.md) | Reverse proxy setup, adding services, SSL certificates |
| [HOMEASSISTANT.md](HOMEASSISTANT.md) | Home Assistant API, automations, integrations |
| [PA-API.md](PA-API.md) | Personal Assistant API, MCP Bridge, Claude integration |
| [SYNCTHING.md](SYNCTHING.md) | File sync across all devices, API access, troubleshooting |
| [SALTBOX.md](#) | Media automation stack (Plex, *arr apps) (coming soon) |
@@ -83,6 +84,7 @@ Documentation for Hutson's home infrastructure - two Proxmox servers running VMs
| **Plex** | Saltbox VM | https://plex.htsn.io |
| **Home Assistant** | VM 110 | https://homeassistant.htsn.io |
| **Gitea** | VM 300 | https://git.htsn.io |
| **PA API** | docker-host2 | https://pa.htsn.io (Tailscale) |
| **Pi-hole** | CT 200 | http://10.10.10.10/admin |
| **Traefik** | CT 202 | http://10.10.10.250:8080 |