Paseo Hub

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

Docs · Paseo · Apache 2.0

Paseo Hub is the self-hosted automation layer for Paseo. Connect the services where work arrives, describe agents as code in .paseo/hub.yml, 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

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_HUB_AUTH_SECRET=replace-with-the-output-of-openssl-rand-hex-32
PASEO_BOOTSTRAP_ORGANIZATION=My organization
PASEO_BOOTSTRAP_OWNER_EMAIL=me@example.com
PASEO_BOOTSTRAP_OWNER_PASSWORD=replace-with-a-temporary-password

Billing is optional and hosted-only: 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, .paseo/hub.yml, Docker, and Fly deployment.

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.

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.

Apache-2.0