133 lines
5.7 KiB
Markdown
133 lines
5.7 KiB
Markdown
# Paseo — Agent Orchestration, Native on .13
|
|
|
|
**Multi-agent orchestration (Paseo 0.7.2) running as a native daemon on `.13` — driving the host's
|
|
pi (0.82.1) with full filesystem access, LLM via OmniRoute.**
|
|
|
|
> Maintained by Sam · Gitea — [sam/paseo](https://gitea.lab.audasmedia.com.au/sam/paseo) ·
|
|
> interactive map: [maps.lab → Paseo](https://maps.lab.audasmedia.com.au/paseo/docs/system-map.html)
|
|
|
|
---
|
|
|
|
## What it is
|
|
|
|
[Paseo](https://github.com/getpaseo/paseo) is a client-server orchestration layer for AI coding
|
|
agents: one **daemon** manages agent processes and streams output to CLI, web and mobile clients.
|
|
|
|
On this lab it runs **natively on the always-on NixOS host `.13`** (no container): the daemon spawns
|
|
the **host's own pi 0.82.1** (`pi --mode rpc`) as user `sam`, giving agents **direct access to the
|
|
real filesystem** — projects, the Obsidian vault, photos — with the user's real permissions. LLM
|
|
traffic routes through the existing **OmniRoute** proxy on `.13:20129`.
|
|
|
|
- **Local-first** — no telemetry, no cloud dependency (Tailscale/LAN only).
|
|
- **No sandbox** — this is deliberate: the daemon *is* `sam`. Guardrails come from pi's own
|
|
protections (filechanges, approvals), not a container boundary.
|
|
- **One console** — `paseo ls` / `attach` / `logs` from .27, .51, and mobile web UI.
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
subgraph CLIENTS["Clients"]
|
|
D27[".27 desktop<br/>paseo CLI"]
|
|
D51[".51 laptop<br/>paseo CLI"]
|
|
M["Mobile / web UI<br/>browser / Tailscale"]
|
|
end
|
|
subgraph N13["Native daemon on .13 (NixOS, always-on)"]
|
|
D["Paseo daemon 0.7.2<br/>systemd user service<br/>0.0.0.0:6767"]
|
|
PI["pi 0.82.1 (Nix)<br/>pi --mode rpc<br/>host ~/.pi + ~/.agents"]
|
|
FS[("Host filesystem as `sam`<br/>projects: ~/paseo/projects/<br/>obsidian vault, photos, /mnt/*")]
|
|
FW["NixOS firewall<br/>port 6767 open"]
|
|
end
|
|
subgraph LLM["LLM routing"]
|
|
OR["OmniRoute .13:20129"]
|
|
OP["OpenRouter / DeepSeek /<br/>OpenCode-Go (deferred)"]
|
|
end
|
|
D27 -->|"PASEO_HOST + password"| D
|
|
D51 -->|"PASEO_HOST + password"| D
|
|
M -->|"Tailscale / LAN :6767"| D
|
|
D -->|"spawns / manages (no sandbox)"| PI
|
|
PI -->|"direct access, real permissions"| FS
|
|
D -.->|"listen allowed"| FW
|
|
PI -->|"omni provider /v1"| OR
|
|
OR -->|"combo routing"| OP
|
|
```
|
|
|
|
## Directory map
|
|
|
|
```
|
|
paseo/
|
|
├── README.md ← this file
|
|
└── docs/
|
|
├── system.mmd ← Mermaid source (single source of truth)
|
|
├── system.architecture.json ← Archify source
|
|
├── system-map.html ← interactive Archify map
|
|
└── diagrams/
|
|
├── system.png
|
|
└── system.svg
|
|
```
|
|
|
|
## Quick start (client)
|
|
|
|
```bash
|
|
npm install -g @getpaseo/cli@0.7.2 # one-time, per machine
|
|
|
|
export PASEO_HOST=192.168.20.13:6767 # or in ~/.config/environment.d/10-secrets.conf
|
|
export PASEO_PASSWORD=<PASEO_PASSWORD> # on .13's secrets file
|
|
|
|
paseo status # daemon reachable?
|
|
paseo ls # running agents
|
|
paseo run --provider pi "your task" # defaults to combo model, cwd = your folder
|
|
paseo logs <agent-id> # full activity timeline
|
|
```
|
|
|
|
Web UI: `http://192.168.20.13:6767` (LAN) · `http://100.114.62.46:6767` (Tailscale/mobile).
|
|
|
|
## Deployment (server, `.13`)
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Daemon | Paseo 0.7.2 · **native** · systemd user service `paseo.service` · `0.0.0.0:6767`, enabled |
|
|
| pi | Host Nix pi 0.82.1 (`/etc/profiles/per-user/sam/bin/pi`) — used directly via `--mode rpc` |
|
|
| Config | `~/.paseo/` (daemon) · `~/.pi/` + `~/.agents/` (host pi, Gitea `pi-config` clone) |
|
|
| Projects | `~/paseo/projects/<name>/` — real paths, direct FS access |
|
|
| LLM | pi → omni provider → `http://192.168.20.13:20129/v1` (OmniRoute) |
|
|
| Firewall | `networking.firewall.allowedTCPPorts` includes **6767** (NixOS configuration.nix) |
|
|
| Secrets | `PASEO_PASSWORD` in `.13` `~/.config/environment.d/10-secrets.conf` (chmod 600) |
|
|
|
|
**Start/stop/status:** `systemctl --user {start,stop,status} paseo` · logs: `journalctl --user -u paseo`.
|
|
|
|
## Verified end-to-end (2026-09-16)
|
|
|
|
```
|
|
$ paseo run --provider pi "…" # bare run — model defaults to combo
|
|
Model omni/default-opencode-go-ds-flash # healthy combo (OpenRouter → DeepSeek → OpenCode-Go)
|
|
Cwd /home/sam/paseo/projects/obsidian_cleanup_tool
|
|
Status idle ✅ (agent replied NATIVE_OK / NEWPATH_OK)
|
|
```
|
|
|
|
- Clients: .27 CLI · .51 CLI · mobile web UI all reach the daemon (LAN + Tailscale). ✅
|
|
- Migration from the earlier Docker deployment completed; Docker removed (legacy backup in
|
|
`~/paseo/docker-legacy-backup-…`).
|
|
|
|
## Known notes
|
|
|
|
- **Model default:** the pi model catalog was reordered so `default-opencode-go-ds-flash` is first
|
|
(bare `paseo run` picks it instead of a flaky free leg). If the combo's OpenCode-Go leg is
|
|
sub-rate-limited, the combo still falls back OpenRouter → DeepSeek.
|
|
- **Skills:** the host pi (`~/.agents`) carries the full skill set (nixos-workflow, system-architect,
|
|
project-ops, obsidian-cli, etc.). Per-project `.pi/settings.json selects which are loaded.
|
|
- **Security model:** native = full user permissions. Do not expose the daemon publicly; keep
|
|
LAN/Tailscale + password (no public Caddy vhost; use Paseo relay only if internet access is ever
|
|
required).
|
|
|
|
## Why it matters
|
|
|
|
- **Full-control autonomy: the daemon is `sam`, so agents manage real files (photos, vault,
|
|
projects) with no mount plumbing.
|
|
- One always-on control plane for pi across all devices — the "phone control plane" use case.
|
|
- n8n/Prefect email→agent workflows, scheduled runs, and browser tasks (pi-browser-harness) can be
|
|
layered on top.
|
|
|
|
---
|
|
|
|
*Documentation project — no proprietary code. Secrets never appear in this repo.* |