How the engine works
A graph is a versioned DOT document. Its entry names the first node. An agent node renders a prompt and calls a harness. A command node records machine facts. An outgoing edge chooses what happens next; a terminal ends the run.
The harness is Claude, Codex or OpenCode. The browser’s run choice supplies the default harness; graph profiles and node settings can select another one for individual turns. The resolved model and harness appear in the transcript.
Context and observations
Section titled “Context and observations”A run begins with its goal and declared inputs. Context holds those values, accepted agent outputs, command facts and stage outcomes. Prompt templates read context. Conditions only read values available on their path through the graph. Context explains what a step can read.
Built-in probes are read-only observations. 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.
Agent outputs are validated structured data, not arbitrary prose scraped from a response. An outputs declaration tells Orbital which keys and types to accept. The final response remains available under context.response.<node>.
Persistence
Section titled “Persistence”The server stores run state and the transcript in ~/.orbital/run-history.db. ORBITAL_HOME changes the data directory. The event transcript records what happened; saved state supplies the context used when execution resumes.
Closing the browser leaves the server running. Stopping the server interrupts execution. After a restart, runs that were executing become stopped runs. Resume uses an available continuation; Retry starts a new visit. A run keeps its original graph snapshot and harness selection. Prompt sidecars can be reread on a later visit, subject to validation.
Steering a live run
Section titled “Steering a live run”Open the run and read the active step and its transcript. Send a steering message when the agent needs a correction. Queued steering is included whole in the next applicable turn, even with truncated history. Harnesses differ in whether they can accept it during a live turn.
Interrupt to stop current work before changing direction. Answer questions and permission requests in the run interface. During a wait, skip the remaining time only when the observation should run again now.
A manual jump changes the next step and may lack context that normal routing would have produced. Read its warnings before confirming. Use normal routing when it already expresses the correction you need.
Failure and hold
Section titled “Failure and hold”A failed stage may take a failure edge and recover. Without a matching failure edge the run waits for an operator. A failed terminal ends the run. These are different states, so inspect both the current phase and the transcript. Error handling gives the exact rules, and troubleshooting explains how to recognise each state in the interface.