138 lines
5.5 KiB
Markdown
138 lines
5.5 KiB
Markdown
# Paseo — Agent Orchestration on the Home Lab
|
|
|
|
**Multi-agent orchestration GUI (Paseo 0.7.2) self-hosted in Docker on `.13`, driving real pi
|
|
coding agents (0.82.1) through OmniRoute.**
|
|
|
|
> Maintained by Sam · Gitea — [sam/paseo](https://gitea.lab.audasmedia.com.au/sam/paseo) ·
|
|
> interactive map: [maps.lab → Paseo](https://maps.lab.audasmedia.com.au/paseo/docs/system-map.html)
|
|
|
|
---
|
|
|
|
## What it is
|
|
|
|
[Paseo](https://github.com/getpaseo/paseo) is a client-server orchestration layer for AI coding
|
|
agents: one **daemon** manages agent processes and streams their output to desktop, CLI, mobile and
|
|
web clients. On this lab it runs **inside Docker on the always-on host `.13`**, with **pi** (the
|
|
coding agent) baked into the image and LLM traffic routed through the existing **OmniRoute** proxy
|
|
on `.13:20129`.
|
|
|
|
- **Local-first** — agents run on our machines/dev environment; no telemetry.
|
|
- **Pi is a first-class provider** — the daemon spawns `pi --mode rpc` (pi 0.82.1, no Nix changes).
|
|
- **One console** — `paseo ls` / `attach` / `logs` from anywhere: `.27`, `.51`, mobile, web UI.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph CLIENTS["Clients"]
|
|
D27[".27 desktop<br/>paseo CLI"]
|
|
D51[".51 laptop<br/>paseo CLI"]
|
|
M["Mobile / web UI<br/>browser"]
|
|
end
|
|
subgraph S13["Paseo daemon (.13 — Docker, always-on)"]
|
|
D["Paseo daemon 0.7.2<br/>:6767 · auth"]
|
|
PI["pi agent 0.82.1<br/>pi --mode rpc<br/>@earendil pi + omni ext"]
|
|
CFG["pi config<br/>/home/paseo/.pi"]
|
|
W["workspaces<br/>/workspace/demo"]
|
|
PWD["PASEO_PASSWORD<br/>.env (600)"]
|
|
end
|
|
subgraph LLM["LLM routing"]
|
|
OR["OmniRoute<br/>.13:20129"]
|
|
OP["OpenCode-Go /<br/>OpenRouter / DeepSeek / Gemini"]
|
|
end
|
|
D27 -->|"PASEO_HOST + password"| D
|
|
D51 -->|"PASEO_HOST + password"| D
|
|
M -->|"https :6767"| D
|
|
D -->|"spawns / manages"| PI
|
|
PI -->|"reads settings + models"| CFG
|
|
PI -->|"works in"| W
|
|
D -->|"protects"| PWD
|
|
PI -->|"httpx /v1 (omni provider)"| OR
|
|
OR -->|"combo routing"| OP
|
|
```
|
|
|
|
## Directory map
|
|
|
|
```
|
|
paseo/
|
|
├── README.md ← this file
|
|
└── docs/
|
|
├── system.mmd ← Mermaid source (single source of truth)
|
|
├── system.architecture.json ← Archify source
|
|
├── system-map.html ← interactive Archify map
|
|
└── diagrams/
|
|
├── system.png
|
|
└── system.svg
|
|
```
|
|
|
|
## Quick start (client)
|
|
|
|
```bash
|
|
# .27 / .51 (one-time)
|
|
npm install -g @getpaseo/cli@0.7.2
|
|
|
|
export PASEO_HOST=192.168.20.13:6767
|
|
export PASEO_PASSWORD=<from .13: /home/sam/Docker/Containers/paseo/.env>
|
|
|
|
paseo status # daemon reachable?
|
|
paseo ls # running agents
|
|
paseo run --provider pi --model omni/openrouter/qwen/qwen3.7-flash \
|
|
--cwd /workspace/demo "describe this workspace"
|
|
paseo logs <agent-id> # full activity timeline
|
|
```
|
|
|
|
Web UI: `http://192.168.20.13:6767` (password). Mobile: browser over LAN/Tailscale.
|
|
|
|
## Deployment (server, `.13`)
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Compose dir | `/home/sam/Docker/Containers/paseo/` |
|
|
| Image | `ghcr.io/getpaseo/paseo:latest` + custom stage |
|
|
| Daemon | 0.7.2 · `restart: always` · :6767 |
|
|
| pi | `@earendil-works/pi-coding-agent@0.82.1` (baked, `--mode rpc`) |
|
|
| Extensions | `omniroute-pi-ext-integration` (baked) |
|
|
| Config | `./paseo-home:/home/paseo` (persists pi + paseo config) |
|
|
| Workspace | `./workspace:/workspace` (agent project area) |
|
|
| LLM | pi → omni provider → `http://192.168.20.13:20129/v1` (OmniRoute) |
|
|
| Secrets | `.env` (chmod 600) — `PASEO_PASSWORD`, `OMNIROUTE_API_KEY` |
|
|
|
|
**Build note:** base image runs as user `paseo` (uid 1000) with root-owned `/usr/local` — so pi and
|
|
the extension are installed at **build time** under `USER root` in the Dockerfile, then dropped back
|
|
to `USER paseo` for runtime.
|
|
|
|
## Verified end-to-end (2026-09-09)
|
|
|
|
```
|
|
$ paseo run --provider pi --model omni/openrouter/qwen/qwen3.7-flash \
|
|
--cwd /workspace/demo --title paseo-demo --background \
|
|
"List files, read HELLO.txt, write DEMO_SUMMARY.md"
|
|
|
|
AGENT ID 560ffca0-… STATUS running PROVIDER pi CWD /workspace/demo
|
|
↓
|
|
AGENT ID 560ffca0-… STATUS idle PROVIDER pi/omni/openrouter/qwen/qwen3.7-flash
|
|
↓ → wrote ./workspace/demo/DEMO_SUMMARY.md (correct content)
|
|
↓ → `paseo logs` shows full timeline (user → thought → shell → read)
|
|
↓ → web UI :6767 → HTTP 200
|
|
```
|
|
|
|
## Known findings
|
|
|
|
- **OmniRoute combo regression:** the default `default-opencode-go-ds-flash` combo currently returns
|
|
`400 missing x-opencode-session` (OpenCode-Go leg) — affects host pi too, not just the container.
|
|
Working legs verified: `openrouter/qwen/qwen3.7-flash`, `openrouter/openai/gpt-5.6-sol`,
|
|
`aug/claude-haiku-4.5`. Fix the combo/credentials on OmniRoute to restore the default path.
|
|
- Paseo is pre-1.0 (0.7.2) — pin the version; expect breaking changes between releases.
|
|
- CLI runtime install on `.27` carries 3 low/medium CVEs in transitive deps (`qs`, `uuid`,
|
|
`@ai-sdk/provider-utils`) — vet/npq scanned clean, author verified.
|
|
|
|
## Why it matters
|
|
|
|
- **Proof the stack composes:** Nix pi binary stays untouched; the lab's OmniRoute routing powers a
|
|
third-party orchestrator; one always-on Docker host (.13) gives fleet control from any device.
|
|
- **A pattern for multi-agent work:** workspaces + `pi --mode rpc` + OmniRoute is a base for
|
|
coordinating several pi agents on real projects — exactly the coordination layer the lab needs.
|
|
|
|
---
|
|
|
|
*Documentation project — no proprietary code. Secrets never appear in this repo.* |