documentation
03 dashboard

Runbooks

Runbooks capture incident response, deployment procedures, or any multi-step operation as an ordered list of steps. Agents can author them from chat and execute them on demand. Lightweight, linear, and easier to write than workflows.

What this page is for

The Runbooks page is where you author, save, and run named sequences of steps. Use it when you have a procedure a human could follow from a sheet of paper — numbered instructions executed in order, where each step is mostly self-contained. Incident response, deployment, onboarding, health-check sweeps, routine maintenance. Anything that reads like a playbook.

For pipelines where one stage’s output feeds the next, use Workflows instead. Runbooks are strictly ordered and don’t have formal dataflow between steps.

Layout

The page lists every saved runbook with:

  • Name and description
  • Step count
  • Status — Draft, Published, or Archived
  • Last executed and last outcome

Click any runbook to open its detail page, which has three tabs: Steps (the editor), Runs (execution history), and API (how to trigger it programmatically).

Common tasks

Create a runbook from the dashboard

  1. Click New runbook in the header
  2. Pick a name and description
  3. Add steps one at a time — each step is a single instruction in plain English
  4. Click Save

Step 1 runs first, step 2 second, and so on. You can reorder by dragging, edit inline, and delete individual steps.

Create a runbook from chat

Any agent with the runbook tool can create one for you. The common shape:

“Create a runbook called incident-response-database with these steps: 1. Page the on-call engineer via send_email. 2. Snapshot the database logs to the data store. 3. Run a diagnostic web_fetch against /health. 4. Post a status update to #incidents on Slack.”

The agent creates the runbook and returns the id. Open the Runbooks page to see it.

Execute a runbook

  1. Open the runbook detail page
  2. Click Run
  3. Optionally fill in any parameter values the runbook declares
  4. Click Execute
  5. Watch the Runs tab — each step shows its status (pending, running, complete, failed) as the runbook progresses

You can also schedule a runbook on cron — see Triggers.

Pause or abort a run

During execution, the runbook detail page shows a Pause and Abort button. Pause stops execution at the next step boundary and waits for you to resume. Abort stops immediately and marks the run as cancelled.

View run history

The Runs tab lists every past execution with status, duration, and which agent executed it. Click any run to see the step-by-step timeline of what happened.

Edit a runbook

Click Edit on the detail page. You can add, remove, reorder, or rewrite steps. In-flight runs finish on the old version; the new version takes effect on the next execution.

Step-writing tips

Good runbook steps are:

  • One instruction each — not “first do A, then do B”. Split those into two steps.
  • Imperative — “Page the on-call engineer” not “The on-call engineer should be paged”
  • Tool-hinting — mention the tool to use when there’s ambiguity: “Use send_email to notify the on-call team”
  • Checkable — the agent should be able to tell if the step succeeded

Bad runbook steps are vague (“handle the problem”), compound (“do X and Y and then Z”), or ambiguous about ownership (“make sure someone is notified”).

Common pitfalls

Using a runbook where each step depends on the previous output. That’s a workflow, not a runbook. Runbooks don’t have formal dataflow between steps — if step 2 can’t run without step 1’s result, use a workflow instead.

Making runbooks too long. A runbook with 20+ steps becomes unreadable. Split long procedures into multiple runbooks that call each other, or convert the complex parts into workflows.

Hardcoding values that should be parameters. If you’re embedding timestamps, URLs, or thresholds directly in step text, parameterize them instead. Parameters are inputs to the runbook that get substituted into the steps at execution time.

Where to go next