2c9db5279c
* Add Docker images and agent Docker Mods Ship official container images that run the Paseo daemon headless. One Dockerfile parametrized by BASE_IMAGE covers Debian 12/13, Ubuntu 22.04/24.04 and Alpine; it bundles Node 22, the npm-published server + CLI, a vendored s6-overlay as PID 1, and a small Docker Mods loader. Agents are chosen at runtime via DOCKER_MODS (pipe-separated mod images). Each mod is a FROM scratch image carrying only an install hook that runs `npm install -g <agent-cli>`; the loader pulls the layers from the registry, extracts them, and runs the hook before the daemon starts, so any requested agent is on PATH when Paseo probes provider availability. - docker/base: Dockerfile, install scripts, s6 services, mods loader - docker/mods/*: claude-code, codex, copilot, opencode, pi - docker/docker-compose.example.yml + docker/README.md - .github/workflows/docker.yml: multi-arch (amd64/arm64) buildx matrix, publishes to ghcr.io/getpaseo on version tags - docs/docker.md + CLAUDE.md docs index row * feat(docker): print pairing QR and link on daemon startup Add an s6 oneshot service that waits for the daemon to listen, then runs `paseo daemon pair` so the pairing QR code and link surface in the container logs. Best-effort: never blocks boot, skips gracefully when relay is disabled. Opt out with PASEO_PAIRING_QR=0. * build(docker): add Arch image support * ci(docker): build Arch without Buildx * docs(docker): document paseo env contract * feat(docker): add opt-in sudo mode * docs(docker): link env references * fix(docker): create agent config dirs * fix(docker): default home to /home/paseo * docs(docker): document agent auth setup * docs(docker): document relay port setup * fix(docker): install Node from tarball * docs: add Docker quick start * docs(docker): remove legacy home example * docs(docker): set container hostname * fix(docker): prepare opencode storage * fix(docker): allow paseo login shell * fix docker opencode permissions * ci(docker): use Node 24 actions * fix(docker): install bzip2 runtime tools * fix(docker): update Pi mod package * fix(docker): quiet default daemon logs * fix(docker): split home from state Docker images now keep HOME at /home/paseo and store Paseo daemon state under /home/paseo/.paseo by default. Existing volumes can keep the old layout by setting PASEO_HOME=/home/paseo. * fix(docker): keep mods out of paseo home * ci(docker): skip alpine arm64 builds * fix(docker): address review findings * fix(docker): verify s6 overlay downloads * fix(docker): honor custom healthcheck port * fix(docker): fail on mod extraction errors * feat(docker): add official container image Ship a focused daemon image with the bundled web UI enabled and document extending it with agent CLIs. * ci(docker): publish images only on stable releases * fix(docker): check daemon health over HTTP --------- Co-authored-by: Herbrant <cdavide98carnemolla@gmail.com>
2.7 KiB
title, description, nav, order, category
| title | description | nav | order | category |
|---|---|---|---|---|
| Getting started | Install Paseo and start running coding agents from anywhere. | Getting started | 1 | Getting started |
Getting started
Paseo runs your coding agents on your machine and gives you a mobile, desktop, web, and CLI client to drive them from anywhere. Three common ways to install.
Desktop app (recommended)
Download from paseo.sh/download or the GitHub releases page. Open it and you're done.
The desktop app bundles its own daemon and starts it automatically, no separate install required. On first launch you'll see a brief startup screen, then connect from your phone by scanning the QR code in Settings.
Server / CLI
For headless machines, dev boxes, or any setup where you want the daemon running without the desktop UI:
npm install -g @getpaseo/cli
paseo
Paseo prints a QR code in the terminal. Scan it from the mobile app, or enter the daemon address manually from another client.
The daemon can also serve the browser web app itself, so you can use the full UI without the hosted app. See Self-hosting the web UI.
Configuration and local state live under PASEO_HOME (defaults to ~/.paseo).
Docker
For servers, dev boxes, NAS devices, or homelab hosts, run the official image:
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
Then open http://localhost:6767.
The image runs the daemon and serves the bundled web UI. It does not bundle agent CLIs, so extend it with the agents you use. See Docker for Compose, reverse proxy, agent install, and security examples.
Where next
- Docker, run the daemon and bundled web UI in a container.
- Workspaces, the project, workspace, and session model Paseo is built around.
- Providers, what a provider is and how Paseo wraps existing CLIs.
- CLI reference, every command.
- Self-hosting the web UI, serve the browser app from your own daemon.
- GitHub repo
- Report an issue
Prerequisites
Paseo manages other agents, it doesn't ship one. Before it's useful, install at least one provider CLI yourself and make sure it works with your credentials. See Supported providers for the full list.
You'll also want the GitHub CLI (gh) installed and authenticated, Paseo uses it for PR-aware worktrees and a few orchestration features.