Paseo: How to Self-Host Coding Agents and Supervise Them by Phone

Leaving your desk should not mean losing sight of a local Claude Code, Codex, or OpenCode session. Cloud sandboxes help some teams, but they are a poor fit when NDA rules, machine-local reproduction, or an existing subscription/MCP setup must stay on hardware you control.

📑Table of Contents

1. What Paseo is: local daemon, multi-device supervision
2. Supported agents and v0.2.5 install paths
3. Remote access: E2E relay and security boundaries
4. Parallel sessions, worktrees, and bundled skills
5. Role split vs cloud sandboxes and other meta-harnesses
6. Pre-adoption checklist and fit/no-fit
7. FAQ
8. Summary: what to verify next

The adoption boundary is simple: where does the agent actually run?

What Paseo is (quick definition)

Paseo (GitHub: getpaseo/paseo, paseo.sh) is a self-hosted orchestrator that starts existing CLI coding agents (Claude Code, Codex, OpenCode, and peers) as processes on your host and lets you supervise them from Desktop, Mobile, Web, and CLI through one UI surface. Treat popularity as an as-of signal: roughly 12.1k stars on the GitHub UI as of 2026-08-05.

Research-window snapshot:

• License: AGPL-3.0
• Latest around 2026-07-30: v0.2.5
• GitHub UI on 2026-08-05: roughly 12.1k stars / 1.2k forks

What this article covers

This article covers architecture, install paths, E2E relay security boundaries, worktrees and bundled skills, how Paseo differs from cloud sandboxes and other meta-harnesses, and a pre-adoption checklist.

Your next decision is whether you can keep a host awake, start the daemon via Desktop or headless CLI, and optionally pair a phone over relay for one real session.

Learning outcomes

---

What Paseo is: local daemon, multi-device supervision

Design in one sentence

Paseo’s core is a host daemon that manages agent processes while clients (desktop/mobile/web/CLI) connect to that daemon. The official site frames it as self-hosted, multi-provider, open-source orchestration from desk and phone.

Design claims

Key design claims from primary docs:

• Agents run with your provider credentials, not a Paseo-owned cloud runtime
• Code stays on the machine for execution rather than being dropped into a vendor sandbox
• Native harness assets—subscriptions, skills, config, MCP—are reused on the CLI side
• README states no telemetry and no forced login
• Monorepo packages include server/daemon, Expo app, CLI, Electron desktop, relay, and website

Think of Paseo as a supervision and orchestration layer on top of tools you already use, not a replacement agent runtime.

Snapshot (research window)

Item	Detail (as researched)
Repository	getpaseo/paseo
Site	paseo.sh
License	AGPL-3.0
Latest	v0.2.5 (around 2026-07-30)
Popularity signal	~12.1k★ / 1.2k forks (2026-08-05 check)
Default listen	127.0.0.1:6767
Reachability	E2E encrypted relay or direct (LAN/Tailscale/VPN/etc.)

Sources: GitHub README, paseo.sh, Security docs (as of August 2026).

---

Supported agents and v0.2.5 install paths

Prerequisites

README expects at least one of Claude Code, Codex, GitHub Copilot, OpenCode, or Pi installed and authenticated on the host.

Docs disagree slightly on the fifth seat: FAQ lists Cursor; README includes Copilot. A Qiita hands-on notes Cursor via ACP (cursor-agent acp). Treat “at least Claude Code / Codex / OpenCode / Pi” as the safe baseline and verify extra providers on your machine.

Install matrix

1. Desktop (fastest): paseo.sh/download or GitHub Releases — macOS dmg / brew install --cask paseo, Windows exe, Linux AppImage/DEB/RPM. Desktop launch typically starts the daemon.
2. Mobile: Play Store package sh.paseo, APK, iOS App Store “Paseo – Pocket Engineer” (id6758887924).
3. Web: app.paseo.sh
4. Headless CLI: npm install -g @getpaseo/cli then paseo (also nix run github:getpaseo/paseo).
5. Docker example: ghcr.io/getpaseo/paseo:latest on port 6767 with PASEO_PASSWORD and a carefully scoped volume.

Release assets

v0.2.5 includes Linux Debian packaging fixes (#2654) and ships dmg/exe/deb/rpm/AppImage/APK assets. GIGAZINE walked through Windows Desktop install and the project → workspace → agent → chat flow with screenshots.

Source

Smoke-check commands

Useful first commands after install:

paseo status
paseo daemon pair
paseo run --provider claude-code
paseo ls
paseo attach <session>

Provider names and flags can change by version—prefer official CLI docs and paseo --help.

---

Remote access: E2E relay and security boundaries

Relay vs direct

• E2E encrypted relay (often recommended off-LAN): daemon opens an outbound relay connection. Official relay: getpaseo/paseo-relay (Elixir). Fresh installs keep relay off until pairing confirms enablement.
• Direct: same LAN, Tailscale/VPN, or deliberate port exposure when you already trust the network path.

Crypto: ECDH (Curve25519) + XSalsa20-Poly1305 (NaCl box). The relay is described as seeing IP/timing/size/session ID style metadata, not plaintext repository contents (Security docs).

Auth and bind defaults

Default listen is 127.0.0.1:6767. Binding 0.0.0.0 is warned against; host allowlists (daemon.hostnames) mitigate DNS rebinding. Passwords use bcrypt; Bearer/WebSocket subprotocol protect APIs; /api/health is the unauthenticated exception.

Practical security boundaries

Boundaries that matter in practice:

• Paseo does not store or transmit provider API keys (auth stays in each CLI)
• Local execution does not mean agents stop calling provider APIs
• Recommended ops: relay for mobile, treat QR as password-equivalent, require password when binding beyond localhost, minimize Docker mounts

Pairing failure modes

Qiita’s Mac/Android write-up documents Android native pairing where a truncated offer URL leads to Connection timed out, with web fallback and full-URL paste as mitigations. First success criterion: paseo status shows daemon/relay health, then one phone attach/send works.

---

Parallel sessions, worktrees, and bundled skills

CLI surface

Beyond single-session supervision, CLI docs cover run, ls, attach, send, logs, stop, wait, plus worktree flags such as --new-workspace worktree, --worktree-mode branch-off, --new-branch, and --base.

A practical loop looks like:

1. Branch or worktree
2. Preview (third-party write-ups emphasize branch-based URLs to avoid port clashes)
3. Inline review
4. Commit / PR / merge

GIGAZINE and a Zenn operator review both highlight multi-pane UI, parallel dev servers, and scriptable paseo run/ls/attach/send.

Skills and optional Hub

Install skills with npx skills add getpaseo/paseo, then use /paseo-handoff, /paseo-loop, /paseo-advisor, /paseo-committee.

Optional Hub adds GitHub/Slack/Discord triggers and team access. Voice defaults to local STT/TTS; OpenAI speech is optional.

Do not enable everything on day one. Order of risk:

1. Single-session supervision
2. Worktree only if needed
3. Skills last

---

Role split vs cloud sandboxes and other meta-harnesses

Comparison axes

Before the table, keep these axes front-and-center:

• Where agents run
• UI purpose
• Reuse of existing CLI assets
• Offsite reach

Comparison table: runtime and code

Axis	Paseo	Cloud sandbox style (e.g. Cosyra contrast)	Team harness / swarm control
Where agents run	Your machine/VM/dev-server daemon	Vendor-isolated cloud workspace	Product-dependent control plane
Code placement	Local execution baseline	Cloud working tree	Depends on design
UI purpose	Multi-device supervision/orchestration	Browser-complete execution	Team coordination / many agents

Comparison table: assets, reach, fit

Axis	Paseo	Cloud sandbox style (e.g. Cosyra contrast)	Team harness / swarm control
Existing CLI assets	Reuse native subs, skills, MCP, config	Often rebuild environment	Often custom runtime
Offsite reach	E2EE relay / LAN / your tunnel	Service reachability assumed	Product-specific
Best fit	NDA, machine-local deps, always-on self-host	Minimal setup, shared isolation	Large-scale parallel org workflows

Sources for the comparison

Sources:

• Cosyra vs Paseo
• note.com KeiTy
• paseo.sh
• getpaseo/paseo

(July–August 2026 window).

How to read the market slice

Cosyra’s independent guide treats Paseo’s strengths as free/OSS, keeping code off a cloud sandbox, and reusing CLI auth—while flagging always-awake host and preinstalled CLIs as hard constraints.

KeiTy’s meta-harness overview scores Paseo strongly for multi-harness phone supervision versus peers such as Maestro/Agent Deck.

Versus team harnesses (e.g. QM-style) or swarm supervisors (e.g. Puppetmaster-style), Paseo’s center of gravity is remote supervision UI + self-hosted daemon.

• Need an organizational multi-agent control plane → evaluate those layers separately
• Refuse to abandon Claude Code/Codex configs just to leave your desk → Paseo is the closer fit

---

Pre-adoption checklist and fit/no-fit

Checklist: host and install

Use this as an actionable gate for host readiness:

1. Always-on host: Will laptop sleep kill the daemon? If yes, move to a home server/VM/always-on box.
2. CLI readiness: Is the target provider installed and logged in on that host?
3. Install path: Desktop / brew install --cask paseo / @getpaseo/cli / Docker.
4. Reachability: LAN direct enough, or enable relay at pair time, or use Tailscale-class tunnels?

Checklist: security, mobile, and fit

Continue with security and adoption gates:

1. Security baseline: Stay on 127.0.0.1 unless needed; if binding wider, set password + host allowlist; minimize Docker mounts.
2. Mobile proof: paseo status → pair → one phone attach/send. Prefer full offer URL paste on Android.
3. Parallelism demand: Skip worktree/skills until single-session supervision is boringly reliable.
4. No-fit signals: No always-on host; mandatory managed isolation; AGPL conflicts with policy; unclear provider ToS for remote operation.

Fit signals

Good fit

• Keep Claude Code / Codex / OpenCode as-is
• Supervise from phone/web
• Keep code local
• Unify multiple CLIs under one surface

Poor fit

• Zero host ops budget
• Must-have managed isolation
• AGPL distribution obligations are unacceptable

Related reading

If you still need to stabilize Claude Code before orchestration:

• Loop design: Claude Code loop patterns: stop conditions, /goal, and token ops
• Repo scaffolding: Claude Code Setup plugin: hooks, skills, MCP, subagents from repo analysis

---

FAQ

Q1. Is Paseo free?

Official FAQ describes it as free open source under AGPL-3.0. Provider API/subscription costs are separate.

Q2. Does code leave my machine?

Execution is local-by-design. Agents still call provider APIs as usual. The relay is documented as carrying encrypted payloads rather than holding plaintext repos (Security docs).

Q3. Does it work beyond Claude Code?

At least Codex/OpenCode/Pi and more. Copilot and Cursor (ACP) appear in docs or third-party verification. Because README vs FAQ naming differs for the fifth seat, verify on your host.

Q4. Can I run everything from a phone alone?

No. The host still needs the daemon and agent CLIs. The phone is a supervision client.

Q5. Is the relay mandatory?

No. Direct LAN or your own tunnel works. Fresh installs default relay off; official E2E relay is convenient off-network.

Q6. Do I give Paseo API keys?

Security docs say provider auth stays in each CLI; Paseo does not store or send API keys.

Q7. Windows support?

Yes—Windows installers are on the download page, and GIGAZINE documents a Windows Desktop flow.

---

Summary: what to verify next

Core value

Paseo is not “cloud sandbox, but free.” It is a multi-device supervision layer for CLI agents that already run on hardware you operate. The durable value is native harness reuse, mobile/web supervision, optional E2E relay, and worktree/skills once the basics work.

Four decision gates

Decide on four gates before feature tourism:

1. Always-on host capacity
2. Operable security boundary (bind/password/relay/mount)
3. AGPL policy fit
4. One successful paired supervision session

Next steps

1. Install the target provider CLI on the host
2. Start the daemon via Desktop or CLI
3. Pair relay only if offsite access is required
4. Prove attach/send on one real task
5. Expand to worktrees and skills only after that proof

Primary sources

Prefer primary sources:

• paseo.sh
• Download
• Releases
• Security
• CLI docs

Use independent write-ups (Cosyra, GIGAZINE, Qiita, Zenn, note) as corroboration, not as substitutes for your own smoke test.