Paseo — Self-Hosted Orchestrator for All Your Coding Agents
Paseo — Self-Hosted Orchestrator for All Your Coding Agents
If you use multiple AI coding agents — Claude Code for architecture, Codex for implementation, Copilot for quick fixes — you've felt the friction of switching between different CLIs, terminals, and contexts. Each agent has its own interface, its own configuration, and its own way of managing files. Paseo solves this by giving you a single daemon that orchestrates all of them.
Paseo is an open-source, self-hostable platform that runs a daemon on your machine and lets you drive any coding agent from a desktop app, mobile app, web UI, or CLI. It launched in late 2025 and has already gained 7,400+ stars on GitHub, trending strongly among developers who work with multiple agent providers.
Why It's Trending
Coding agents have become essential tools, but the ecosystem is fragmented. Developers who want the best model for each task — Claude for planning, GPT-5 for coding, Copilot for inline suggestions — end up juggling multiple terminals and remembering different command syntaxes.
Paseo's appeal is simple: one interface, any agent. You install the daemon once, connect your existing agent CLIs (Claude Code, Codex, GitHub Copilot, OpenCode, Pi), and control them all from a single pane of glass. The mobile app means you can also start or check on agents from your phone — a feature that's surprisingly rare in the coding agent space.
The project hit #1 on Hacker News and has been growing steadily since, driven by its clean architecture, native mobile apps, and genuine commitment to self-hosting and privacy.
Architecture Overview
Paseo follows a daemon-client architecture. At the center is the Paseo Daemon — a local server that manages agent processes, WebSocket connections, and an MCP server for agent-to-agent orchestration. Clients (desktop app, mobile app, web UI, and CLI) all connect to this daemon, either locally or through an optional encrypted relay for remote access.
The daemon communicates with each agent provider's CLI (Claude Code, Codex, etc.) via their standard command-line interfaces, wrapping them in a uniform API. The MCP server allows agents themselves to use Paseo — one agent can spawn another, wait for results, and incorporate them into its workflow.
For remote access, Paseo offers a relay system with end-to-end encryption. You pair your daemon with your mobile app via a QR code, and the connection goes through Paseo's relay without exposing your machine to the network. You can also self-host the relay with TLS for full control.
Prerequisites
Before installing Paseo, you need at least one coding agent CLI installed and configured:
- Claude Code —
npm install -g @anthropic/claude-code - Codex —
npm install -g @openai/codex - GitHub Copilot —
npm install -g @github/cli-copilot - OpenCode —
pip install opencode - Pi —
npm install -g @pi-ai/cli
You'll also want the GitHub CLI (gh) installed and authenticated — Paseo uses it for PR-aware worktrees and orchestration features.
Installation
Desktop App (Recommended)
The desktop app is the simplest way to get started. It bundles its own daemon and starts it automatically.
- Download from paseo.sh/download or the GitHub releases page
- Open the app — the daemon starts automatically
- Scan the QR code in Settings from the mobile app to pair your phone
CLI / Headless Installation
For servers, remote machines, or headless setups:
npm install -g @getpaseo/cli
paseoThis starts the daemon and prints a QR code in the terminal. Scan it from the mobile app or connect via the web UI.
The daemon's configuration and state live under ~/.paseo by default (configurable via PASEO_HOME).
Configuration
Paseo is configured through a JSON file at PASEO_HOME/config.json. Key settings include:
{
"daemon": {
"host": "127.0.0.1",
"port": 6767,
"mcp": {
"enabled": true,
"injectIntoAgents": true
}
},
"providers": {
"claude": {
"enabled": true,
"model": "claude-sonnet-4-20250514"
},
"codex": {
"enabled": true
}
}
}For remote access through a self-hosted relay with TLS:
{
"daemon": {
"relay": {
"enabled": true,
"endpoint": "127.0.0.1:8080",
"publicEndpoint": "relay.example.com:443",
"useTls": true
}
}
}Docker Compose (Self-Hosted Relay)
If you want to run the Paseo relay behind nginx with TLS, here's a minimal docker-compose setup:
version: "3.8"
services:
relay:
image: nginx:alpine
ports:
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
- /etc/letsencrypt:/etc/letsencrypt:ro
restart: unless-stoppedWith a minimal nginx WebSocket proxy config:
events {}
http {
server {
listen 443 ssl;
server_name relay.example.com;
ssl_certificate /etc/letsencrypt/live/relay.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/relay.example.com/privkey.pem;
location /ws {
proxy_pass http://paseo-daemon:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}
}Usage
Running Agents
Start an agent with a task from the CLI:
paseo run "fix the failing tests"
paseo run --provider codex "refactor the API layer"
paseo run --detach "run the full test suite" # background
paseo run --worktree feature-x "implement feature X"Managing Agents
paseo ls # List running agents
paseo attach abc123 # Stream agent output in real-time
paseo send abc123 "now add tests" # Send follow-up task
paseo logs abc123 # View agent timeline
paseo stop abc123 # Stop an agentMulti-Agent Workflows
One of Paseo's most powerful features: agents can orchestrate other agents.
# Agent spawns a sub-agent for parallel work
paseo run --detach "implement the API" --name api-agent
paseo wait api-agent
paseo logs api-agent --tail 5Skills (Agent-to-Agent Workflows)
Paseo ships with skills that you can inject into any agent conversation:
/paseo-handoff— Hand off work between agents (e.g., plan with Claude, implement with Codex)/paseo-loop— Loop an agent against clear acceptance criteria with a verifier/paseo-advisor— Spin up an advisor agent for a second opinion/paseo-committee— Form a committee of two contrasting agents for root cause analysis
Add skills to your environment:
npx skills add getpaseo/paseoRemote Access
Connect to your daemon from anywhere using a pairing offer:
paseo daemon pair --json # Get pairing URL
# From another machine:
paseo ls --host "$OFFER_URL"
paseo run --host "$OFFER_URL" "deploy the hotfix"Verification Checklist
After installing Paseo, verify everything works:
- Daemon is running:
paseo daemon statusreturns "running" - Providers are detected:
paseo run --helplists available providers - An agent can run a simple task:
paseo run "echo hello"completes - Mobile app connects to the daemon (QR pairing)
- Remote CLI connects via offer URL:
paseo ls --host "$OFFER_URL"shows agents - MCP tools are injected: Check agent settings → "Inject Paseo tools" is enabled
- Skills load correctly:
/paseo-handoffis available in agent conversations
Comparison with Alternatives
Paseo occupies a unique niche — it's not an IDE plugin or a hosted service. Here's how it compares:
- Claude Desktop / Codex App — Provider-specific UIs. You can only use one agent provider per app. Paseo unifies all of them.
- OpenCode Desktop — Great for OpenCode users but doesn't support Claude Code or Codex. Paseo supports all major providers.
- Conductor — Similar orchestrator concept but more opinionated about workflows. Paseo is more flexible and has first-class mobile support.
- Happy Coder — Focused on code generation with a single model. Paseo is an orchestrator for any agent workflow.
Paseo's key differentiators are its daemon-client architecture (runs on your hardware, not in the cloud), multi-provider support (any agent CLI works), and native mobile apps (iOS and Android).