# Paseo: a self-hosted control plane for Claude Code, Codex, Copilot, OpenCode and Pi

> Paseo runs a local daemon that manages coding agent processes and exposes them over a WebSocket API to desktop, mobile, web and CLI clients. It is for engineers who already run agent CLIs and want one place to start, watch and hand off work across machines.

**getpaseo/paseo** — Orchestrate multiple coding agents from desktop and mobile

- Repository: https://github.com/getpaseo/paseo
- Website: https://paseo.sh
- Stars: 19,092 · Forks: 2,217
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/getpaseo-paseo

## The coordination problem Paseo targets, and who feels it

Running one coding agent in one terminal is easy. Running four of them across two repositories, on a workstation at the office and a laptop at home, is not. Each CLI keeps its own session state, its own working directory and its own notion of what is running. You end up with a wall of terminals and no reliable answer to "what is still going".

Paseo's answer is to put a long-lived local server, the daemon, between you and the agent processes. The README describes it plainly: "Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it." The intended user is someone who already has credentials configured for Claude Code, Codex, GitHub Copilot, OpenCode or Pi, and wants to pick a different provider per task rather than committing to one vendor's interface. The cross-device angle matters here: the same daemon serves an Expo client for iOS, Android and web, an Electron desktop app, and the `paseo` CLI, so a task started at a desk can be inspected from a phone without moving the work itself off your machine.

## Daemon, WebSocket API and relay: how the pieces connect

The repository layout makes the architecture legible. `packages/server` holds the daemon, described in the README as handling "agent process orchestration, WebSocket API, MCP server". `packages/relay` holds "relay transport and encryption used by the daemon and clients". `packages/app` is the Expo client, `packages/desktop` the Electron app, `packages/cli` the terminal surface, and `packages/client` the TypeScript SDK.

So the data flow is: a client opens a WebSocket to the daemon, asks it to create an agent with a provider, a working directory and a prompt, and the daemon spawns and supervises the underlying agent CLI process. Output streams back over the same socket. The SDK example in the README shows the shape directly, connecting to `ws://127.0.0.1:6767/ws` and calling `client.agents.create(...)` with a `config.provider`, a `cwd` and a `prompt`, then awaiting `agent.waitForFinish()` and reading `result.lastMessage`.

Two design choices stand out. First, the daemon is the single source of truth for agent state, which is what makes `paseo ls` and `paseo attach` meaningful across devices. Second, the relay is optional. The README states that on the CLI path Paseo "asks whether to enable the end-to-end encrypted relay for device pairing. If you decline, connect directly over TCP, Tailscale, or another VPN." That is a real fork in the road, and it shapes your network setup more than any other decision.

## Installing Paseo and running your first agent

The desktop app is the shortest path. The README says to download it from paseo.sh/download or the GitHub releases page, and that opening it starts the daemon automatically with nothing else to install. Phone pairing then goes through Settings, your host, then Pair Device.

For servers and remote machines, the CLI is the documented route. Install it globally and start it:

```bash
npm install -g @getpaseo/cli
paseo
```

On first start Paseo asks whether to enable the end-to-end encrypted relay for device pairing. Declining leaves you connecting directly over TCP, Tailscale or another VPN, which is the usual choice for a machine you already reach over a private network.

Once the daemon is up, the README's CLI examples show how to dispatch work. Each `run` names a provider in `provider/model` form:

```bash
paseo run --provider claude/opus-4.6 "implement user authentication"
paseo run --provider codex/gpt-5.5 --worktree feature-x "implement feature X"
```

The `--worktree feature-x` flag is worth noticing: it scopes the agent to a git worktree, which is how you keep two agents from editing the same checkout. To see what is live and follow one of them:

```bash
paseo ls
paseo attach abc123
paseo send abc123 "also add tests"
```

The first command lists running agents, the second streams live output from one, and the third sends a follow-up task to the same session. Running against a remote daemon uses `--host` with a `host:port` pair, and the README notes that `--cwd` is then a path on that host, not on your local machine:

```bash
paseo run --host workstation.local:6767 --cwd /workspace "run the full test suite"
```

If you would rather not install the CLI at all, the documented Docker path runs the daemon and the self-hosted web UI together:

```bash
docker run -d --name paseo \
  -p 6767:6767 \
  -e PASEO_PASSWORD=change-me \
  -v "$PWD/paseo-home:/home/paseo" \
  -v "$PWD:/workspace" \
  ghcr.io/getpaseo/paseo:latest
```

After it starts, the README says to open `http://localhost:6767`. The image does not ship your agent CLIs, so the README instructs you to extend the base image with the ones you use and supply credentials through environment variables or the persistent `/home/paseo` volume. Change `PASEO_PASSWORD` before exposing the port anywhere.

## Where Paseo gets in your way

The prerequisite is the first constraint and the one people skip past. Paseo does not include an agent. You need at least one of Claude Code, Codex, GitHub Copilot, OpenCode or Pi installed and configured with credentials, and the daemon orchestrates those processes. If you have not authenticated an agent CLI on a machine, Paseo has nothing to run there.

The Docker path inherits the same problem in a sharper form. The published image gives you the daemon and web UI, not the agents, so a working container means building a derived image with your CLI of choice and arranging credentials. That is ordinary container work, but it is work the one-line `docker run` hides.

The plugin system carries a stated risk that deserves repeating rather than paraphrasing away. The README says plugins "run with access to your daemon machine and inside connected clients; install only code you trust." A plugin is not a sandboxed theme file in the way a browser extension is; it is code running where your agents run.

Finally, Paseo is the wrong tool if you want a hosted service that keeps your sessions alive when your machine is off. The README's whole framing is self-hosted: agents run on your machine with your dev environment. That is the point, and it is also the boundary. If your laptop sleeps, so does the daemon on it, unless you run the daemon somewhere that stays up.

## How Paseo differs from a single-vendor agent CLI

The obvious alternative is just using Claude Code or Codex directly in a terminal, which is what most people do before looking at something like Paseo. The difference is scope, not capability. A single CLI owns one session in one directory and gives you a TUI. Paseo owns a fleet: providers from several vendors behind one `--provider` flag, a list of running agents, attachable output streams, and clients on four platforms pointed at the same daemon.

That difference cuts both ways. A vendor CLI is updated by the vendor and needs no intermediary process; Paseo adds a daemon, a WebSocket protocol and a relay as things that can be misconfigured or need upgrading. The trade is coordination for moving parts. If you run one agent in one repo, the daemon is overhead you will not recoup. If you run several agents and want to check on them from a phone, the daemon is the thing that makes that possible at all.

The skills bundled in the repository show the intended workflow rather than a feature list. `npx skills add getpaseo/paseo` installs them, after which `/paseo-handoff`, `/paseo-advisor` and `/paseo-committee` are available inside an agent conversation. The README describes `/paseo-handoff` as handing work between agents, with the author's own pattern being to plan with Claude and hand off to Codex to implement. That is a workflow opinion baked into tooling, and it only makes sense if you are already running more than one provider.

## Maintenance, licensing and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-10, the same day v0.8.0 was released. The release history shows a steady cadence: v0.7.2 on 2026-09-02, v0.8.0-beta.1 on 2026-09-08, and v0.8.0 on 2026-09-10. Release cadence is not a quality signal on its own, but it does tell you the upgrade treadmill is real. You are pinning a daemon that talks to agent CLIs which change on their own schedules, so a Paseo upgrade can interact with an agent CLI upgrade in ways neither project controls.

Licensing needs care. The repository's `package.json` declares `"license": "Apache-2.0"`, while the repository metadata reports the licence as NOASSERTION. Those two do not agree, and the discrepancy is worth resolving with whoever handles licensing in your organisation before you build on it. The README also points at a `LICENSE` file at the repository root. I am not giving legal advice here; the point is simply that the two sources you would check first disagree, and that is a question for a human, not a guess.

The operational cost is mostly in the daemon. Everything the clients do depends on it being reachable, so it wants a stable address, a stable port (6767 in the documented Docker and remote-host examples) and a plan for credentials. The Docker route makes that explicit by mounting `/home/paseo` as a persistent volume, which is where credentials survive a container restart.

## Conclusion

Adopt Paseo if you already have at least one agent CLI configured and you want a single daemon that multiple people-shaped surfaces (desktop, phone, terminal, SDK) can talk to, especially if you work across more than one machine. Do not adopt it as a way to avoid installing agent CLIs: the README lists Claude Code, Codex, Copilot, OpenCode or Pi as a prerequisite, and the daemon only orchestrates what is already on the box. Before committing, verify three things against your own setup: that the Docker image can be extended with the agent CLI you use and its credentials, that the relay path you pick (end-to-end encrypted relay versus direct TCP, Tailscale or another VPN) matches your network, and that the plugin trust model is acceptable, since the README states plugins run with access to your daemon machine and inside connected clients.

## FAQ

### What is Paseo?

Paseo is a self-hosted orchestration layer for coding agents. A local daemon manages agent processes and exposes them over a WebSocket API to a desktop app, an Expo client for iOS and Android, a web app and the `paseo` CLI.

### How do I use Paseo with Claude Code and Codex together?

Install and authenticate at least one agent CLI first, then start the daemon and dispatch work with `paseo run --provider <name>`. The README's examples use `claude/opus-4.6` and `codex/gpt-5.5`, and the bundled `/paseo-handoff` skill is described as a way to plan with one agent and hand off to another.

### Can I run the Paseo daemon in Docker?

Yes. The README gives a `docker run` command that publishes port 6767, sets `PASEO_PASSWORD`, and mounts a persistent `/home/paseo` volume plus your workspace. The base image does not include the agent CLIs, so you extend it with the ones you use and provide credentials through environment variables or the mounted volume.

### Does Paseo work without the end-to-end encrypted relay?

Yes. On the CLI path Paseo asks whether to enable the relay for device pairing, and the README states that if you decline you connect directly over TCP, Tailscale or another VPN.

### What is the Paseo TypeScript SDK for?

The `@getpaseo/client` package is described as a way to build issue integrations, dashboards and orchestration services. The README example connects to a daemon at `ws://127.0.0.1:6767/ws`, creates an agent with a provider, working directory and prompt, and awaits the finished result.

### Is Paseo safe to extend with plugins?

The README states that plugins run with access to your daemon machine and inside connected clients, and advises installing only code you trust. Plugins can add themes, workspace panels, commands, settings screens and coding-agent providers, and are installed with `paseo plugin add <source>`.

## Sources

- [getpaseo/paseo on GitHub](https://github.com/getpaseo/paseo)
- [Issues](https://github.com/getpaseo/paseo/issues)
- [Project website](https://paseo.sh)
- [README](https://github.com/getpaseo/paseo/blob/main/README.md)
- [Releases](https://github.com/getpaseo/paseo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/getpaseo-paseo