---
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 a working leg:
  `openrouter/qwen/qwen3.7-flash`.
- **Secrets** live only in `.env` (600) — `PASEO_PASSWORD`, `OMNIROUTE_API_KEY`; never in docs/repos.
- **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`.

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