Runbooks

Operations → Runbooks (/gravity/runbooks, with detail pages at /gravity/runbooks/[id]) is where you define the operational actions Sencai can carry out on your enrolled servers - a service restart, freeing disk space, killing a runaway process, or running an approved script - and trigger them by hand or automatically.

Creating, editing, and triggering a runbook all require the Admin or Owner role. Viewing the library, opening a runbook, and reading its execution history are open to any role in your organization, including Viewer and Auditor.

Authoring a runbook

A runbook has:

• Name and description
• Trigger type - Manual (you fire it yourself) or Alert (intended to be matched by an auto-remediation rule)
• Actions - a JSON array of one or more steps. Each step has a type and its own params. The supported action types are restart_service, clear_disk_space, kill_process, and run_approved_script.
• Cooldown (minutes) - the minimum time between two triggers of the same runbook, so a flapping condition can’t fire it repeatedly.
• Require approval - see Approval gating below.
• Active - an inactive runbook can’t be triggered, manually or automatically.

[
  {
    "type": "restart_service",
    "params": { "service_name": "nginx" }
  }
]

Targeting hosts

Every runbook trigger must name a specific enrolled agent - its documentId identifies the host the run executes on, and that agent must belong to the same organization as the runbook. There’s no untargeted or organization-wide “run everywhere” option; a trigger with no agent selected is rejected with a validation error. This applies to dry runs too, since a dry run is still sent to the target agent (see below). Note that the Trigger dialog currently labels this field Agent ID (optional) - despite the label it isn’t optional, and leaving it blank will fail. An agent must also have the runbook-execution capability granted before it will accept a dispatched runbook - see the fleet agent guide for enabling agent capabilities.

Dry runs

Both the library and a runbook’s own detail page offer a Test (dry-run) action that simulates the runbook’s actions without actually executing them on a host - useful for checking that a new or edited runbook does what you expect before it touches a real server. Dry runs skip the approval gate entirely, even on a runbook with Require approval turned on. A dry run is still sent to the target agent (it’s the agent that simulates the steps), so it depends on the same dispatch capability as a real run - see the caution below. (The Dry Run button on the Runbook Versions screen, covered below, is a different, lighter check that doesn’t involve an agent at all.)

Approval gating

If Require approval is on, triggering the runbook for real creates an execution in a pending state instead of running immediately - the intent being that a second person reviews and approves it before anything touches a host.

Caution

Approving a pending execution isn’t functional in the app today - the approval step needs a token that isn’t currently surfaced anywhere in the UI or the API, so a pending execution has no way to be moved forward. If you want a runbook to actually execute when triggered (rather than sit in pending indefinitely), turn Require approval off. New runbooks default to requiring approval, so this is worth checking explicitly on anything you create.

Caution

Triggering a runbook creates the execution record described above and, on top of approval and the runbook-execution capability, still needs dispatch to a fleet host switched on for your environment. It isn’t enabled for every account today - where it isn’t, a triggered runbook, dry run or real, never actually reaches the agent. Check with your account team before relying on runbooks to make a change on a host.

Execution history

A runbook’s Executions tab lists every time it’s been triggered - dry-run or real, who triggered it (or which automation did), the target agent, status (pending, running, completed, failed, dry-run, or cancelled), and when the pending-approval window expires. Use the status filter to narrow a long history down to, for example, only failed runs.

Versioning and rollback

Operations → Runbook Versions (/gravity/operations/runbook-versions) manages a runbook’s version history separately from its day-to-day edit form:

• New Version creates a draft copy of the runbook (a new, inactive record linked back to the version it was copied from) so you can change actions or configuration without touching the version currently in use.
• Dry Run from this screen previews a specific version’s steps - it lists what each step would do, without running anything and without sending anything to a host. Because it doesn’t involve an agent, it works even where runbook dispatch isn’t enabled for your account, and it’s available to any role that can view the runbook. Useful for validating a draft before you switch to it.

There’s no one-click “activate this version” or “rollback” button. A version is a separate runbook record, so making a new version live - or going back to an older one - means opening that version’s own detail page and turning its Active setting on (and, if you want only one version running at a time, turning the previous one off).

What’s next

• Fleet: remote execution - the agent-side mechanics a triggered runbook relies on
• Auto-remediation - matching an incident pattern to a runbook automatically
• Incidents - where a manually triggered runbook is often used from
• Audit log - every trigger, dry-run, and approval attempt is recorded there