Reusable Runbooks

Start Here

From Package to Checked List

Native v1 targets one active, visible POSIX terminal. That can be a local shell or an SSH/container session you established before starting the run.

1. 01
   Enable the experiment Open Settings → Runbooks and enable Runbooks. It is off by default while the format is v1alpha1.
2. 02
   Choose an example or import a package Start with one of the included macOS assessments, or select a local folder whose root contains exactly one runbook.vrun.yaml. VTerminal validates imported packages before registering them.
3. 03
   Review the preflight Choose the terminal, confirm its observed target, enter only non-secret inputs, review declared capabilities, and confirm how much output this run keeps.
4. 04
   Run beside the terminal Follow the live checklist, approve actions, resolve pauses, review the runbook definition mid-flight, add comments, then inspect or export the final report from History.

Create Without YAML

Build a Runbook in VTerminal

Choose New in the Library to open the deterministic, offline builder. Drafts autosave in app-managed storage and remain resumable across restarts. They cannot be run until the final package passes the same strict validation as an import.

1. 01
   Basics Set the stable ID, semantic version, title, description, tags, failure policy, declared network or root capability, and the absolute paths the runbook writes to.
2. 02
   Inputs Add non-secret string, integer, boolean, path, or enum inputs with typed defaults.
3. 03
   Steps Order shell or manual checks. Shell inputs use explicit VRUN_* environment mappings and compliant/non-compliant exit codes. Tick Remediate when this check fails to add an apply that fixes it and a verify that proves it worked.
4. 04
   Review and publish Inspect the generated YAML and validation findings, then publish the app-managed package into the Library.

Published wizard projects remain editable. Changed publications require a strictly greater semantic version; unchanged publication is a no-op. Removing a Library registration keeps its draft for republishing. Discarding a published draft detaches wizard editing but leaves the published source and historical snapshots intact.

Turn What You Just Did Into a Runbook

New → Generate with AI authors a draft from a plain-language requirement and, optionally, the terminal session where you already did the work by hand. Install and configure something once, attach that tab, and the model turns the commands you ran into steps: what you ran becomes the apply, and the way you would tell it already happened becomes the check and the verify.

1. 01
   Describe it Say what the runbook should do. Requirements alone are enough; the terminal is optional context, not a requirement.
2. 02
   Choose what you share Pick the session, untick any command you do not want to send, and edit the assembled transcript directly. That box is the payload, verbatim.
3. 03
   Review before saving The result opens on Review as an ordinary draft, validated, with every field editable. Nothing reaches the Library until you publish it.

Ready to Run

Included Packages

Four packages ship with VTerminal. The three macOS assessments below target macOS 13 and newer and are assessment-only: they use no model actions and declare no network, privilege or write capability. Each stops on an unsupported target and, on a supported Mac, continues through independent findings to produce a useful full report. A fourth, ansible-localhost-example, demonstrates the Ansible executor against a local inventory and does declare one write.

Own Format

A Small, Versioned YAML Package

A package is deliberately local and constrained. The definition uses a stable Runbook ID, a semantic content version and ordered steps with durable IDs.

my-runbook/
├── runbook.vrun.yaml   required
├── README.md           optional
└── ansible/            optional; used by ansible.playbook actions

apiVersion: runbooks.veviad.com/v1alpha1
kind: Runbook

metadata:
  id: ensure-jq-installed
  version: 1.0.0
  title: Ensure jq is installed
  tags: [linux, software]

spec:
  target:
    kind: active-terminal

  declaredCapabilities:
    network: true
    privilege: root
    writes: [/usr/bin, /usr/local/bin]

  defaults:
    onFailure: pause

  steps:
    - id: jq-installed
      title: jq is installed
      required: true
      check:
        uses: shell
        with:
          command: "command -v jq >/dev/null 2>&1"
        outcomes:
          compliantExitCodes: [0]
          noncompliantExitCodes: [1]
      apply:
        uses: agent
        instructions: |
          Install jq with the target's package manager.
          Make the smallest safe change.
      verify:
        uses: shell
        with:
          command: "command -v jq >/dev/null 2>&1"
        passExitCodes: [0]

Validation rules that matter

• Every step requires check. If apply is present, verify is mandatory.
• Shell actions are one inline command of at most 4,096 characters, with no newlines, control characters or heredocs.
• Typed inputs are non-secret and enter shell actions only through an explicit VRUN_* environment mapping. There are no arbitrary template expressions.
• Unknown fields/actions, duplicate IDs, aliases, custom tags, merge keys, includes, multiple YAML documents and invalid semantic versions are rejected.
• Symlinks, traversal and package-root escapes are rejected. Native v1 never uploads or executes package scripts in a remote terminal.

Portable Packages

Export, Edit, Version and Import

Export runbook in the Library creates a complete, import-ready folder named runbook-<id>-v<version>. The folder contains the exact validated YAML, optional README, and allowed ansible/ tree from the registered source.

1. 01
   Export from the Library Choose a destination that does not already contain the generated folder. VTerminal revalidates source digests and refuses drift, symlinks, path escapes, merge or overwrite.
2. 02
   Edit the exported files Change the YAML or README in an ordinary editor. Keep metadata.id when the operational purpose is the same, and retain step IDs for controls whose meaning is unchanged.
3. 03
   Bump the semantic version Update metadata.version whenever requirements, behavior, inputs or step meaning changes.
4. 04
   Import the edited folder Exported included examples import as normal user sources. The recoverable bundled original remains a separate source.

Registrations are path-based. Importing the same folder refreshes that source; importing a copy at another path creates a separate user source.

Execution Model

Check → Apply → Verify

Steps execute sequentially. A check explicitly distinguishes a compliant exit code, a non-compliant exit code and an execution error. Success is never inferred from an apply command alone.

Only already_compliant and remediated_verified render as checked. A required skipped, waived, blocked, failed, non-compliant or unknown step produces a completed run with exceptions rather than a false success.

Adaptive Remediation

State the Goal, Not the Commands

Installing Docker is apt-get on Debian, dnf on RHEL and pacman on Arch. A fixed command list needs one runbook per distribution. Handing the whole job to a model swaps that for a worse problem: the model decides both what to do and whether it worked.

A goal splits those apart. You state what must be true and the exact conditions that prove it. The model picks the commands. The engine runs the conditions and decides.

- id: docker-running
  title: Docker Engine is installed and running
  goal:
    intent: |
      Docker Engine is installed from the distribution's own
      repository and its daemon is running and enabled at boot.
    checks:
      - command: "command -v docker"
        expect: [0]
      - command: "docker info >/dev/null 2>&1"
        expect: [0]
  constraints:
    maxCommands: 12
    privilege: root
  apply:
    uses: agent
    instructions: |
      Install Docker Engine using this distribution's package manager.

There is no check and no verify: the goal serves as both, so one condition is written once instead of twice. Goal conditions are ordinary commands in your visible terminal and carry the same shell_observed assurance as any other. Nothing claims a more trustworthy executor. What changed is who reads the result.

Operator Control

Actions, Approvals and the Trust Boundary

What approval means in native v1

• Every visible-terminal shell action requires explicit approval, including checks and verification. Apply always requires it.
• Model phases are opaque and must be approved one step at a time.
• If you prefer, use Acknowledge and approve all remaining steps in live mode to continue through later approvals. It waits for each approved command to finish before the next approval appears, so a step that takes minutes is normal. It stops at the first operator pause, manual step, finished run or invalid command, and Stop auto-approve ends it at any point.
• Abort run stops an active run and returns you to the Library. It cannot prove the process stopped or undo a change already made; the active step is reported unknown.
• This flow is different from the agent panel’s Full setting and can only advance runbook approvals.
• On-device models are reported as local; cloud and configured remote providers are additionally reported as networked.
• Each approval shows the immutable target and asks you to attest that the visible row is a POSIX prompt on the intended host/container, and that its shell, functions, aliases and PATH are trusted.
• A run binds to one terminal and observed local/SSH/container context. Target or session drift pauses execution, and two runs cannot drive the same terminal concurrently.

A timeout is unknown; it is not an automatic retry. Cancellation sends SIGINT to the owned foreground job but cannot prove detached work stopped or undo a mutation. After an app restart, an active run is interrupted and must be explicitly rebound before resuming.

Durable Results

Evidence and Canonical Reports

Successful, exceptional, failed and cancelled runs all finalize a canonical report.json. The human-readable report.md is generated only from that report data, so the two views cannot invent different outcomes.

Settings → Runbooks → Record terminal output sets the floor: Never, As the runbook asks (the default, honouring spec.audit.recordOutput), or Always, in full. Preflight offers only levels at or above it, so a single run can be raised but never lowered, and the clamp is applied in Rust rather than in the picker.

Reports include definition IDs, versions and digests; target and input data; checklist states; attempts; approvals; edited-command deviations; evidence metadata; agent summaries; comments; exceptions and unresolved risks. Removing a package registration does not erase its historical runs.

Step and executive summaries use the engine-fixed outcomes and bounded structured evidence. They are deterministic by default, so report evidence is not sent to a model merely to improve the prose. A summary returned by an explicitly approved agent phase is retained.

Credential-shaped content and private-key blocks are redacted before display, persistence and export, and truncation is explicit. Detection is necessarily best-effort: arbitrary secrets without a recognizable name or shape cannot be found reliably.

Native

Ansible Runner, Explicitly Controlled

ansible.playbook executes through a user-installed ansible-runner; there is no fallback to ansible-playbook or a generic shell action. Every approval shows and binds the exact project and inventory digests, and reports retain structured outcomes per host. Check and verify run with --check --diff, while a successful apply must still pass verification. Runner is launched as a local controller without inheriting the visible terminal shell; its inventory may target remote hosts.