Paseo Hub

Run coding agents from GitHub, Slack, and Discord on your own Paseo daemons.

Docs · Paseo · Apache 2.0

Warning

Paseo Hub is in early development. Expect breaking changes and data loss. Join the Paseo Discord to learn more about the project.

Paseo Hub is the self-hosted automation layer for Paseo. Connect the services where work arrives, describe environments and agents in .paseo/hub.yml, define triggers under .paseo/workflows/, and run them on the machines where your development environments already live.

• Your machines: Hub dispatches to Paseo daemons on your laptop, devbox, or build server.
• Your configuration: Keep triggers, environments, permissions, and prompts in version control.
• Your services: Start agents from GitHub, Slack, Discord, or manual runs.
• One audit trail: See every event, configuration revision, execution, and result.

 GitHub ─┐                 ┌─ laptop
 Slack  ─┼─ Paseo Hub ────┼─ devbox
 Discord ┘                 └─ build server

Develop locally

You need Node.js and npm. A fresh checkout runs with an embedded database and no external services:

npm install
npm run dev

Open http://localhost:3000. Hub stores the embedded database and its generated authentication secret in .dev/paseo-hub and keeps both across restarts. Set PASEO_HUB_DATA_DIR to use a different directory, or set DATABASE_URL to use PostgreSQL instead:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/paseo_hub npm run dev

Embedded mode supports one Hub process per data directory. Docker Compose continues to run Hub with PostgreSQL.

Run with Docker Compose

You need Docker, Docker Compose, and a public HTTPS URL when connecting external providers.

git clone https://github.com/getpaseo/hub.git
cd hub
cp .env.example .env

Set these values in .env:

PASEO_HUB_APP_URL=https://hub.example.com
PASEO_BOOTSTRAP_ORGANIZATION=My organization
PASEO_BOOTSTRAP_OWNER_EMAIL=me@example.com
PASEO_BOOTSTRAP_OWNER_PASSWORD=replace-with-a-temporary-password

Hub generates and stores its authentication secret in the database. Advanced deployments may set PASEO_HUB_AUTH_SECRET to override it without replacing the stored secret.

Billing is optional: leave STRIPE_SECRET_KEY unset and Hub runs with no billing surface at all. See docs/billing.md.

Then start Hub and PostgreSQL:

docker compose up -d

Open PASEO_HUB_APP_URL, sign in with the bootstrap account, and replace its temporary password. Connect a daemon with:

paseo hub connect https://hub.example.com

The image is published as ghcr.io/getpaseo/hub:latest.

See the Hub documentation for provider setup, workflow configuration, Docker, and Fly deployment.

Provider options and Hub tools

Workflow steps may pass a JSON-compatible, provider-native agent.options object. Hub preserves the names and nesting exactly; the selected Paseo provider validates and applies them:

agent:
  provider: codex
  model: gpt-5.5
  thinkingOptionId: high
  options:
    sandbox_workspace_write:
      writable_roots:
        - /var/cache/npm
      network_access: false

Options are specific to the selected provider and are not portable. Omit mode to inherit the provider or daemon default. Tool preapproval is not configurable in Hub YAML: Hub grants only the execution-scoped MCP tools it materializes (finish_execution, plus an allowed output tool such as reply). Provider or machine policy still controls every unrelated tool. A read-only provider configuration is defense in depth; Hub output authorization remains enforced by the execution MCP server.

Public API

Each Hub serves a self-hosted API reference at /api/reference and its generated OpenAPI 3.1 contract at /api/openapi.json. The short public API guide covers CLI login, versioning, credential scopes, and request correlation.

License

Apache-2.0