paseo/public-docs/hub/configuration/hub-yml.md

---

title: hub.yml reference description: The authored Hub configuration: environments, triggers, typed inputs, workflow steps, routing, and prompt partials. nav: hub.yml reference order: 69 category: Hub

hub.yml reference

A configuration has environments and triggers. Execution fields belong to each trigger's steps.

environments:
  - name: development
    kind: daemon
    daemon: my-macbook
    cwd: /Users/you/code/project

triggers:
  - name: request
    on: manual.run
    max_runtime: 2h
    filters:
      from_users: [automation]
    steps:
      - id: work
        environment: development
        max_runtime: 90m
        idle_timeout: 10m
        agent:
          provider: codex
          mode: full-access
        prompt:
          - text: ${{ paseo.prompt }}

Environments

Field	Required	Notes
name	yes	Lowercase identifier referenced by a step.
kind	yes	daemon, fly, or docker in the authored schema; workflow steps must resolve to a daemon environment.
daemon	daemon only	Daemon name, resolved when the revision activates.
cwd	daemon only	Absolute path on the daemon.
image	fly/docker	Image name.
worktree	no	branch-off, checkout-branch, or checkout-pr target.

The worktree object is part of the environment. Its fields are exact authored names: newBranch and optional base for branch-off, branch for checkout-branch, and positive integer prNumber for checkout-pr.

Triggers

Field	Required	Notes
name	yes	Lowercase identifier, unique in the configuration.
on	yes	provider.event, such as slack.mention or manual.run.
max_runtime	yes	Positive duration for the complete trigger run, up to 24h.
filters	no in schema	Provider filters; externally sourced triggers still require a non-empty from_users allowlist.
inputs	no	Typed leading key=value invocation headers.
values	no	Derived expressions.
steps	yes	One or more ordered steps.

Inputs

Each input has:

inputs:
  repo:
    type: string
    required: false
    choices: [project, paseo]
  agent:
    type: string
    default: codex
    choices: [codex, claude]

type is string, number, or boolean. required, default, and choices are optional. required and default cannot be combined. Defaults and choices must match the declared type; a default must be one of the choices.

Inputs may be referenced as ${{ paseo.inputs.name }}. A dynamic authority-bearing field such as a provider, model, mode, or environment requires finite choices at activation. A prompt cannot supply authority.

Values

Values bind expressions under their own namespace:

values:
  selected_repo: ${{ paseo.inputs.repo ?? steps.classify.outputs.repo }}

The grammar supports paths, JSON literals, parentheses, !, ==, !=, &&, ||, and ??. It does not support function calls, JavaScript, arithmetic, mutation, or implicit string coercion. Referenced steps must exist and value dependencies cannot cycle.

Steps

Field	Required	Notes
id	yes	Lowercase step identifier, unique within the trigger.
environment	yes	Environment name or a finite input expression resolving to one.
max_runtime	yes	Positive step hard limit, up to 24h.
idle_timeout	yes	Positive idle limit, no longer than the step hard limit.
agent	yes	provider, optional model, mode, and thinkingOptionId.
prompt	yes	Non-empty list of text and GitHub-only include blocks.
if	no	Expression deciding whether this ordered step runs.
output	no	{ schema: <JSON Schema> } for structured finish_execution.
allow_outputs	no	Reply capabilities such as slack.reply, discord.reply, or github.reply, each with optional max.
auto_archive	no	Archives the step's agent when it ends.

Prompt blocks are objects, not a scalar prompt:

prompt:
  - text: Request: ${{ paseo.prompt }}
  - include: developer.md

Use ${{ paseo.prompt }}, ${{ paseo.inputs.* }}, ${{ steps.*.outputs.* }}, and ${{ values.* }} in prompts, conditions, and agent selection fields. Provider event payloads are not part of this workflow expression namespace; provider adapters put the normalized request into the prompt and preserve the raw event as evidence.

Prompt partials

include paths are relative to .paseo/partials/ and are resolved at the exact GitHub configuration commit. Hub stores the resolved content and SHA-256 hash in the immutable revision. Missing files, unsafe paths, symlinks, submodules, directories, and nested includes are rejected. Manual configurations cannot use repository partials.

Deadlines

The trigger's max_runtime is the hard limit for the complete workflow run. Each step also has max_runtime and idle_timeout:

max_runtime: 2h
steps:
  - id: classify
    max_runtime: 2m
    idle_timeout: 30s
  - id: implement
    max_runtime: 90m
    idle_timeout: 10m

The effective step hard and idle deadlines are capped by the remaining trigger deadline. Meaningful daemon activity refreshes idle time, but cannot extend a hard deadline. Hub persists absolute deadlines, so a restart or deployment does not reset them. A step timeout fails the run; a trigger timeout stops later steps and interrupts a live agent.

Provider invocation

The provider removes its mention or marker before Hub parses leading declared input tokens. Slack and Discord place the inputs immediately after the bot mention. GitHub places them after the configured marker. Manual runs send the same string as the API input:

@Paseo repo=project investigate the failed sync

The first token that is not a declared input begins the prompt. The clean prompt is available as ${{ paseo.prompt }}. The raw provider message remains separate Activity evidence. See provider triggers for provider-specific marker and filter behavior.

Removed fields

Do not put execution fields directly on a trigger. environment, agent, prompt, timeout, idle_timeout, auto_archive, and allow_outputs are step fields now. The duration field is max_runtime; timeout is not an alias.

Next: Hub workflows for routing patterns and copyable configurations.