Expert knowledge that anyone can run.

Gruntwork Runbooks turns your infrastructure expertise into guided workflows that any developer can safely execute. No portals to deploy. No docs that rot. Just live runbooks that work.

Get Started View on GitHub

How it works

Authors write MDX

You write a runbook in MDX (markdown with interactive blocks) in your editor, just like code.

Here’s a real runbook:

# Deploy a New Service

This runbook guides you through deploying a new microservice to your infrastructure.

## Pre-flight checks

Before we begin, let's verify your local environment is ready.

<Check
    id="check-node"
    path="checks/node-version.sh"
    title="Check Node.js Installation"
    description="Verify that Node.js is installed on your machine."
    successMessage="Node.js is installed and ready!"
    failMessage="Node.js is not installed. Install it from https://nodejs.org"
/>

## Configure your service

<Inputs id="service-config">
```yaml
variables:
  - name: ServiceName
    type: string
    default: "my-service"
  - name: Environment
    type: enum
    options: [dev, staging, production]
    default: dev
  - name: EnableMonitoring
    type: bool
    default: true
```
</Inputs>

## Deploy

<Command
    id="deploy"
    command="echo 'Deploying {{ .inputs.ServiceName }} to {{ .inputs.Environment }}...'"
    inputsId="service-config"
    title="Deploy the service"
    description="Deploys your service to the target environment."
    successMessage="Service deployed successfully!"
    failMessage="Deployment failed. Check the logs for details."
/>

View this runbook on GitHub →

Developers get a guided UI

That MDX renders into a clean web interface. Developers fill out forms, run checks, and execute commands. No copy-pasting, no guesswork.

Pre-flight checks UI

Choose the blocks you need

Gruntwork Runbooks ships with a growing set of blocks that handle common infrastructure tasks. Mix and match them to build your workflow.

<Command>Execute shell commands and scripts with variable substitution and streaming output.→<Template>Generate files from Boilerplate templates. Render forms for variables, then write to the workspace.→<AwsAuth>Authenticate to AWS via SSO, static credentials, or local profiles. Credentials flow to subsequent blocks.→<GitHubAuth>Authenticate to GitHub via OAuth, PAT, or the GitHub CLI. Detected credentials are confirmed before use.→<GitHubPullRequest>Open a pull request from changes made during the runbook. Completes the clone → modify → PR workflow.→

View all blocks →

Author in minutes, not weeks

No platform to deploy. No plugins to build. No YAML abstractions to learn.

Write a runbook in your editor using MDX, which is markdown you already know, with a handful of interactive blocks. It lives in git, gets reviewed in PRs, and stays close to the infrastructure it documents.

MDX Authoring

Markdown + interactive blocks. If you can write a README, you can write a runbook.

Lives in Git

Runbooks are code. Version them, review them, share them like any other file in your repo.

Watch Mode

Edit your runbook and see changes instantly in the browser. Fast feedback loop for authors. Learn more →

Generate files, open PRs, ship changes

Gruntwork Runbooks isn’t just live documentation, it’s a code generation pipeline.

Powered by Gruntwork Boilerplate, the <Template> block renders files from templates with developer-supplied variables, previews the output in a built-in file tree, and writes results to the workspace.

Combine <GitClone> to clone a repo, <Template> to generate files, and <GitHubPullRequest> to open a PR, all in a single guided workflow.

Boilerplate Templates

Generate files and folders from a template. Variables come from form inputs. Learn more →

Inline Templates

Define small templates directly in your runbook MDX and give users inline previews. Learn more →

Clone & PR

Clone a repo with <GitClone>, make changes, and open a pull request with <GitHubPullRequest> for a complete end-to-end workflow. Learn more →

File Preview

Generated files render in a collapsible file tree with syntax-highlighted code. Developers see exactly what will be created before committing.

Open source and self-contained

Gruntwork Runbooks is a single Go binary.

No servers to maintain, no cloud accounts to configure, no dependencies to manage. Everything executes locally on the developer’s machine.

Single Binary

One download. No runtime dependencies. Works offline. Runs on macOS and Linux.

Local Execution

All commands run on the developer’s machine. No secrets leave the local environment.

Open Source

MPLv2 licensed. Full source on GitHub. No vendor lock-in, no surprise pricing.

Get started

InstallInstall via Homebrew, download a binary, or build from source.Write your first runbookStep-by-step tutorial to create and run your first runbook.View on GitHubBrowse the source, open issues, and contribute.