228 lines
10 KiB
Markdown
228 lines
10 KiB
Markdown
---
|
|
created: 2026-09-09
|
|
modified: 2026-09-10
|
|
type: project
|
|
status: active
|
|
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<br/>paseo CLI"]
|
|
D51[".51 laptop<br/>paseo CLI"]
|
|
M["Mobile / web UI<br/>browser"]
|
|
end
|
|
subgraph S13["Paseo daemon (.13 — native, 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: ~/.config/environment.d/10-secrets.conf>
|
|
|
|
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 |
|
|
|---|---|
|
|
| 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/<name>/`** — 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 <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` `~/.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=<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 `<project>/.pi/settings.json` with a package entry
|
|
`{ "source": "/home/sam/.agents", "skills": ["skills/<name>"...] }`.
|
|
|
|
### 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** |