flight

A flight is a catalog resource that defines a directed acyclic graph of agent tasks. Each flight belongs to a workspace and can be triggered automatically by events or on a cron schedule. See the multi-agent orchestration guide for a walkthrough. Flights use a markdown content format. You author a Markdown file with YAML frontmatter (between --- fences) and a body containing the agent task graph, then pipe it to murmur set flight. The server parses the content into structured fields on write.

Content format

The full flight document is a single Markdown file:

YAML frontmatter (between --- fences) declares workspace binding, event triggers, concurrency limits, and root agent configuration.
H1 heading names the flight.
Prose between H1 and the first H2 provides pilot-level notes — instructions that apply to the entire flight.
H2 headings define individual agent tasks. Each agent’s body is its prompt. Blockquote lines (> key: value) set agent metadata.

A flight with zero H2 agent sections is a “zero-agent flight” — the root agent does the work directly, configured by the frontmatter persona and model fields.

Frontmatter fields

Name	Type	Required	Description
`workspace`	string	yes	Name of the workspace this flight belongs to. Events from repos in the workspace trigger the flight.
`on`	object	no	Event triggers. See Triggers.
`max_concurrent`	int	no	Maximum parallel flight instances. `0` = unlimited. Default: `0`.
`persona`	string	no	Persona for the root agent in zero-agent flights.
`model`	string	no	Model override for the root agent (e.g. `claude-sonnet-4-6`). Empty uses the default.
`out`	string	no	Expected output artifact. Known values: `pr`, `push`, `respond`, `diff`, `report`, `none`. Any other value passes through to the agent verbatim.
`dequeue_strategy`	string	no	How the agent drains queued follow-ups between turns. Values: `all` (default), `one`, `five`.
`daemon`	bool	no	When `true`, the agent sleeps instead of auto-terminating after idle — for long-lived message processors. Default: `false`.
`disabled`	bool	no	When `true`, the flight is skipped during sync. Existing schedules are deleted; new ones are not created. Default: `false`.
`service_profile`	string	no	Name of a service profile for agents spawned by this flight. Required when the flight has triggers or `daemon: true`.

Agent metadata directives

Each H2 agent section supports blockquote metadata lines (> key: value):

Directive	Type	Description
`persona`	string	Agent persona name.
`model`	string	Model override (e.g. `claude-opus-4-6`).
`needs`	CSV	Upstream agent slugs. All must complete before this agent starts. Starts a new branch and VM — no inherited context.
`continues`	string	Upstream agent slug. Sends a follow-up to the same agent on the same branch and VM. Full context preserved. Mutually exclusive with `needs`.
`gate`	CSV	Completion criteria: `ci`, `review`, `approve`, `merge`.
`branch`	string	Explicit branch name. Auto-generated if omitted.
`each`	string	Collection description for fanout — one agent instance per item. Mutually exclusive with `continues`. An `each` agent cannot depend on another `each` agent.
`out`	string	Expected output: `pr`, `push`, `respond`, or freeform.

Triggers

The on: block declares event triggers. Each trigger names an event type, a list of repos (as clone URLs), and optional filters.

Event type	Repos required	Required filters	Optional filters
`issue_opened`	yes	—	`labels`
`pr_opened`	yes	—	`labels`
`pr_labeled`	yes	—	`labels`
`push`	yes	—	`branches`
`schedule`	no (must be omitted)	`cron`	—
`ci_failure`	yes	`check`, `branch`	—

Trigger repos must be clone URLs that exist in the flight’s workspace. The server validates this at write time.

Proto fields

These fields appear on the stored CatalogFlight resource. When you author via markdown content, the server populates them from the parsed frontmatter and body.

Name	Type	Required	Description
`name`	string	yes	Unique identifier within the tenant. DNS label format: `[a-z][a-z0-9-]{0,62}`.
`content`	string	—	Server-rendered full markdown (frontmatter + body). Read-only — regenerated on every write.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.
`workspace`	string	yes	Workspace name. Derived from the `workspace:` frontmatter field when content is provided.
`paused`	bool	no	Whether the flight is paused. Derived from `disabled:` in frontmatter.
`daemon`	bool	no	Whether this is a long-running daemon flight.
`triggers`	FlightTrigger[]	no	Event triggers. Derived from the `on:` frontmatter block.
`max_concurrent`	int32	no	Max concurrent instances. `0` = unlimited.
`persona`	string	no	Root agent persona for zero-agent flights.
`model`	string	no	Model override for the root agent.
`expected_output`	string	no	Expected output: `pr`, `push`, `respond`, `diff`, `report`, `none`, or freeform.
`prompt`	string	no	The flight document body (markdown after frontmatter). Contains the agent instructions.
`dequeue_strategy`	enum	no	Follow-up dequeue strategy: `all` (default), `one`, or `five`.
`service_profile`	string	no	Service profile for agents spawned by this flight.

You can write a flight either by piping markdown content (with frontmatter) or by setting structured fields directly. The two approaches are mutually exclusive — if content is provided, structured fields other than name must be empty.

Examples

Event-triggered flight with multiple agents

---
workspace: backend-team
service_profile: ci-bot
on:
  issue_opened:
    repos: [https://github.com/acme-corp/api]
    labels: [bug]
max_concurrent: 3
---

# Bug Fixer

## triage

> persona: architect
> out: respond

Analyze the bug report. Determine the root cause and outline a fix.

## implement

> needs: triage
> out: pr
> gate: ci

Implement the fix described in the triage phase. Open a pull request.

murmur set flight bug-fixer < bug-fixer.md

Zero-agent scheduled flight

---
workspace: platform
service_profile: nightly-bot
persona: programmer
model: claude-sonnet-4-6
out: pr
on:
  schedule:
    cron: "0 9 * * 1-5"
---

# Dependency Updates

Check for outdated dependencies and open a PR with version bumps.

murmur set flight dep-updates < dep-updates.md

CI failure flight

---
workspace: backend-team
service_profile: ci-bot
on:
  ci_failure:
    repos: [https://github.com/acme-corp/api]
    check: [TestSuite]
    branch: [main]
---

# CI Fix

## diagnose

> persona: programmer
> out: respond

Read the CI failure logs and identify the failing test and root cause.

## fix

> needs: diagnose
> out: pr
> gate: ci

Fix the failing test based on the diagnosis.

Fanout flight

---
workspace: backend-team
service_profile: ci-bot
---

# Fix All Failing Packages

## fix-package

> each: every Go package that has failing tests
> out: pr
> gate: ci

Fix the failing tests in this package: {}

Listing flights

murmur get flight

NAME          WORKSPACE      PAUSED  TRIGGERS
bug-fixer     backend-team   false   issue_opened
dep-updates   platform       false   schedule
ci-fix        backend-team   false   ci_failure

Reading a single flight

murmur get flight bug-fixer

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` for the flight.
`INVALID_ARGUMENT`	`name must match [a-z][a-z0-9-]{0,62}`	Use a DNS-label-format name: lowercase letters, digits, and hyphens.
`INVALID_ARGUMENT`	`description exceeds 1024 byte limit`	Shorten the `description` field.
`INVALID_ARGUMENT`	`content and structured fields are mutually exclusive`	Provide either markdown `content` or structured fields — not both.
`INVALID_ARGUMENT`	`parse flight content: <detail>`	The markdown content failed to parse. Check frontmatter syntax and agent metadata.
`INVALID_ARGUMENT`	`flight content missing required 'workspace:' in frontmatter`	Add a `workspace:` field to the YAML frontmatter.
`INVALID_ARGUMENT`	`either content or structured fields (with workspace) are required`	Provide markdown `content` or set the `workspace` field.
`INVALID_ARGUMENT`	`workspace "<name>" does not exist`	The referenced workspace does not exist. Create it first.
`INVALID_ARGUMENT`	`trigger <N>: unknown event type <value>`	Use a valid event type: `issue_opened`, `pr_opened`, `pr_labeled`, `push`, `schedule`, `ci_failure`.
`INVALID_ARGUMENT`	`trigger <N>: event trigger requires repos`	Non-schedule triggers must include a `repos` field with at least one clone URL.
`INVALID_ARGUMENT`	`trigger <N>: schedule trigger must not have repos`	Schedule triggers are time-based. Remove the `repos` field.
`INVALID_ARGUMENT`	`trigger <N>: invalid repo "<url>": <detail>`	The repo clone URL is malformed. Use a full clone URL (e.g. `https://github.com/org/repo`).
`INVALID_ARGUMENT`	`trigger <N>: ci_failure trigger requires a 'check' filter`	Add a `check` filter listing the CI check names to match.
`INVALID_ARGUMENT`	`trigger <N>: ci_failure trigger requires a 'branch' filter`	Add a `branch` filter listing the branches to match.
`INVALID_ARGUMENT`	`trigger <N>: schedule trigger requires a 'cron' filter`	Add a `cron` filter with a cron expression (e.g. `"0 9 * * 1-5"`).
`INVALID_ARGUMENT`	`trigger <N>: repo "<url>" is not in workspace "<name>"`	The trigger references a repo that is not in the flight’s workspace. Add the repo to the workspace or remove it from the trigger.
`INVALID_ARGUMENT`	`service_profile is required for triggered or daemon flights`	Flights with triggers or `daemon: true` must set `service_profile`.
`INVALID_ARGUMENT`	`service_profile "<name>" does not exist`	The referenced service profile does not exist. Create it first.
`INVALID_ARGUMENT`	`unknown dequeue_strategy "<value>" (valid: all, one, five)`	Use `all`, `one`, or `five` for the `dequeue_strategy` field.
`INVALID_ARGUMENT`	`invalid max_concurrent value`	`max_concurrent` must be a non-negative integer.
`INVALID_ARGUMENT`	`max_concurrent must be non-negative`	`max_concurrent` cannot be negative. Use `0` for unlimited.
`INVALID_ARGUMENT`	`flight has no H1 heading`	The markdown body must start with an H1 heading (`# Flight Name`).
`INVALID_ARGUMENT`	`multiple H1 headings`	Only one H1 heading is allowed per flight.
`INVALID_ARGUMENT`	`duplicate agent slug "<slug>"`	Each H2 agent section must have a unique name.
`INVALID_ARGUMENT`	`agent "<slug>" has both continues and needs (mutually exclusive)`	An agent can use `needs` or `continues`, not both.
`INVALID_ARGUMENT`	`agent "<slug>" has both each and continues (mutually exclusive)`	An `each` agent cannot also use `continues`.
`INVALID_ARGUMENT`	`agent "<slug>" continues unknown agent "<slug>"`	The `continues` target does not exist as an H2 section in this flight.
`INVALID_ARGUMENT`	`agents "<a>" and "<b>" both continue "<c>" (continues is 1:1)`	Only one agent can `continue` a given upstream agent.
`INVALID_ARGUMENT`	`agent "<slug>" needs unknown agent "<slug>"`	A `needs` dependency references an agent that does not exist in this flight.
`INVALID_ARGUMENT`	`agent "<slug>" needs each agent "<slug>" (nested each not supported)`	An `each` agent cannot depend on another `each` agent.
`INVALID_ARGUMENT`	`dependency cycle detected`	The agent dependency graph contains a cycle. Restructure the `needs` relationships.
`FAILED_PRECONDITION`	`cannot remove repo from workspace: flight trigger references it`	A flight trigger references a repo you are trying to remove from the workspace. Update or delete the flight first.

Flights — concept overview
Multi-agent orchestration — guide for building and running flights
Workspaces — the resource a flight belongs to
Agent personas — personas referenced in flight agent sections
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

Content format

Frontmatter fields

Agent metadata directives

Triggers

Proto fields

Examples

Event-triggered flight with multiple agents

Zero-agent scheduled flight

CI failure flight

Fanout flight

Listing flights

Reading a single flight

Errors

Getting Started

Core Concepts

Guides

Documentation Index

​Content format

​Frontmatter fields

​Agent metadata directives

​Triggers

​Proto fields

​Examples

​Event-triggered flight with multiple agents

​Zero-agent scheduled flight

​CI failure flight

​Fanout flight

​Listing flights

​Reading a single flight

​Errors

​Related

Content format

Frontmatter fields

Agent metadata directives

Triggers

Proto fields

Examples

Event-triggered flight with multiple agents

Zero-agent scheduled flight

CI failure flight

Fanout flight

Listing flights

Reading a single flight

Errors

Related