flight catalog resource

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. `"*"` fans out one instance per source workspace; it is valid only when every dispatch source is a `messages:` field or a `task_delegation` trigger.
`description`	string	no	Human-readable description shown in the dashboard. Maximum 1024 bytes.
`on`	object	no	Event triggers. See Triggers.
`max_concurrent`	int	no	Maximum parallel flight instances started by event and schedule triggers. `0` = unlimited. Events that arrive while the flight is at its cap are dropped, not queued. A flight with no event or schedule trigger rejects this field. Default: `0`.
`priority`	int	no	Dispatch priority. When multiple flights match the same event, only the highest-priority flight is spawned. Higher number wins; `0` is the default (lowest) priority. Must be non-negative. Two of your flights with the same priority and overlapping triggers are rejected at write time. 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: `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. Use this for long-lived message processors. Default: `false`.
`on_idle`	string	no	Idle behavior for spawned agents: `sleep` or `terminate`. Empty uses the default for the flight’s shape (daemon: `sleep`, one-shot: `terminate`). `daemon: true` with `on_idle: terminate` is rejected.
`suggest_terminate`	string	no	`murmur suggest-terminate` behavior for spawned agents: `suggest` or `immediate`. Empty uses the workspace default.
`completion_check`	string	no	Completion check for spawned agents: `none` or `assessor`. Empty uses the default for the flight’s shape (daemon: `none`, one-shot: `assessor`).
`idle_timeout`	string	no	How long a spawned agent waits idle before acting on its idle policy, as a positive Go duration (e.g. `45m`). Empty uses the launch context’s default: `1m` for a one-shot flight’s terminate-on-idle, the platform’s `20m` otherwise.
`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 `messages`, `daemon: true`, or any trigger other than `linear_delegation`. A flight triggered solely by `linear_delegation` may omit it; its agents then run as the person who delegated the issue, on that person’s own account settings and credentials.
`restrict_repository_access`	bool	no	When `true`, every agent this flight spawns is confined to the repositories that spawn involves: see Repository confinement. Accepts only `true` or `false`; any other value is rejected. A caller that triggers the flight synchronously may add the confinement to a flight that does not declare it, and can never remove one that does. On a `schedule` (cron) trigger each firing computes its own set, from the workspace as it stands at that tick. Default: `false`.
`tags`	string[]	no	Tags applied to every agent the flight spawns, in addition to the automatic `flight-<name>` tag. Written as a YAML list. Each is a DNS-label slug; unknown names are created. A flight whose name is too long to form a valid `flight-<name>` tag is rejected.
`messages`	object[]	no	Named message fields this flight registers, as a block list of `{field, from, description}` entries. Each field is injected into the structured output of every agent turn in its listen scope (`from`: a workspace name or `"*"`), and a non-null value at turn end is delivered to this flight. A flight with `messages` needs a `service_profile`.

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-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	none	`labels`
`issue_labeled`	yes	none	`labels`
`pr_opened`	yes	none	`labels`, `branches`
`pr_labeled`	yes	none	`labels`
`push`	yes	none	`branches`
`schedule`	no (must be omitted)	`cron`	`timezone`
`ci_failure`	yes	`check`, `branch`	none
`agent_feedback`	no (must be omitted)	none	`source_workspace`
`linear_delegation`	no (must be omitted)	none	`team`, `labels`, `project`
`webhook`	no (must be omitted)	`source` (a `webhook-source` name)	`type`, `match` (a CEL expression)
`task_delegation`	optional (empty = every repo)	none	none: filters are rejected

Trigger repos must be clone URLs that exist in the flight’s workspace. The server validates this at write time. A linear_delegation trigger fires when a Linear issue is delegated to the Macroscope agent. Its filters match three issue attributes: team (the issue’s team key, e.g. ENG), labels (one or more label names, all of which must be present), and project (the project name). All filters must match; a filterless trigger is a catch-all. See the Linear delegation guide.

Priority

When an event matches more than one flight, the highest-priority match wins and lower-priority matches are suppressed. 0 is the default and lowest priority, so a flight at priority: 100 beats one left at 0. This normally resolves to exactly one flight. A task_delegation request spanning several repositories is the exception. Flights with disjoint repos: lists may share a priority, so one request can match several at once. Dispatch then fails with FAILED_PRECONDITION instead of choosing arbitrarily. Give the flights distinct priorities or narrow their repos: lists to disambiguate them. Tenant flights take precedence over built-in murmur-* flights before priority is considered. If any tenant flight matches an event, matching built-ins are shadowed and do not run. You can therefore override a built-in by writing a flight that matches the same event at any priority. Priority orders flights only within the tenant or built-in class. A tenant flight at priority: 0 still beats a matching built-in at priority: 100. Two tenant flights may not share a priority when their triggers overlap, meaning that one event could match both. The server rejects such a write. This check does not apply to overlap with a built-in murmur-* flight because a tenant flight always shadows the built-in. For repo-scoped event types, two triggers overlap when they share an event type, their repositories overlap, and their filters can both be satisfied. Repo-less event types, such as linear_delegation, are compared by their filters. For task_delegation, the optional repos: list also affects overlap. repos: [] matches every repository, while non-empty lists overlap only when their canonical repositories intersect. Two task_delegation flights with disjoint repository lists may therefore share a priority. Only filters that the server treats as single-valued can make two same-priority flights disjoint. For the events described here, those keys are branch and check, and the flights must require different values. For example, a ci_failure flight on branch: main and another on branch: dev may share a priority. Every other filter is treated as multi-valued for this check, so different values do not make flights disjoint. The labels filter is multi-valued: a PR can carry both labels: [bug] and labels: [feature], so those filters overlap. Although each Linear issue has one team, linear_delegation does not treat team as disjointing, so team: ENG and team: OPS cannot share a priority. Give those flights distinct priorities instead. schedule triggers run on their own timers, outside event dispatch, so priority does not arbitrate them and they never overlap.

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	none	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.
`priority`	int32	no	Dispatch priority. Highest matching flight wins. Default is `0` (lowest priority). See Priority.
`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: `auto` (default), `all`, `one`, or `five`.
`restrict_repository_access`	bool	no	Whether agents this flight spawns are confined to the repositories their spawn involves. Derived from `restrict_repository_access:` in frontmatter.
`on_idle`	string	no	Idle behavior for spawned agents: `sleep` or `terminate`. Empty uses the default for the flight’s shape (daemon: `sleep`, one-shot: `terminate`). `daemon: true` with `on_idle: terminate` is rejected.
`suggest_terminate`	string	no	`murmur suggest-terminate` behavior for spawned agents: `suggest` or `immediate`. Empty uses the workspace default.
`completion_check`	string	no	Completion check for spawned agents: `none` or `assessor`. Empty uses the default for the flight’s shape (daemon: `none`, one-shot: `assessor`).
`idle_timeout`	string	no	Idle timeout for spawned agents as a Go duration (e.g. `45m`): how long a pilot waits idle after a turn a person started or interacted with. A machine-triggered turn keeps the idle deadline at least one minute after it finishes, or for the configured idle timeout if that is shorter; it never moves an existing deadline earlier. Derived from the `idle_timeout:` frontmatter field.
`service_profile`	string	no	Service profile for agents spawned by this flight.
`tags`	string[]	no	Tags applied to every agent the flight spawns, on top of the automatic `flight-<name>` tag. Derived from the `tags:` frontmatter list.
`messages`	FlightMessageField[]	no	Message fields the flight registers. Derived from the `messages:` frontmatter list.

You can write a flight by piping Markdown with frontmatter or by setting structured fields directly. When structured fields are present, they are the source of truth. The server ignores any content in the request and re-renders content from the structured fields on every write. Provide content without structured fields to author the flight as Markdown.

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: murmur-planner
> 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

Issue-labeled flight

Fires when a matching label is added to an existing issue. This example hands an issue to an agent when you add the murmur label:

---
workspace: backend-team
service_profile: ci-bot
persona: murmur-programmer
out: pr
on:
  issue_labeled:
    repos: [https://github.com/acme-corp/api]
    labels: [murmur]
---

# Issue Handler

Read the issue and implement a fix. Open a pull request referencing the
issue number.

murmur set flight issue-handler < issue-handler.md

Zero-agent scheduled flight

---
workspace: platform
service_profile: nightly-bot
persona: murmur-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: murmur-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.

Linear delegation flight

---
workspace: backend-team
service_profile: linear-bot
persona: murmur-programmer
out: pr
priority: 10
on:
  linear_delegation:
    team: ENG
    labels: [agent-ready]
---

# Backend Ticket Handler

Work the delegated issue. Keep the change minimal and open a pull request
referencing the ticket identifier.

murmur set flight backend-tickets < backend-tickets.md

See the Linear delegation guide for the end-to-end flow.

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

bug-fixer
ci-fix
dep-updates

The list prints one name per line, with no header. A disabled built-in murmur-* flight prints with a (disabled — re-enable: murmur set flight <name>) marker.

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`	`workspace is required: pin the flight to a workspace (workspace: <name>) or fan out one instance per source workspace (workspace: "*")`	Set the `workspace` field.
`INVALID_ARGUMENT`	`flight content is server-rendered and cannot be patched; patch structured fields, or replace the resource with 'murmur set'`	`content` cannot appear in a patch update mask: patch structured fields (`model`, `paused`, etc.), or replace the whole resource with `murmur set`.
`INVALID_ARGUMENT`	`parse flight content: <detail>`	The markdown content failed to parse. Check frontmatter syntax and agent metadata.
`INVALID_ARGUMENT`	`either content or structured fields are required`	Provide markdown `content` or structured fields.
`INVALID_ARGUMENT`	`workspace "<name>" does not exist`	The referenced workspace does not exist. Create it first.
`INVALID_ARGUMENT`	`unknown event type "<value>"`	Use a valid event type: `issue_opened`, `issue_labeled`, `pr_opened`, `pr_labeled`, `push`, `schedule`, `ci_failure`, `agent_feedback`, `linear_delegation`, `webhook`, `task_delegation`.
`INVALID_ARGUMENT`	`trigger <event> requires a 'repos' field`	Repo-scoped event triggers (`issue_opened`, `issue_labeled`, `pr_opened`, `pr_labeled`, `push`, `ci_failure`) must include a `repos` field with at least one clone URL. `schedule`, `agent_feedback`, `linear_delegation`, and `webhook` triggers must not include `repos`.
`INVALID_ARGUMENT`	`<event> trigger must not have 'repos'`	The trigger is not repo-scoped (`schedule`, `agent_feedback`, `linear_delegation`, `webhook`). Remove the `repos` field.
`INVALID_ARGUMENT`	`trigger <event>: invalid repo "<url>": <detail>`	The repo clone URL is malformed. Use a full clone URL (e.g. `https://github.com/org/repo`).
`INVALID_ARGUMENT`	`ci_failure trigger requires a 'check' filter`	Add a `check` filter listing the CI check names to match.
`INVALID_ARGUMENT`	`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`	`linear_delegation trigger "<filter>" filter takes a single non-empty value (no surrounding whitespace)`	`team` and `project` filters take exactly one value with no surrounding whitespace.
`INVALID_ARGUMENT`	`linear_delegation trigger 'labels' filter must list at least one label`	Provide at least one non-empty label name, or omit the `labels` filter.
`INVALID_ARGUMENT`	`linear_delegation trigger only accepts 'team', 'labels', and 'project' filters; got "<key>"`	Remove the unsupported filter key.
`INVALID_ARGUMENT`	`invalid priority value`	`priority` must be an integer.
`INVALID_ARGUMENT`	`priority must be non-negative, got <N>`	Use `0` or higher for `priority`.
`INVALID_ARGUMENT`	`flight "<a>" shares priority <N> with flight "<b>" and has an overlapping <event> trigger; flights that can match the same event must have distinct priorities`	Two flights at the same priority could match the same event. Give them distinct `priority` values.
`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 daemon, message-registering, and machine-triggered flights; only a flight triggered solely by linear_delegation may omit it ...`	Nobody invokes an individual run of a daemon, a `messages` flight, or a flight on a schedule or repository trigger, so each needs a `service_profile` to run as. Set one, or narrow the flight to `linear_delegation` alone.
`INVALID_ARGUMENT`	`restrict_repository_access must be true or false, got "<value>"`	The frontmatter value was something else (`yes`, `1`, `True`). Use `true` or `false`.
`INVALID_ARGUMENT`	`service_profile "<name>" does not exist`	The referenced service profile does not exist. Create it first.
`INVALID_ARGUMENT`	`persona "<name>" does not exist`	The frontmatter `persona` must name an existing agent-persona. Platform personas are named `murmur-*` (for example `murmur-programmer`).
`INVALID_ARGUMENT`	`unknown dequeue_strategy "<value>" (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, got <N>`	`max_concurrent` cannot be negative. Use `0` for unlimited.
`INVALID_ARGUMENT`	`max_concurrent requires an event or schedule trigger to throttle ...`	Remove `max_concurrent`, or use `daemon: true` for backpressure.
`INVALID_ARGUMENT`	`unknown on_idle "<value>" (valid: sleep, terminate)`	Use `sleep` or `terminate`. The same shape applies to `suggest_terminate` (`suggest`, `immediate`) and `completion_check` (`none`, `assessor`).
`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 "<url>" from workspace "<name>": flight "<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
Linear delegation: routing delegated Linear issues through 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

flight catalog resource

Content format

Frontmatter fields

Agent metadata directives

Triggers

Priority

Proto fields

Examples

Event-triggered flight with multiple agents

Issue-labeled flight

Zero-agent scheduled flight

CI failure flight

Linear delegation flight

Fanout flight

Listing flights

Reading a single flight

Errors

​Content format

​Frontmatter fields

​Agent metadata directives

​Triggers

​Priority

​Proto fields

​Examples

​Event-triggered flight with multiple agents

​Issue-labeled flight

​Zero-agent scheduled flight

​CI failure flight

​Linear delegation flight

​Fanout flight

​Listing flights

​Reading a single flight

​Errors

​Related

Content format

Frontmatter fields

Agent metadata directives

Triggers

Priority

Proto fields

Examples

Event-triggered flight with multiple agents

Issue-labeled flight

Zero-agent scheduled flight

CI failure flight

Linear delegation flight

Fanout flight

Listing flights

Reading a single flight

Errors

Related