226 lines
9.8 KiB
Markdown
226 lines
9.8 KiB
Markdown
---
|
|
created: 2026-09-09
|
|
modified: 2026-09-10
|
|
type: project
|
|
tags:
|
|
- ai
|
|
- ai-agents
|
|
- ai-resume
|
|
- paseo
|
|
- pi
|
|
- tool
|
|
- tools
|
|
aliases:
|
|
- Paseo Pi GUI Tool
|
|
- Paseo
|
|
---
|
|
|
|
# Paseo Pi GUI Tool
|
|
|
|
**Paseo 0.7.2 — multi-agent orchestration GUI**, self-hosted in **Docker on .13**, driving real
|
|
**pi agents (0.82.1)** through **OmniRoute**. Built 2026-09-09/10.
|
|
|
|
**Interactive map:** [maps.lab → Paseo](https://maps.lab.audasmedia.com.au/paseo/docs/system-map.html) ·
|
|
**Repo:** [sam/paseo](https://gitea.lab.audasmedia.com.au/sam/paseo) (public, README + diagram)
|
|
|
|
## What it is
|
|
|
|
A client-server **orchestration layer for AI coding agents**:
|
|
- **Daemon** (Node.js) runs on .13, spawns and manages agent processes, streams output over WebSocket.
|
|
- **Clients** — CLI (`paseo` on .27/.51), web UI (:6767), mobile — attach locally or over LAN/Tailscale.
|
|
- **Pi is a first-class provider**: the daemon spawns `pi --mode rpc` (pi 0.82.1 baked into the image — no Nix changes to any host pi).
|
|
- **Local-first**: agents run in our environment; no telemetry.
|
|
|
|
```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"]
|
|
CFG["pi config<br/>/home/paseo/.pi"]
|
|
W["workspaces<br/>/workspace/demo"]
|
|
end
|
|
subgraph LLM["LLM routing"]
|
|
OR["OmniRoute .13:20129"]
|
|
OP["OpenCode-Go / 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
|
|
PI -->|"omni provider /v1"| OR
|
|
OR -->|"combo routing"| OP
|
|
```
|
|
|
|
## How to use it
|
|
|
|
```bash
|
|
# client (on .27/.51 once)
|
|
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
|
|
paseo attach <agent-id> # live stream
|
|
```
|
|
|
|
Web UI: `http://192.168.20.13:6767` (password) · mobile: browser over LAN/Tailscale.
|
|
|
|
## Where things live
|
|
|
|
| Area | Location |
|
|
|---|---|
|
|
| Compose + config + secrets | `.13` `/home/sam/Docker/Containers/paseo/` (`docker-compose.yml`, `Dockerfile`, `.env` chmod 600) |
|
|
| pi config (persisted) | `.13` `…/paseo/paseo-home/.pi/` (settings.json, models.json, auth.json) |
|
|
| Demo workspace | `.13` `…/paseo/workspace/demo/` |
|
|
| Docs + diagram + map | Gitea `sam/paseo` → `docs/` → maps.lab (`/paseo/docs/`) |
|
|
| Client CLI | `.27` `~/.local/share/npm-global` (`paseo` 0.7.2) |
|
|
|
|
## Config notes (no secrets)
|
|
|
|
- **Image**: `ghcr.io/getpaseo/paseo:latest` base + `USER root` stage installing
|
|
`@earendil-works/pi-coding-agent@0.82.1` + `omniroute-pi-ext-integration`, drops to `USER paseo`.
|
|
Reason: base image runs as `paseo` (uid 1000); `/usr/local` is root-owned → npm -g must run at build time.
|
|
- **LLM**: container pi → `omni` provider → `http://192.168.20.13:20129/v1` (OmniRoute, LAN IP reachable
|
|
from the bridge net; `host.docker.internal` also mapped). Default model set to the fixed combo:
|
|
`default-opencode-go-ds-flash` (OpenRouter → DeepSeek → OpenCode-Go).
|
|
- **Secrets** live only in `.env` (600) — `PASEO_PASSWORD`, `OMNIROUTE_API_KEY`; never in docs/repos.
|
|
Also mirrored into `~/.config/environment.d/10-secrets.conf` on .27 (and .51 later) as `PASEO_HOST` + `PASEO_PASSWORD` for zero-config CLI.
|
|
- **Access** is LAN/Tailscale-only; password auth enforced. No public Caddy subdomain yet.
|
|
- **Restart/rebuild**: `cd /home/sam/Docker/Containers/paseo && docker compose up -d --build`.
|
|
|
|
---
|
|
|
|
## BEGINNER'S GUIDE — how to use Paseo
|
|
|
|
### The big idea
|
|
|
|
Paseo is a **control room** for AI coding assistants (pi). You start pi working on a task, watch it,
|
|
check back later from any device, and see everything that's running in one place. The heavy lifting
|
|
runs on the always-on server **.13**, so you don't need your desktop powered on.
|
|
|
|
**Key mental model:** every agent you start through Paseo runs on **.13** (in the container). Your
|
|
laptop, desktop, and phone are all *clients* that connect to the same daemon and see the same view.
|
|
So there's no "what's running on .27 vs .51" — there's one shared view: what the .13 daemon is running.
|
|
|
|
> Two consoles, don't confuse them:
|
|
> - **Paseo** — agents you start *through* it (run on .13 container). `paseo ls` / web UI.
|
|
> - **Pi Dashboard** (Go TUI) — pi sessions you open *directly* on each machine in a terminal.
|
|
> Different thing: that's your existing per-machine console.
|
|
|
|
### The 3 commands (start / look / watch)
|
|
|
|
```bash
|
|
# 1. START — give pi a task (runs in background by default, prints an agent ID)
|
|
paseo run --provider pi "Add a README to this project and summarize what it does"
|
|
|
|
# 2. LOOK — what's running / who's idle: status + which folder (CWD)
|
|
paseo ls
|
|
# idle = finished · running = working now · CWD = the folder it's working in
|
|
|
|
# 3. WATCH — tune in live to a running agent (Ctrl+C detaches; the agent keeps going)
|
|
paseo attach <agent-id>
|
|
|
|
# BONUS — read the full history of what an agent did
|
|
paseo logs <agent-id>
|
|
```
|
|
|
|
### A typical workflow
|
|
|
|
A "workflow" here just means *a task you hand pi + how you follow it through*:
|
|
|
|
```bash
|
|
paseo run --provider pi "Review this code and tell me if there are bugs" # start
|
|
paseo ls # check
|
|
paseo attach <id> # watch (optional)
|
|
paseo logs <id> # review when idle
|
|
```
|
|
|
|
Run several at once — 3 agents on 3 tasks, one `paseo ls` shows them all, attach to any. That's the
|
|
"multi-agent coordination": several pi assistants in parallel, one control room.
|
|
|
|
### No-typing option: the web UI
|
|
|
|
Browser → **http://192.168.20.13:6767** (from phone: **http://100.114.62.46:6767** — .13's Tailscale
|
|
IP). Password = `PASEO_PASSWORD` in `.13`'s `.env`. Point-and-click dashboard: start, watch, see
|
|
all agents.
|
|
|
|
### Passwords — what to do
|
|
|
|
- One password protects the web UI + CLI: `PASEO_PASSWORD` in `.13` `/home/sam/Docker/Containers/paseo/.env`.
|
|
- Mirrored to `~/.config/environment.d/10-secrets.conf` on .27 (and .51) so the CLI just works after login.
|
|
- **Rule:** never paste into chat, git-committed files, or public docs. It's a secret.
|
|
- You don't type it day-to-day — it's wired up. Just don't share it or put it in code.
|
|
|
|
### Installing the client on a new machine (.51 pattern)
|
|
|
|
```bash
|
|
# 1. install the Paseo CLI (NOT pi — pi stays Nix-managed)
|
|
npm install -g @getpaseo/cli@0.7.2
|
|
|
|
# 2. add connection info to the machine's secrets file
|
|
# (get the password from .13's .env, never commit it)
|
|
echo "PASEO_HOST=192.168.20.13:6767" >> ~/.config/environment.d/10-secrets.conf
|
|
echo "PASEO_PASSWORD=<password>" >> ~/.config/environment.d/10-secrets.conf
|
|
|
|
# 3. log out/in (environment.d loads at login), then test
|
|
paseo ls
|
|
```
|
|
|
|
Requirements: the machine must be on **Tailscale** or the home LAN to reach .13. .51's pi is 0.80.10
|
|
(Nix) vs .13-container pi 0.82.1 — doesn't affect Paseo (agents use the container pi).
|
|
|
|
### How pi is running / where
|
|
|
|
- **Paseo's pi** — baked into the .13 container (0.82.1). What `paseo run --provider pi` uses. You
|
|
do not install/update it; it's part of the image.
|
|
- **Your normal pi** on each machine (.27/.13/.51) — Nix-managed, used in a terminal. Untouched.
|
|
|
|
### Skills & extensions (IMPORTANT)
|
|
|
|
- Paseo's container pi starts with a **minimal config** (~/.pi in the paseo-home volume): providers +
|
|
omni extension only.
|
|
- It does **NOT** automatically get your `~/.agents` skills/extensions (nixos-workflow,
|
|
system-architect, obsidian-cli, tavily-search, etc.) from Gitea `pi-config`.
|
|
- To give Paseo agents those, we add them to the container (bake into image or mount `~/.agents`).
|
|
**Follow-up task — not done yet.** Until then: Paseo agents handle general coding tasks with the
|
|
base config; for your specialized skills, use your normal terminal pi.
|
|
|
|
### Mobile
|
|
|
|
- Web UI in any phone browser (Tailscale): **http://100.114.62.46:6767**. Simplest, no install.
|
|
- Native ios/android app exists (pairing + E2EE relay) — not needed to start.
|
|
|
|
---
|
|
|
|
## Verified end-to-end (2026-09-09)
|
|
|
|
`paseo run --provider pi --model omni/openrouter/qwen/qwen3.7-flash --cwd /workspace/demo --title paseo-demo`
|
|
→ agent `560ffca0` ran (`pi/omni/openrouter/qwen/qwen3.7-flash`), read `HELLO.txt`, **wrote
|
|
`DEMO_SUMMARY.md`** into the workspace; `paseo logs` shows the full timeline; web UI → HTTP 200. ✅
|
|
|
|
## Findings / decisions
|
|
|
|
- **OmniRoute combo regression (server-side, affects host pi too):** `default-opencode-go-ds-flash`
|
|
→ `400 missing x-opencode-session` (OpenCode-Go leg). Working legs verified 200:
|
|
`openrouter/qwen/qwen3.7-flash` · `openrouter/openai/gpt-5.6-sol` · `aug/claude-haiku-4.5`.
|
|
**Fix OmniRoute combo/credentials to restore the default path.**
|
|
- Install security: `vet` clean · `npq` author verified (boudra = maintainer) · `socket` accepted
|
|
3 low/med CVEs in transitive deps (`qs`, `uuid`, `@ai-sdk/provider-utils`).
|
|
- Paseo is pre-1.0 (0.7.2) — pinned; expect breaking changes between releases.
|
|
- Original AGENT.md noted **Pi Web UI** as an alternative — not needed now; Paseo covers the console use-case.
|
|
|
|
## Related
|
|
- [[Tools Software WebUI]] · [[Pi Dashboard]]
|
|
- `300 areas/350 AI/Pi Agent Extensions & Skills.md`
|
|
- Gitea `sam/paseo` · maps.lab `/paseo/docs/` · Outline project **Paseo** · Vikunja project **Paseo** |