> For the index of every page in Orbital's docs, read https://docs.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 TOML file of steps, each with the routes that lead out of it. 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 probe step reads facts, such as the state of a pull request, and a command step runs your shell command and records its facts.
- An action step makes a built-in change, such as opening a pull request.
- A step's routes and its `next` choose what happens next.
- A terminal step ends the run.

The harness is the coding agent that does an agent step: Claude Code, Codex, OpenCode or Pi. A step takes each turn setting, such as its harness, model and effort, from the first place that sets it: the step itself, its [style](/styles/), the styles of the groups holding it, a model picked when the run started, the workflow's style, the run's preset, else **Settings > Harnesses**. [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. Routes 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.<id>`, where `<id>` is the step's id.

Built-in probes only observe. A `probe` step with `observe = "github.pr"` reads each repository folder's current pull request from GitHub. Command steps 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 github.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 route matches | The run takes the route and may recover. |
| A step fails and no failure route 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 TOML file of steps and the routes between them. Orbital loads, validates and runs it, and ships nine of its own. |
| [Step](/reference/step-kinds/) | One part of a workflow. Its `kind` decides what it does, from agent steps to probes, actions, decide steps, 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. |
| [Style](/styles/) | A named set of turn settings, such as the harness, model, effort and persona, that a step, a group or the whole workflow can use. |
| [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. |
| [Delivery lead](/delivery-lead/) | An optional chat that leads delivery 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.