Turn the Markdown you already write into runbooks you can actually run.

Welcome to Runme: Executable Markdown for DevOps.

Runme is a CNCF sandbox project that turns ordinary Markdown documents — READMEs, runbooks, setup guides — into interactive, runnable notebooks. The shell and code blocks you already write inside your docs become cells you can execute, in a VS Code notebook, from a command-line tool, or headless inside CI. The problem it attacks is documentation bitrot: instructions that drift out of sync with reality because no one runs them. By making the doc itself the thing that runs, Runme keeps your operational knowledge honest, testable, and reproducible. This book starts with the bitrot problem and the executable-document idea, then works through Runme's architecture — its serializer, kernel, runner, and the gRPC interface that lets one engine serve many clients. From there it covers cell annotations and named cells, sessions and exported environment variables, the command-line workflow, putting runbooks into CI/CD pipelines, and finally the practices and ecosystem fit that make Runme worth adopting. Throughout, the goal is the same: documentation that you trust because it stays executable.

This title is part of the ShriIra library and is free to read in full, right here — our small contribution to making world-class knowledge easy to reach.

A note on reading it: open the Contents menu at the top of the reader to jump between chapters, use the Aa menu to set a comfortable text size, theme (light, sepia, or night), and single- or two-page layout. Your place is saved automatically, so you can always pick up where you left off.

We hope it serves you well.

— Shriira Press

Contents

1. Chapter 1 — Documentation That Runs
2. Chapter 2 — Inside Runme's Architecture
3. Chapter 3 — Cells, Annotations, and Named Workflows
4. Chapter 4 — Sessions and Environment State
5. Chapter 5 — The Command Line and Headless Runme
6. Chapter 6 — Runbooks in CI/CD
7. Chapter 7 — Runme in Practice