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

Start a run

Give a project a goal, pick a workflow and start a run

You start a run from the Start page: you pick a project, write a goal and choose a workflow. The run then carries out that one workflow for that one project, towards that goal.

Before you start

Section titled “Before you start”

You need a project and a harness that is set up. A run whose harness is missing stops and waits on you.

Start a run from the app

Section titled “Start a run from the app”

  1. Open the Start page.

    Choose New task in the sidebar.

  2. Check the project.

    The project shows at the top. Choose it to pick another, or press ⌘K.

  3. Leave the switch on Workflow.

    The switch sits under the text box. Set to Chat, it starts a chat instead.

  4. Write the goal.

    In the text box that reads “Describe what the run should achieve”, type what the run should achieve.

  5. Choose a workflow and fill in its inputs.

    The workflow dropdown lists every workflow the project offers, with its description, and starts on the project’s default or the one it ran last. If the workflow has inputs, fill them in. For example, implement-ticket asks for a “Ticket URL”.

  6. Pick a preset, if you want.

    The preset picker starts on the preset in use, which follows your settings: if you switch the preset in use later, the run moves with it. Choose another style to pin the run to it, so every step uses that style’s harness, model and effort until the run ends. A setting the workflow already gives a step, through the step’s own keys, its style, its group or the workflow’s style, wins over the run’s preset.

  7. Choose Start run.

    The Start page asking what to do in a project, with the goal box, the preset picker, the workflow picker and the Chat and Workflow switch.
    The goal box, with the style and workflow pickers beneath it.

If you choose no workflow

Section titled “If you choose no workflow”

The run uses the workflow the project ran last. If the project has never run one, it uses the Default workflow in Settings.

What happens next

Section titled “What happens next”

The new run joins the queue and starts when a run slot is free. Follow it on the run page.

Other ways to start a run

Section titled “Other ways to start a run”

You can also start a run without opening the app.

From How
A terminal orbital run start
A coding agent Over MCP
An event or a schedule A trigger
Section titled “Related”