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 · interactive map: maps.lab → Paseo

What it is

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

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)

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.

README.md