--- 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
paseo CLI"] D51[".51 laptop
paseo CLI"] M["Mobile / web UI
browser"] end subgraph S13["Paseo daemon (.13 — Docker, always-on)"] D["Paseo daemon 0.7.2
:6767 · auth"] PI["pi agent 0.82.1
pi --mode rpc"] CFG["pi config
/home/paseo/.pi"] W["workspaces
/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= 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 # full activity timeline paseo attach # 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 # BONUS — read the full history of what an agent did paseo logs ``` ### 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 # watch (optional) paseo logs # 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=" >> ~/.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**