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.

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.