> ## Documentation Index > Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt > Use this file to discover all available pages before exploring further. # flight > Catalog resource that defines a multi-agent orchestration plan — event triggers, cron schedules, root agent persona, and a DAG of agent tasks. A [flight](/concepts/flights) is a catalog resource that defines a directed acyclic graph of agent tasks. Each [flight](/concepts/flights) belongs to a [workspace](/concepts/workspaces) and can be triggered automatically by events or on a cron schedule. See the [multi-agent orchestration guide](/guides/multi-agent-orchestration) for a walkthrough. [Flights](/concepts/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](/concepts/flights) 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](/concepts/flights). * **Prose between H1 and the first H2** provides pilot-level notes — instructions that apply to the entire [flight](/concepts/flights). * **H2 headings** define individual agent tasks. Each agent's body is its prompt. Blockquote lines (`> key: value`) set agent metadata. A [flight](/concepts/flights) with zero H2 agent sections is a "zero-agent [flight](/concepts/flights)" — 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](/concepts/workspaces) this [flight](/concepts/flights) belongs to. Events from repos in the [workspace](/concepts/workspaces) trigger the [flight](/concepts/flights). | | `on` | object | no | Event triggers. See [Triggers](#triggers). | | `max_concurrent` | int | no | Maximum parallel [flight](/concepts/flights) instances. `0` = unlimited. Default: `0`. | | `persona` | string | no | [Persona](/concepts/agent-personas) for the root agent in zero-agent [flights](/concepts/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: `auto` (default — up to five follow-ups of one kind per turn; manual and auto-generated events never share a turn), `all`, `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](/concepts/flights) 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](/concepts/flights). Required when the [flight](/concepts/flights) has triggers or `daemon: true`. | | `tags` | string\[] | no | [Tags](/catalog/tag) applied to every agent the [flight](/concepts/flights) spawns, in addition to the automatic `flight-` tag. Written as a YAML list. Each is a DNS-label slug; unknown names are created. A [flight](/concepts/flights) whose name is too long to form a valid `flight-` tag is rejected. | ## Agent metadata directives Each H2 agent section supports blockquote metadata lines (`> key: value`): | Directive | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `persona` | string | Agent [persona](/concepts/agent-personas) name. | | `model` | string | Model override (e.g. `claude-opus-4-8`). | | `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](/concepts/flights) [workspace](/concepts/workspaces). 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](/concepts/workspaces) name. Derived from the `workspace:` frontmatter field when content is provided. | | `paused` | bool | no | Whether the [flight](/concepts/flights) is paused. Derived from `disabled:` in frontmatter. | | `daemon` | bool | no | Whether this is a long-running daemon [flight](/concepts/flights). | | `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](/concepts/agent-personas) for zero-agent [flights](/concepts/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](/concepts/flights) document body (markdown after frontmatter). Contains the agent instructions. | | `dequeue_strategy` | enum | no | Follow-up dequeue strategy: `auto` (default), `all`, `one`, or `five`. | | `service_profile` | string | no | Service profile for agents spawned by this [flight](/concepts/flights). | | `tags` | string\[] | no | [Tags](/catalog/tag) applied to every agent the [flight](/concepts/flights) spawns, on top of the automatic `flight-` tag. Derived from the `tags:` frontmatter list. | You can write a [flight](/concepts/flights) 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 ```markdown theme={null} --- 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. ``` ```bash theme={null} murmur set flight bug-fixer < bug-fixer.md ``` ### Zero-agent scheduled flight ```markdown theme={null} --- 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. ``` ```bash theme={null} murmur set flight dep-updates < dep-updates.md ``` ### CI failure flight ```markdown theme={null} --- 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 ```markdown theme={null} --- 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 ```bash theme={null} 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 ```bash theme={null} murmur get flight bug-fixer ``` ## Errors | Code | Meaning | What to do | | --------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `INVALID_ARGUMENT` | `name is required` | Provide a `name` for the [flight](/concepts/flights). | | `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: ` | 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 "" does not exist` | The referenced [workspace](/concepts/workspaces) does not exist. Create it first. | | `INVALID_ARGUMENT` | `trigger : unknown event type ` | Use a valid event type: `issue_opened`, `pr_opened`, `pr_labeled`, `push`, `schedule`, `ci_failure`. | | `INVALID_ARGUMENT` | `trigger : event trigger requires repos` | Non-schedule triggers must include a `repos` field with at least one clone URL. | | `INVALID_ARGUMENT` | `trigger : schedule trigger must not have repos` | Schedule triggers are time-based. Remove the `repos` field. | | `INVALID_ARGUMENT` | `trigger : invalid repo "": ` | The repo clone URL is malformed. Use a full clone URL (e.g. `https://github.com/org/repo`). | | `INVALID_ARGUMENT` | `trigger : ci_failure trigger requires a 'check' filter` | Add a `check` filter listing the CI check names to match. | | `INVALID_ARGUMENT` | `trigger : ci_failure trigger requires a 'branch' filter` | Add a `branch` filter listing the branches to match. | | `INVALID_ARGUMENT` | `trigger : schedule trigger requires a 'cron' filter` | Add a `cron` filter with a cron expression (e.g. `"0 9 * * 1-5"`). | | `INVALID_ARGUMENT` | `trigger : repo "" is not in workspace ""` | The trigger references a repo that is not in the [flight's](/concepts/flights) [workspace](/concepts/workspaces). Add the repo to the [workspace](/concepts/workspaces) or remove it from the trigger. | | `INVALID_ARGUMENT` | `service_profile is required for triggered or daemon flights` | [Flights](/concepts/flights) with triggers or `daemon: true` must set `service_profile`. | | `INVALID_ARGUMENT` | `service_profile "" does not exist` | The referenced service profile does not exist. Create it first. | | `INVALID_ARGUMENT` | `unknown dequeue_strategy "" (valid: auto, all, one, five)` | Use `auto`, `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](/concepts/flights). | | `INVALID_ARGUMENT` | `duplicate agent slug ""` | Each H2 agent section must have a unique name. | | `INVALID_ARGUMENT` | `agent "" has both continues and needs (mutually exclusive)` | An agent can use `needs` or `continues`, not both. | | `INVALID_ARGUMENT` | `agent "" has both each and continues (mutually exclusive)` | An `each` agent cannot also use `continues`. | | `INVALID_ARGUMENT` | `agent "" continues unknown agent ""` | The `continues` target does not exist as an H2 section in this [flight](/concepts/flights). | | `INVALID_ARGUMENT` | `agents "" and "" both continue "" (continues is 1:1)` | Only one agent can `continue` a given upstream agent. | | `INVALID_ARGUMENT` | `agent "" needs unknown agent ""` | A `needs` dependency references an agent that does not exist in this [flight](/concepts/flights). | | `INVALID_ARGUMENT` | `agent "" needs each agent "" (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](/concepts/flights) trigger references a repo you are trying to remove from the [workspace](/concepts/workspaces). Update or delete the [flight](/concepts/flights) first. | ## Related * [Flights](/concepts/flights) — concept overview * [Multi-agent orchestration](/guides/multi-agent-orchestration) — guide for building and running [flights](/concepts/flights) * [Workspaces](/concepts/workspaces) — the resource a [flight](/concepts/flights) belongs to * [Agent personas](/concepts/agent-personas) — personas referenced in [flight](/concepts/flights) agent sections * [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources * [`murmur get`](/cli/get) — CLI command for reading catalog resources