--- 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**, running **natively on .13** (no Docker), driving the host's **pi (0.82.1)** with full filesystem access, LLM through **OmniRoute**. Native migration 2026-09-16. **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** runs natively on .13 (systemd user service), spawns and manages agent processes, streams output over WebSocket. - **Clients** — CLI (`paseo` on .27/.51), web UI (:6767), mobile — attach over LAN/Tailscale. - **Pi is a first-class provider**: the daemon spawns the **host's own pi 0.82.1** via `pi --mode rpc` (Nix-managed, no image bake-in). - **No sandbox — full control**: the daemon runs as user `sam`, so agents reach the real filesystem directly (projects, vault, photos). This is the autonomy model: pi's own guardrails (filechanges, approvals) protect the work, not a container boundary. - **Local-first**: 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 — native, 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 | |---|---| | Native daemon | `.13` systemd user service `paseo.service` (enabled) — `0.0.0.0:6767` | | pi (host Nix 0.82.1) | `.13` `/etc/profiles/per-user/sam/bin/pi` — used directly | | Paseo config | `.13` `~/.paseo/` | | **Real projects** | `.13` **`~/paseo/projects//`** — direct FS access, no mounts | | Obsidian vault / photos | directly accessible (agent runs as `sam`) | | Docs + diagram + map | Gitea `sam/paseo` → `docs/` → maps.lab (`/paseo/docs/`) | | Client CLIs | `.27`/`.51` `~/.local/share/npm-global` (`paseo` 0.7.2) | | Legacy Docker backup | `.13` `~/paseo/docker-legacy-backup-20260916104024/` (delete when confident) | ## Config notes (no secrets) - **Daemon**: native, `systemctl --user {start,stop,status} paseo`; logs `journalctl --user -u paseo`. Start cmd: `paseo start --listen 0.0.0.0:6767 --web-ui` (daemonized; `--foreground` is buggy with PID lock). - **pi**: host Nix pi 0.82.1 with the host `~/.pi/` + `~/.agents` (Gitea `pi-config` clone) — full skill set, per-project `.pi/settings.json` selects which load. - **LLM**: pi → `omni` provider → `http://192.168.20.13:20129/v1` (OmniRoute). Default model = combo `default-opencode-go-ds-flash` (OpenRouter → DeepSeek → OpenCode-Go) — models.json reordered so it's first. - **Secrets**: `PASEO_PASSWORD`/`PASEO_HOST` in `.13` `~/.config/environment.d/10-secrets.conf` (600); mirrored to .27/.51 secrets. Never in docs/repos. - **Firewall**: port 6767 added to `networking.firewall.allowedTCPPorts` in `.13` `/etc/nixos/configuration.nix` (backup `configuration.nix.bak-paseo-…`). - **Access** is LAN/Tailscale-only; password auth enforced. No public Caddy subdomain (use Paseo relay only if internet access ever needed). --- ## 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` `~/.config/environment.d/10-secrets.conf`. - 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 (native = full toolbox) - Native daemon uses the **host pi** (`~/.pi` + `~/.agents` on .13, Gitea `pi-config` clone) — so Paseo agents have the **same skills as your terminal pi** (nixos-workflow, system-architect, project-ops, obsidian-cli, etc.). No bake-in needed. - Per-project `.pi/settings.json` **selects** which skills load (project settings replace global). - To give a specific project skills: create `/.pi/settings.json` with a package entry `{ "source": "/home/sam/.agents", "skills": ["skills/"...] }`. ### 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**