Paseo Hub

Run coding agents from GitHub, Linear, 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 and run agents 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, Linear, Slack, Discord, or manual runs.
• One audit trail: See every event, configuration revision, execution, and result.

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

Quick start

You need Node.js and Paseo installed and running.

npx @getpaseo/hub

Open the local URL printed by Hub. Create the operator account, then follow the browser setup to connect GitHub, Slack, or Discord. Slack Socket Mode works without a public URL.

From the repository where agents should work, run:

paseo hub init

Choose the local Hub URL when prompted. The guided setup connects your daemon, uses the default project created during onboarding, detects the selected app connection, writes a safe starter workflow, validates it, and offers to deploy it.

See the Hub documentation for PostgreSQL, Docker, public URLs, environment-managed configuration, and production deployment.

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 under $XDG_DATA_HOME/paseo-hub, falling back to ~/.local/share/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.

Email delivery is optional too: set RESEND_API_KEY and RESEND_FROM to email organization invitations, signup verification links, and password-reset links through Resend. Configured instances require new password accounts to verify their email before sign-in. Without delivery configuration, managers retain the existing copy-and-share invitation workflow.

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 self-hosting guide for production deployment details. For Linear setup and workflows, see the public Linear app and Linear triggers guides.

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
  mode: full-access
  thinkingOptionId: high
  options:
    sandbox_workspace_write:
      writable_roots:
        - /var/cache/npm
      network_access: false

Options and modes are specific to the selected provider and are not portable. New triggers require an explicit mode; thinkingOptionId may be omitted to use the provider default. Hub always grants the execution-scoped finish_execution tool. Conversational triggers also receive an unlimited event-native reply tool for progress and final responses. 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.

Scheduled triggers

Choose Schedule in the trigger editor to run agents daily or on selected weekdays, at one or more local times. See scheduled triggers for setup, YAML, timezone rules, and recovery behavior.

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