Reference

Orchestration manifest

brainbase-orchestration.yaml is the committed source of truth for an orchestration's members, handoff edges, and schedule triggers. Member agents live under ./agents/<slug>/ and keep their own brainbase.agent.yaml files.

Cloud identity stays local

The orchestration id and revision are stored under .brainbase/, not in this manifest. An unlinked manifest can be claimed with brainbase orchestration create; pulling an existing orchestration creates both the manifest and its local link state.

Full example

brainbase-orchestration.yamlyaml

schema: 1
orchestration:
  name: Daily PR Janitor
  description: Closes stale PRs and reports the results
  credit_limit: 10
members:
  - slug: janitor
    name: PR Janitor
edges: []
triggers:
  - type: schedule
    node_id: 2d92a515-6f69-4e1e-9ba3-193de84151f4
    is_active: true
    config:
      cron_expression: "0 9 * * *"
    to:
      - agent: janitor
        description: Run the daily stale-PR pass

Folder layout

text

orchestration/
  brainbase-orchestration.yaml
  .brainbase/
  agents/
    janitor/
      brainbase.agent.yaml
      .brainbase/

Every members[].slug must match a folder under agents/. Before orchestration create or push, each member folder must contain a claimed agent with local link state.

orchestration

schemainteger · 1required

Manifest schema version. Must be 1.

orchestration.namestringrequired

Display name. Must be non-empty.

orchestration.descriptionstringoptional

Short description of the workflow.

orchestration.iconstringoptional

Icon identifier round-tripped from the cloud.

orchestration.icon_colorstringoptional

Icon color round-tripped from the cloud.

orchestration.credit_limitnumberoptional

Optional orchestration credit limit.

members

members[].slugstringrequired

Stable local alias for the member. It must match the directory name under agents/ and is used by edges and triggers.

members[].namestringoptional

Optional display label. The member agent manifest remains authoritative.

Member manifests are checked before anything is pushed

orchestration push applies the same rules as agent push to every member. If any member declares a block the CLI cannot sync — see Reserved fields — the whole run is refused before the first member is pushed and the graph is left unchanged. A member whose push fails for any other reason also stops the graph update, so a successful orchestration push means every member made it.

edges

edges[].frommember slugrequired

Source member. Self-loops are rejected.

edges[].tomember slugrequired

Destination member.

edges[].descriptionstringoptional

Human-readable handoff description.

edges[].payload_schemaobjectoptional

JSON Schema for the handoff payload. The server validates it.

edges[].settingsobjectoptional

Edge behavior settings, including task-permission options configured in the app. Pull and push preserve this object.

triggers

Schedule triggers are writable. App and other non-schedule triggers may appear after a pull as read-only context; orchestration push ignores those entries and reconciles only schedule triggers.

triggers[].typestringrequired

Use schedule for a writable CLI-managed trigger.

triggers[].node_idUUIDrequired

Stable trigger-node id. Schedule trigger ids must be UUIDs.

triggers[].is_activebooleanoptional

Whether the trigger fires. Defaults to false when omitted.

triggers[].config.cron_expressionstringrequired

Standard five-field cron expression.

triggers[].config.configured_propsobjectoptional

Integration-specific schedule configuration preserved when present. Author fields only when the trigger provider documents them.

triggers[].to[].agentmember slugrequired

Member agent started by this trigger.

triggers[].to[].descriptionstringoptional

Description passed with the trigger edge.

triggers[].to[].payload_schemaobjectoptional

Optional JSON Schema for the trigger payload.

Schedules belong to orchestrations

Agent manifests do not accept schedule triggers. A scheduled single-agent workflow is an orchestration with one member and a schedule trigger pointing to that member.