Skip to content
Orbital
Menu
DocsExamplesReference
Get started
OverviewInstall OrbitalStart your first runBuild with AI
Concepts
How Orbital worksRunsWorkflowsDurability after restartsProjects and foldersHarnesses and modelsStyles and personas
Runs
Start a runWatch a runMessage a runPause, stop or resolve a runThe run queue
Workflows
Write your first workflowWrite promptsAdd branchesDecide with a modelAdd a loopRun steps in parallelReuse a workflowPass context between stepsAdd gates and waitsPush and open pull requestsRepeat a workflowOne-off workflows
Automate
TriggersMake a trigger ruleDelivery leadLead deliveryChats
Configure
Create a projectWorktrees and deliverySwitch a run's harnessUse different modelsGive steps a styleSettingsSet up decision modelsRun on your other computers
Connect agents
Connect a coding agentUse the shipped skillsCommand line
Troubleshooting
Troubleshooting
Changelog
Changelog

Run steps in parallel

Run independent review steps at once and collect their results

Run independent steps at the same time with a fan-out, then collect their results with a fan-in. In practice, independent work means reviews.

parallel-reviews.toml
[steps.reviews]
kind = "fan_out"
max_parallel = 2
join = "steps.collect"


[steps.reviews.clarity]
prompt = "Review the goal for clarity."
outputs.assessment = "text"
next = "steps.collect"


[steps.reviews.risks]
prompt = "Review the goal for risks."
outputs.assessment = "text"
next = "steps.collect"


[steps.collect]
kind = "fan_in"
prompt = "Summarise these reviews: {{ context.parallel.results['0'].context.assessment }} and {{ context.parallel.results['1'].context.assessment }}"

Orbital keeps each branch’s context apart, but not its files. Two branches that write to the same checkout will fight over it.

How the fan-out works

Section titled “How the fan-out works”

reviews is a fan-out, a step with kind = "fan_out". Each step inside it starts a branch, and a fan-out needs at least two. A fan-out can also name steps written elsewhere in the file, as branches = ["steps.clarity", "steps.risks"], and each of those starts a branch too. Up to max_parallel branches run at a time, four by default. Instead of next, a fan-out has join, which names the fan-in where the branches meet. Each branch runs from its step until it reaches that fan-in. A branch may not hold a gate, and its steps may not loop, set thread or send the run out of the branch.

Each branch keeps its own context, so clarity cannot read what risks produced. After the fan-in, results arrive under parallel.results in the order the fan-out names its branches, the branches list first and then the steps inside it in file order, with each branch’s step, outcome, failure reason and context. Each branch agent’s final prose is at its dotted ID, such as context.response.reviews.clarity. The fan-in prompt reads {{ context.parallel.results['0'].context.assessment }}. The index is quoted, and the complete example validates that spelling. A fan-in without a prompt is only the meeting point.

The editor shows a fan-out step with a maximum of three, three parallel steps below it, and a prompted fan-in step that combines their findings.
Every branch leaves the fan-out and meets again at the fan-in.

A fan-out can also ask a decision model which branches to start, and takes its default branches when none can answer.

Set max_parallel to the number of steps your harness can run at once. If branches must write, give them separate files and review the combined result after the fan-in.

Before you start

Section titled “Before you start”

You need a harness you have signed in to that can run two steps at once, and a project in Orbital. Any project works. It does not need to be a Git repository, unless you run the example with Codex, which needs one. See Projects and folders.

The branches share a folder, and their prompts ask only for a review of the goal. When branches must not change a shared folder, say so in their prompts. With Codex, a style can also give them a read-only sandbox with codex.sandbox_mode = "read-only".

1. Download the example

Section titled “1. Download the example”

Download the example and unpack it into ~/.orbital/workflows/. Keep every relative path.

reviews forks into clarity and risks; both meet at collect, which summarises them and reaches done.

parallel-reviews.toml
version = 3
entry = "steps.reviews"


[steps.reviews]
kind = "fan_out"
max_parallel = 2
join = "steps.collect"


[steps.reviews.clarity]
prompt = "Review the goal for clarity."
outputs.assessment = "text"
next = "steps.collect"


[steps.reviews.risks]
prompt = "Review the goal for risks."
outputs.assessment = "text"
next = "steps.collect"


[steps.collect]
kind = "fan_in"
prompt = "Summarise these reviews: {{ context.parallel.results['0'].context.assessment }} and {{ context.parallel.results['1'].context.assessment }}"
next = "steps.done"


[steps.done]
kind = "terminal"

Download parallel-reviews.toml

2. Validate it

Section titled “2. Validate it”
Terminal window
orbital validate ~/.orbital/workflows/parallel-reviews.toml

Validate again whenever you change where a branch starts or ends.

3. Run it

Section titled “3. Run it”

Choose New task, pick any project, and choose the parallel-reviews workflow and your harness. One project serves every example. Write the goal both reviews should assess, and start the run.

Both reviews run. Their assessment outputs stay inside parallel.results. The collect step summarises both before done.

Section titled “Related”