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

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 strip offers up to three workflows: the ones this project runs most, then the default. Choose a workflow lists every workflow the project offers, with its description. If the workflow has inputs, fill them in. For example, implement-ticket asks for a “Ticket URL”.

  6. Pick a harness and model, if you want.

    Default harness follows the workflow and your settings. Steps whose role or model settings name their own harness keep that harness whatever you pick.

  7. Choose Start run.

    The Start page asking what to do in a project, with the goal box, the harness picker, the workflow picker and the Chat and Workflow switch.
    The goal box, with the workflow and harness 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”