Skip to content
Orbital
Menu
DocsExamplesReference
Get started
OverviewInstall OrbitalStart your first runBuild with AI
Concepts
How Orbital worksRunsWorkflowsDurability after restartsProjects and foldersHarnesses and modelsRoles and tool access
Runs
Start a runWatch a runMessage a runPause, stop or resolve a runThe run queue
Workflows
Write your first workflowWrite promptsAdd branchesAdd a loopRun steps in parallelReuse a workflowPass context between stepsAdd gates and waits
Automate
TriggersMake a trigger ruleSupervisorLead delivery with a supervisorChats
Configure
Create a projectWorktrees and deliverySwitch a run's harnessUse different modelsGive steps a roleSettings
Connect agents
Connect a coding agentUse the shipped skillsCommand line
Troubleshooting
Troubleshooting

The run queue

Orbital runs a set number of runs at once and queues the rest

You set how many runs Orbital works on at once, two unless you change it. Each working run holds one run slot, and the other runs wait in the queue until a slot frees up. A project can also have its own limit.

Change the number of runs at work

Section titled “Change the number of runs at work”

  1. Open Settings.

    Go to Settings > General.

  2. Set Concurrent runs.

    Under Concurrent runs, choose − or +, or type a number from 1 to 16.

    The General settings page, with Appearance, Concurrent runs, Queue method, Default workflow, Default harness and other settings.The General settings page, with Appearance, Concurrent runs, Queue method, Default workflow, Default harness and other settings.
    Concurrent runs sets how many runs work at once.

The page shows how many slots are in use now. A change applies at once. Lowering the number never stops a run that is already working. The queue waits longer instead.

Each run can make many agent turns at once, for example in parallel steps. The number counts runs, not turns.

Choose the queue method

Section titled “Choose the queue method”

The queue method decides what a run does with its slot while it waits for you or for a pull request.

  1. Open Settings.

    Go to Settings > General.

  2. Choose a Queue method.

    Under Queue method, choose one:

    • Interleave, the default. While a run waits for you or for a pull request, another run can use its slot.
    • Finish first. A new run starts only when an earlier run has finished.

The choice saves at once and applies at the next decision, without a restart. Switching to Interleave lets queued runs into the slots that paused runs were holding. Switching to Finish first stops nothing that is already working.

Under Finish first, a queued run’s page says “Waiting for a run to finish”, with its place. A paused run, or one at a gate, says “Holding its slot until it finishes”.

Limit one project’s runs

Section titled “Limit one project’s runs”

Give a project its own limit, so a project with a long backlog does not take every slot.

  1. Open the project.

    Open Projects and choose the project.

  2. Set the run limit.

    Under Runs, set Run limit with − and +, or type a number and press Enter. It saves at once.

    A project page with its folders table and the Runs limit field.
    The run limit applies to this project only.

Leave the field empty for no limit of its own. The number in Settings > General stays the upper limit across all projects, and the project page shows it, for example “Orbital allows 4 at a time overall.” A project limit at or above that number changes nothing, and the page says so.

A change applies at the next decision, without a restart. Lowering the limit never stops a run that is already working.

A queued run held back by its project’s limit shows “Queued · waiting for a free slot in project” instead of its place.

What holds a slot

Section titled “What holds a slot”

A run takes a slot when it starts. It keeps the slot through every step: agent turns, commands, checks, parallel branches, timed waits and questions the agent asks you.

Under Interleave, a run gives its slot back when:

  • it reaches a human gate (Waiting, “At a gate”);
  • it stops by itself and shows “Waiting on you”, or you pause it (Paused);
  • it ends.

A delivery workflow waiting for its pull request to be reviewed sits at a human gate, so it holds no slot. Many runs can wait on review while others work.

Under Finish first, a run keeps its slot until it ends, through gates, pauses and waits on you. Stopping a run, or resolving it, frees its slot under either method.

Order in the queue

Section titled “Order in the queue”

When a slot frees, Orbital skips projects that are at their own limit. It gives the slot to the project that has waited longest since it last got one, so projects take turns. Within one project, runs start in the order they joined the queue. A queued run’s badge shows its place, such as “Queued · 2nd”.

To start a queued run next, open Runs, open its row’s menu (⋯) and choose Move to front of queue.

A run that comes back from a gate or a pause joins the back of the queue and shows “Continuing when a slot is free”. A paused run therefore loses its place. When you resume it, it joins the back.

After a restart

Section titled “After a restart”

The queue is stored with the run history. After a restart, the runs that were working take their slots back first, even beyond the number you set. Queued runs keep their order.

Section titled “Related”