Running a workflow

This page covers what happens once a workflow exists and you actually want to run it: where the Run button lives, what the launch modal asks for, what shows up after you launch, and how to follow or stop a run in progress. For building the workflow itself, see the editor.

Starting a run

Three places open the same launch modal:

• Workflows → Run on any workflow card in your list.
• Recommended workflows, a strip on the new-chat home screen listing your own workflows, most recently run first.
• Run workflow in an active chat's composer. The lightning-bolt button opens a workflow picker without leaving the conversation.

Launching from chat fixes the target to that chat's workspace and offers the current session as a binding candidate for an agent using the same harness. The location and workspace are shown as a read-only line instead of editable pickers.

The launch modal

Launching opens one modal, whichever door you came in from:

• Inputs — one field per input the workflow declares (text, number, choice, or boolean), rendered from the workflow's definition. Required inputs block the Run button until filled in.
• Sessions — only shown when the workflow has a live session it could reuse. Every agent slot defaults to New session. A run never takes over a session you're using unless you pick it explicitly from that slot's dropdown. Binding an existing session hands it to the run and locks it until the run finishes or you cancel. If another run already holds the selected session, launch is rejected instead of transferring the lock. Workflows with a parallel group cannot bind existing sessions.
• Run location — On this Mac or Cloud, if you have a cloud workspace available. Pre-filled with wherever this workflow last ran, so repeat runs don't make you re-pick a target every time.
• Workspace — the specific local or cloud workspace to run in, filtered to whichever run location you picked.

If a run can't start because a connected account is not ready for a provider, for instance, the modal shows the error in place and, when it knows what to fix, links straight to Settings → Integrations.

After you launch: the run pill

Launching doesn't take you anywhere. It stays on whatever screen you launched from and drops a small pill at the bottom of the window instead:

View jumps to the run's page; the X just dismisses the pill. The run keeps going either way. This is deliberate: starting a run is a small, frequent action, and it shouldn't yank you out of whatever you were doing.

Following a run

A run's page shows a header and a step timeline:

• The header names the workflow, shows a live status pill (Queued, Starting, Running, Waiting for approval, Completed, Failed, or Cancelled), and lists how it was triggered, how long it's taken, cost so far, which run location it's using, and the input values it launched with.
• The timeline lists every step across every agent in order, each with a status dot, a one-line preview of what the step does, and typed chips for what it produced: an exit code, a PR link, a Slack delivery, an approval decision. A step that's iterating toward a goal shows a live counter of turns and tokens spent instead of a static preview.
• Any step tied to an agent session shows an Open session link that takes you straight to that session's workspace to read the full transcript or diff.

The page polls for updates while the run is active and stops once it reaches a terminal state. A handful of statuses carry a more specific reason than their name alone; the status pill and its tooltip show that reason instead of flattening every outcome into a generic failure.

Taking over a session, and stopping a run

If you bound a live session to a run, that session is locked to the run until the run ends. You can't type in it while it's held. To get it back, or to stop a run outright, use Cancel run in the run's header:

Cancel run is available for both local and cloud runs while the run hasn't reached a terminal state yet, and it is the same action whether you're stopping a run you don't want to continue or taking back a session it locked. Cancelling releases any bound session immediately. There's no resume: a cancelled run can't be picked back up, only re-launched from the workflow.

Where to go next