Mohamed BoudraandGitHub
dfd18a44a7
* feat(website): nest docs pages under landable groups The docs sidebar could already render groups from subdirectories in public-docs, but nothing used it because every doc was a flat file, and two things stopped it being usable. A group had no page of its own, so its label was only a toggle and its name came from the directory name via formatLabel. A directory's index.md now supplies the group's label, order, and href, which makes the group landable and lets the label be authored rather than derived. Categories and top-level directories named the same thing, so a categorised doc at hub/index.md produced a group nested inside its own category. Only directories below the top level become groups now. Also fixes two behaviours in the sidebar: - The open/closed effect assigned containsActive on every change, so a group you expanded to browse collapsed the moment you navigated anywhere else. Navigating in now opens a group and navigating away leaves it alone. - The sidebar scrolls independently of the page and never scrolled the active entry into view, so loading or refreshing a page far down the list left the sidebar parked at the top with no visible position. The group row is a single target: it navigates and expands, and collapses when clicked again from the page it points at. A separate chevron button would put two actions a few pixels apart. * docs(hub): document Hub Adds a Hub section covering what it is, how it works, daemons, triggers, configuration, activity, and the two ways to run it. The section separates using Hub from running it. Overview, quickstart, daemons, triggers, and configuration hold regardless of who operates the deployment; the self-hosting branch owns deploying the service and creating the GitHub, Slack, and Discord apps it talks to. That split falls on a real seam, because those apps are exactly what a hosted Hub would own on your behalf. Hosted is a placeholder until it ships. Each provider gets a trigger page carrying its events, filter semantics, and the full paseo.event.* reference for the data a prompt can read. That data is the thing a config author actually needs and the thing they cannot get from anywhere else. Every YAML block was parsed against the Hub config schema rather than eyeballed, which kept several plausible-looking things out of the docs: worktree prNumber takes a literal number and not a merge variable, only daemon environments run today, and github.push has no actor so it can never satisfy the required from_users filter. Troubleshooting moves to order 90 so it stays last. * refactor(website): let the active docs entry scroll itself into view The layout queried the sidebar for the active entry after every navigation, which coupled it to when that entry mounts. A link inside a collapsed group only mounts once the group's own effect opens it, so the query could run against a DOM that does not contain it yet. Moving the scroll to the entry removes the ordering question rather than answering it, and drops the ref and the cross-component query. Reported by Greptile on #2864. The failure it described does not reproduce: navigating from a page outside a collapsed group into one of its children still scrolls correctly, verified with the group confirmed collapsed and the sidebar forced to the top. The coupling was real even though the bug was not. * docs(hub): stop listing BETTER_AUTH_URL as required It falls back to PASEO_CLOUD_PUBLIC_URL, so a deployment that sets the public origin already has a correct auth base URL. Listing it as required made the Fly recipe look incomplete when it was not. Moved to optional with its default, and recorded what actually breaks without BETTER_AUTH_SECRET: the auth routes close and nobody can sign in. Reported by Codex on #2864, which read the same inconsistency the other way round and proposed adding the variable to the Fly example. * docs(hub): attach a database in the Fly recipe The Fly section showed inline config and a secrets command, neither of which supplied DATABASE_URL. It defaults to localhost:5432, which on Fly reaches nothing, so the documented deployment could not start. fly postgres attach sets DATABASE_URL as a secret, so the step is the attach itself rather than another variable to copy. Reported by Codex on #2864. * docs: align Hub self-hosting contract
6.1 KiB
title: hub.yml reference description: Every field in a Paseo Hub configuration: environments, triggers, filters, outputs, and merge variables. nav: hub.yml reference order: 69 category: Hub
hub.yml reference
The complete field reference for a Hub configuration. For where the file lives and how it activates, see Configuration.
environments: where agents run
triggers: what starts them
Both keys are required. environments needs at least one entry.
Environments
An environment says where an agent runs.
environments:
- name: dev
kind: daemon
daemon: my-macbook
cwd: /Users/you/code/your-repo
| Field | Required | Notes |
|---|---|---|
name |
yes | Referenced by a trigger's environment. |
kind |
yes | daemon. Only daemon environments run today. |
daemon |
yes | The daemon's display name, resolved to an id on activation. |
cwd |
yes | Absolute path on that machine. |
worktree |
no | Run in an isolated git worktree instead of cwd directly. |
Worktrees
worktree:
mode: branch-off
newBranch: hub/issue-${{ paseo.event.github.issue.number }}
base: main
Three modes:
| Mode | Fields | Behavior |
|---|---|---|
branch-off |
newBranch, optional base |
New branch off base, or the current head |
checkout-branch |
branch |
Existing branch |
checkout-pr |
prNumber |
The pull request's head |
newBranch, base, and branch accept merge variables. prNumber does not, because it is a literal number. For a per-event pull request use checkout-branch with ${{ paseo.event.github.pull_request.head.ref }}.
See Git worktrees for how the daemon sets them up.
Triggers
triggers:
- name: review
on: github.pull_request_review_comment
environment: dev
filters:
repo: acme/api
contains: "@paseo"
from_users: [alice, bob]
agent:
provider: codex
mode: full-access
prompt: ${{ paseo.event.github.comment.body }}
timeout: 45m
idle_timeout: 5m
auto_archive: true
| Field | Required | Default | Notes |
|---|---|---|---|
name |
yes | Unique within the configuration. | |
on |
yes | provider.event, see below. |
|
environment |
yes | An environment name. |
|
agent |
yes | provider, mode, optional model, thinkingOptionId. |
|
prompt |
yes | Supports merge variables. | |
filters |
yes | from_users is mandatory. See below. |
|
env |
no | Environment variables for the agent process. | |
allow_outputs |
no | none | Lets the agent reply to the source. |
timeout |
no | 1h |
Absolute wall clock. Max 24h. |
idle_timeout |
no | 5m |
Starts on the first idle report from the daemon. |
auto_archive |
no | false |
Archive the agent when the execution ends. |
Durations are a positive integer plus ms, s, m, or h.
agent.provider and agent.mode are the same identifiers the Paseo CLI uses, such as codex, claude, and full-access. See Supported providers.
Events and filters
on and filters decide which events reach a trigger. Both are documented in Triggers, with a page per provider for the events and data each one exposes.
filters is required, and from_users must be non-empty. Validation rejects a trigger without it.
Merge variables
${{ ... }} expressions are available in prompt, env, and worktree branch fields. Values reach the agent's process only through env; nothing else is injected.
Event data
${{ paseo.event.<provider>.<path> }} exposes the provider's own payload, unflattened. The full field list per provider lives with its trigger page: GitHub, Slack, Discord.
Manual runs expose actor, input, config, trigger, and delivery_id under paseo.event.manual.
Connection credentials
${{ paseo.connections.<slug>.token }} mints a token from a named connection. GitHub connections are the only ones that provide a token today.
Use it when a trigger needs a provider other than the one that fired it:
triggers:
- name: discord-fix
on: discord.mention
environment: dev
filters:
guild: "123456789"
from_users: ["987654321"]
agent:
provider: codex
mode: full-access
env:
GH_TOKEN: ${{ paseo.connections.acme-github.token }}
prompt: ${{ paseo.event.discord.trigger_message.body }}
You must name the connection. An organization can hold several GitHub installations and Hub will not guess between them.
GitHub-triggered executions already receive a scoped GH_TOKEN for the triggering repository. You do not need to map one.
Outputs
allow_outputs:
- type: slack.reply
slack.reply and discord.reply give the agent a reply tool for the conversation that triggered it. The reply is plain text, posted in-thread, and can be sent once per execution.
Every execution also gets finish_execution, whether or not allow_outputs is set.