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