obsidian-vault/200 projects/Tools Software WebUI/Paseo Pi GUI Tool.md

created, modified, type, tags, aliases

created	modified	type	tags	aliases
2026-09-09	2026-09-10	project	ai ai-agents ai-resume paseo pi tool tools	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 · Repo: 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.

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

# 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)

# 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:

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)

# 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