---
Date: 2026-07-28
Author: Adolfo Reyna + Hermes
Tags: [paseo, centralized-agents, orchestration, home-infra, project]
---

# Paseo — Centralized Agents Across Home Fleet

## Goal
Centralized control plane for AI agents across all home computers, where Hermes (this agent) can orchestrate tasks to the best machine.

## Fleet (from 2026-07-13 inventory)
- **FamReynaServer .110** - 7.6Gi, Docker 17 containers, Caddy v2.10.2, main host, candidate for paseo-server
- **iMac .124** - 15Gi healthy, Node 22, Chrome reyna-bot :9222, BareBrowse/Default for heavy/browser tasks
- **Mac-mini-M4 .102** - macOS, MCP server 7331, Deco API, image gen, high traffic
- **aeropi5 Pi .126** - 3.9Gi 3.3Gi swap thrashing, Hermes dashboard :9119, cron orchestrator, should stay light
- **emiserver .119** - EMI API, SSH locked, ports 3000/3001/9000/2283 open

## Core Insight from User
> "paseo is the solution for centralized agents across my computers at home. Not only that, but also provides a way for you to help me orchestrate"

So paseo must:
1. Be the fabric where agents register from each machine
2. Let Hermes (me) dispatch/orchestrate work via tools

## Architecture

### Components
```
[paseo-server .110:7001] <- Caddy paseo.reynafamily.com
  FastAPI + SQLite + Bearer auth
  Tables: agents, tasks, heartbeats
  Endpoints: /agents/register, /agents/heartbeat, /agents/list, /tasks/create, /tasks/claim, /tasks/update, /tasks/list

[paseo-agent daemon] on each host (.110, .124, .102, .126)
  Python, lightweight (~20MB RAM)
  On start: detect capabilities -> register
  Loop: heartbeat 15s + poll for tasks
  Capabilities: { ram_gb, cpu, chrome_debug_port, mcp_tools[], gpu, python, node, docker, voicebox }

[Hermes skill: paseo]
  CLI: `paseo agents`, `paseo tasks`, `paseo dispatch --type chrome --payload ...`
  MCP-ish: list agents, create task assigned to best-fit, watch logs
  Used by me to route work: e.g., BareBrowse -> iMac .124, image gen -> Mac mini .102, light cron -> Pi .126
```

### Capability-based routing (MVP)
- `browser/chrome` -> .124 (15Gi, :9222)
- `image/codex/gemini` -> .102 (Mac mini M4)
- `heavy-llm/ollama` -> .110 (Ollama host) or .124
- `light/cron` -> .126 (Pi)
- `docker/build` -> .110
- `emi-api` -> .119

### Data Model (SQLite MVP)
- agents: id TEXT PK, hostname TEXT, ip TEXT, capabilities JSON, status TEXT, last_heartbeat ISO, created_at
- tasks: id TEXT PK, type TEXT, payload JSON, assigned_agent TEXT FK, status TEXT (pending/claimed/running/done/failed), created_by TEXT, result JSON, created_at, updated_at

### Security
- Bearer token from env PASEO_TOKEN (stored in ~/.config/paseo-token 0600)
- Caddy forward_auth via Authentik optional, but start with LAN-only + bearer
- No public write without token

### Hermes Orchestration Flow
1. User asks Hermes to do coding task requiring Chrome
2. Hermes calls `paseo dispatch`: creates task type=browser payload
3. paseo-server matches capability -> assigns to iMac .124 agent
4. iMac agent claims, runs BareBrowse flow, updates result
5. Hermes polls task, returns result to user

### Phases
- Phase 0: Repo scaffold + FastAPI server + agent + Hermes skill (this week)
- Phase 1: Deploy server on .110 via docker-compose or systemd, Caddy route paseo.reynafamily.com :7001
- Phase 2: Install agents on .124, .102, .126 via systemd user services
- Phase 3: Hermes skill integration: `delegate_task` wrapper that uses paseo to route
- Phase 4: Dashboard UI + logs streaming + kill/restart
- Phase 5: Extend to ESP32 fleet as executable endpoints (display, etc)

## Decisions Made
- Stack: Python FastAPI + SQLite (fastest to build, familiar, low RAM, same as Hermes scripts)
- Server host: .110 FamReynaServer (central, Caddy already, Docker)
- Agent: single python file daemon, no deps beyond requests + psutil
- Token: shared via ~/.config/paseo-token

## Next
- Scaffold ~/Projects/paseo
- Implement server MVP and agent MVP
- Create ~/.hermes/skills/paseo skill for Hermes use
- Test locally on Pi .126 first, then deploy to .110