> For the index of every page in Orbital's docs, read https://docs.beta.runorbital.dev/llms.txt.

# How Orbital works

> How a run carries out a workflow, step by step, with the coding agents you already use

You give Orbital a goal, a [workflow](/workflows/) and a [project](/projects/), and it starts a [run](/runs/). The run carries out the workflow one step at a time, hands each agent step to a coding agent you already use, and records every result, so you can follow it, steer it and pick it up after a restart.

![A run page with an agent step selected, showing the step's prompt, the agent's answer and the values it recorded, with run facts, pull requests and the list of steps on the right.](/screenshots/run-hero.webp?v=4fa21a573c)

*Most ideas meet on the run page: the run, its workflow's steps, its harness and its project.*

## A run works one step at a time

A workflow is a DOT file of steps and the edges between them. Its `entry` names the first step. From there, the run takes one step at a time:

- An agent step fills in its prompt and sends it to a harness.
- A command step records facts it reads from your machine, such as the state of a pull request.
- The edges leaving a step choose what happens next.
- A terminal step ends the run.

The harness is the coding agent that does an agent step: Claude Code, Codex or OpenCode. A step takes its harness, model and effort together from one place: its model settings, its role or the workflow's blocks, else the run's harness. [Which harness a step uses](/harnesses/#which-harness-a-step-uses) gives the order. The transcript shows the harness and model each step used.

![The run page's Waterfall tab shows each step as a bar on a timeline with its duration, including repeated visits such as probe@2 and wait@2.](/screenshots/run-steps.webp?v=fee718c962)

*Each visit to a step is its own bar; a repeat visit carries a number such as @2.*

## What a run remembers

A run begins with its goal and declared inputs. Its context holds those values, accepted agent outputs, command facts and each step's outcome. Prompts read context. Conditions on edges only read values available on their path through the workflow. [Pass context between steps](/workflows/pass-context/) explains what a step can read.

Agent outputs are checked, structured data. Orbital does not scrape them from the agent's prose. An `outputs` declaration tells Orbital which keys and types to accept. The agent's final response stays available under `context.response.<node>`.

Built-in probes only observe. A `parallelogram` with `probes="pr"` reads each repository folder's current pull request from GitHub. Script commands are different: they run your shell command once in the primary folder and declare their own typed facts.

![The run page's Context tab lists fourteen values held by the run, such as pr.state and summary, each with the step that set it on the right.](/screenshots/run-context.webp?v=3e79bd8607)

*Each context value shows the step that set it.*

## Runs carry on after a restart

Orbital keeps every run's progress, context and transcript in `~/.orbital/run-history.db`. `ORBITAL_HOME` moves it to `$ORBITAL_HOME/.orbital`.

Closing the browser leaves the server running. When Orbital restarts, every run you did not pause carries on from its last finished activity, with the context it had:

- A finished step does not run again.
- A wait wakes at the time it first set.
- An agent turn continues its session.

The message an agent was writing when Orbital restarted may be lost. A tool call that was running may run again.

A paused run stays paused until you resume it. **Resume** carries the step on in the same agent session. **Retry** starts the step again as a new visit.

A run keeps the workflow as it was when the run started, and the harness you picked for it. Orbital rereads a prompt file before a later visit. If your edit is invalid, it keeps the checked prompt. [Durability after restarts](/runs/durability/) covers restarts in full.

## You can steer a live run

Open the run and read the active step and its transcript. Send a message when the agent needs a correction. A message you queue reaches the agent whole in its next turn that can take it, even when the history sent with that turn is shortened. Harnesses differ in whether they can take a message during a live turn. [Message a run](/runs/message-a-run/) shows how.

[Pause](/runs/control-a-run/) the run to stop its current work before you change direction. Answer questions and permission requests on the run page. During a wait, skip the remaining time only when the observation should run again now.

:::caution
A manual jump changes the next step and may lack context that normal routing would have produced. Read its warnings before you confirm. Use normal routing when it already expresses the correction you need.
:::

## When a step fails

What happens depends on where the failure is:

| Failure | Result |
| --- | --- |
| A step fails and a failure edge matches | The run takes the edge and may recover. |
| A step fails and no failure edge matches | The run is Paused and shows "Waiting on you" until you act. |
| A terminal step fails | The run ends as Failed. |

These are different [standings](/runs/#standings), so check both the standing and the transcript. [Error handling](/reference/error-handling/) gives the exact rules. [Troubleshooting](/troubleshooting/) explains how to recognise each state in the app.

![The run page's Waterfall tab highlights a failed command step with its error output and a red Stopped with an error box, followed by Run ended: failed.](/screenshots/run-current-step.webp?v=cf3386ca9f)

*The failed step is highlighted, with the error that stopped it.*

## Quick reference

| Idea | What it is |
| --- | --- |
| [Run](/runs/) | One workflow carried out for one project, towards one goal. Orbital keeps its full history, and you can follow, message, pause and resume it. |
| [Workflow](/workflows/) | One DOT file of steps and the edges between them. Orbital loads, validates and runs it, and ships eight of its own. |
| [Node](/reference/node-types/) | One step of a workflow. Its shape decides what it does. There are eight kinds, from agent steps to gates and fan-outs. |
| [Gates and waits](/workflows/gates-and-waits/) | A gate stops a run until a person lets it continue. A wait stops it for a set time. Both survive a restart. |
| [Run queue](/runs/queue/) | Orbital works on at most a set number of runs at once, two unless you change it. Other runs wait and start as slots free up. |
| [Durability](/runs/durability/) | When Orbital restarts, every run you did not pause carries on where it was. Queued runs keep their place. |
| [Project](/projects/) | A name and the folders a run works in. A folder can be a Git repository or a plain folder. Every run belongs to one project. |
| [Worktree](/projects/worktrees-and-delivery/) | An isolated copy of a repository on a branch of its own. Code workflows use it to open a pull request and repair it until it merges. |
| [Harness](/harnesses/) | The coding agent that does an agent step: Claude Code, Codex or OpenCode. You install and sign in to each yourself, so each step runs on your own plan. |
| [Role](/roles/) | Who a step's agent is, which model it runs on and which tools it may use, bundled under one name. |
| [Chat](/chats/) | A conversation with one coding agent in a project, with no workflow behind it. Use it for work you do not repeat. |
| [Trigger](/triggers/) | A rule that acts on runs when something happens in GitHub, Linear or on a schedule. It can start a run, or stop, pause or message runs already working. |
| [Supervisor](/supervisor/) | An optional chat that acts as your delivery lead inside Orbital. When a run needs help, it steps in within the limits you set. |

## Related

- [Start your first run](/get-started/first-run/): see runs, projects and harnesses work together.
- [Pass context between steps](/workflows/pass-context/): what goes into context and what a step can read.
- [Pause, stop or resolve a run](/runs/control-a-run/): take control of a live run.
- [Error handling](/reference/error-handling/): the exact rules for failed steps.
- [Settings](/settings/): where you change how each part behaves.