Skip to content

Your first runbook, agent run and approval

This walkthrough uses the CLI against a server you started in a quick start. Install the CLI and sign in first with runbook login https://your-server.

Only IDs are required. Save this as hello.yaml:

metadata: { id: hello }
spec:
inputs:
service: { type: string, required: true }
steps:
- id: check_health
actor: agent
instructions: Call /healthz on ${{ inputs.service }}; pass on 200.
- id: go_no_go
approval:
prompt: Keep ${{ inputs.service }} running?
options: [keep, rollback]
approvers: { teams: [approvers] }

Check it offline:

Terminal window
runbook spec validate hello.yaml

An approval names who may decide it, and names resolve against your server when you publish. Make the approvers team and add yourself, with the user_id that bootstrap printed:

Terminal window
runbook team create --slug approvers --title Approvers
runbook team member add approvers usr_REPLACE_WITH_YOUR_USER_ID

The first runbook of a project is pushed with --draft, then published:

Terminal window
runbook push hello.yaml --project default --draft
runbook publish hello --project default
Terminal window
EXE=$(runbook run start hello --project default --input service=api --json | jq -r .id)

Give an agent an execution-scoped credential, never a person’s token. A service token mints one for a run:

Terminal window
runbook run token "$EXE" --session agent-1

Then the agent loop: ask what’s next, claim the step, read it, report it.

Terminal window
runbook step next "$EXE"
runbook step claim "$SR" --session agent-1 --agent-name my-agent --model manual
runbook step get "$SR"
runbook step report "$SR" --status succeeded --verdict pass --output status_code=200

step next prints next: claim_ready_work with the ready steps and their step run IDs (sr_…), or next: wait when nothing is ready for this actor. An execution credential can read only the step it has claimed.

To run a real command under the step’s lease, use step exec; it streams the output into the step’s log with secrets redacted and reports from the exit code:

Terminal window
runbook step exec "$SR" -- ./scripts/smoke-test.sh --env prod

Approvals aren’t in the agent’s brief; a person decides them. Find the step run in the run report and decide:

Terminal window
runbook run report "$EXE" --format md
runbook step decide "$SR" --option keep --comment "Healthy"
Terminal window
runbook run get "$EXE" --wait
runbook run report "$EXE" --format md

The run report reads like a document: who did each step, their outputs, logs and evidence. Export it as Markdown, JSON, JUnit or PDF.