Skip to main content

Welcome to ▶️ Runme's docs. Thanks for stopping by.

Quick Start ⚡️

If you are of the kind who likes to jump in head first. Below is a quick start guide to launch into Runme's self-hosted web UX.

💡 If you are a VS Code user, skip ahead to Runme for VS Code.

MacOS​

$ brew install runme && runme open

Linux & Windows​

$ npx runme open

Make sure to confirm the prompts and you should be dropped into the Runme web interface at http://127.0.0.1:8080. Go ahead and open any abitrary Markdown document as notebook or open the terminal to test-drive the runme CLI. While the UI might remind you of VS Code, it's a self-hosted web app. More information please see Runme for Web.

Runme for Web


Keep going!

Learn more about Runme and what problems it solves for you.

Why Runme?​

Runme makes runbooks actually runnable, making it easy to complete step-by-step instructions. This makes it an excellent solution for runbooks, playbooks, and documentation that requires users to complete runnable steps incrementally—making operational docs reliable and less likely to become outdated.

DevOps Workflows Built With Markdown 🤝​

Using notebook-based technology, users can execute instructions, check intermediate results, and ensure the desired outputs match expectations to complete the steps confidently. Authors, on the other hand, can define reliable paths for operational tasks, steps it takes to diagnose problems, or remedies to resolve problems and effectively share them with teammates.

In a nutshell, Runme combines the guardrails of a pipeline with the flexibility of scripting, where users can check intermediary results before moving on. Much like a terminal session, environment variables are retained across execution, and it is possible to pipe previous cells' output into successive cells.


Try it now

Learn how to install Runme and get started.

What is Runme?​

Runme enables you to execute interactive runbooks using Markdown. More specifically, Runme runs your code and commands inside your fenced code blocks (shell, bash, zsh, but also, Ruby, Python, etc).

We have designed a comprehensive set of tools and configurations that are 100% compatible with CommonMark, the standard for Markdown. Through this, your integration with Runme does not interfere with your existing Markdown documentation or tooling.

Alongside, we provide interfaces for terminal, editor, and notebooks all attached to a kernel, making them interoperable. While these interfaces share core features, each interface excels in different use cases.

💡 Runme is like Jupyter but with a Shell/Bash Kernel and lightweight dependencies.

Usability​

Runme runs everywhere, irrespective of the environment: a local laptop, a VM, a Devcontainer, Cloud Development Environment, or attached to a remote host via SSH:

  • Split loose scripts into runbooks with separate cells, intermediate outputs, and controls to check before moving on.
  • Get ahead of bit-rot and reverse-engineering runbooks executing them directly from Markdown inside your project's repo.
  • Increase the shareability of runbooks by decoupling them from personal dotfiles or bash_history's without getting in the way.
  • Codify golden paths without overly restricting the flexibility of "scripting".

Learn more about Runme's Kernel Architecture to understand what powers Runme's portability.

Known Limitations​

  • Runme currently only has rudimentary support for PowerShell. While PowerShell is not limited to Windows, it is its primary platform. We recommend using WSL.
  • Please report any issues you encounter, big or small, to help us make Runme better.

Communication & Support​

Need assistance in getting started? Get in touch with members of our team via Discord and get answers to your questions and all the necessary details to get you started with Runme.

Join Runme community!

Make sure to get in touch with us if you are missing a feature or have other ideas.