DOCSEARCHbyAlgolia
Submit Docs

Runme Documentation

website·Indexed 34 days ago

https://docs.runme.dev

Runme codifies DevOps workflows into reliable, reusable assets stored in Git as Markdown. It provides a notebook-based environment for executing commands and scripts via a VS Code extension, CLI, and web interface, featuring support for shebangs, standard streams, and integration with GitHub Actions, Kubernetes, Helm, and ArgoCD.

Tokens
35.7K
Snippets
222
Records
309
Agent score
63%

What's inside Runme

  1. Overview of Runme DevOps Workflow Codification

    Runme allows DevOps teams to codify workflows into reliable, reusable assets stored in Git as Markdown. When opened with a Runme client, these files become interactive Runme Notebooks. A single notebook can encapsulate all requirements for a workflow, including human instructions, scripts/code, environment variables (.ENV), secrets, configuration, devContainers, cloud integrations, and system dependencies. This approach enables organizations to capture and share operational knowledge to unblock engineering teams.

  2. Overview of runme eval for agent task evaluation

    runme eval is an experimental command group designed for agent task evaluation workflows. Unlike standard Runme notebook execution, it does not run Markdown cells; instead, it runs task datasets that require AI agents (e.g., Codex, Claude Code, Cursor CLI, OpenClaw) to complete concrete tasks in a local project environment. Each task defines the setup, the agent's objective, and a verifier to score the result. It is intended for the 'inner development loop,' allowing authors to create and improve eval tasks against real repo state before moving them to CI or larger benchmark infrastructure.

  3. Overview of Runme and its relationship to Stateful

    Runme is an open-source platform (licensed under APL-2.0) developed by Stateful, Inc. It allows developers to create and run interactive runbooks using standard Markdown files, aimed at preventing documentation bitrot by supporting scripting and pipelines.

  4. Overview of Runme and Runme Notebooks

    Runme is a cloud-native shell kernel that makes Markdown documentation runnable. It provides a notebook, editor, terminal, and CLI interface to automate step-by-step instructions and capture operational knowledge. Runme Notebooks are created using Markdown (which Runme extends) and enable commands and code to be executable, behavior and output to be configurable (stored within the Markdown), and commands to be aware of .ENV dependencies. For example, specifying a 'mimetype' in config metadata allows the notebook to render output as images or sortable tables instead of plain text.

  5. Overview of Runme Gist

    Runme Gist integrates GitHub Gist with Runme's notebook capabilities, allowing users to run, share, and store plain text or code snippets from Markdown files. Its primary value is the ability to capture execution outputs and mask sensitive data directly within the Markdown workflow without needing a full repository or third-party integration.

  6. Run interactive Notebooks using Markdown files

    Runme allows you to run Notebooks directly from standard Markdown files (.md) without additional configuration. Upon installing the Runme VS Code extension, it becomes the default viewer for .md files, enabling the execution of text and commands within the Markdown format.

  7. Use Runme features within development containers

    Runme provides specific capabilities when running inside a development container:

    • Shebang Support: Allows you to specify the programming language for a code block using a shebang, enabling multi-language support within a single Markdown file.
    • Background Tasks: You can configure code blocks to run commands in the background, allowing you to continue working on other parts of the project while a process (like a Go server) runs.

  8. Runme VS Code extension features overview

    Runme transforms Markdown files (*.md, *.mdx) into interactive notebooks with the following capabilities:

    • Notebooks Explorer: Access all Markdown files in the project directory.
    • Cell Execution: Run code blocks with a single click and view results in the integrated VS Code terminal.
    • Execution Indicators: Visual icons showing success or failure (e.g., "X" for failure) of executed cells.
    • Global & Cell Actions: Configure cell language and execution settings via Notebook Global Actions and Cell Code Block Actions.

  9. Choose a Runme client interface for your workflow

    Runme provides several client interfaces to interact with its kernel, depending on the user's environment and use case:

    • IDE Extensions: Available for VS Code (including Cursor and PearAI) and Open VSX (including VSCodium and Theia).
    • Terminal: A CLI for directly executing commands from existing Notebooks.
    • Web: A self-hosted web app version for browser-based Notebook UI.
    • Cloud Development Environments (CDEs): Support for GitHub Codespaces, Gitpod, IDX, and Azure AI Studio.
    • Containerization: Docker support for isolated environments.
    • CI/CD: A GitHub Action for testing Notebooks in automated pipelines.

  10. Runme Notebooks feature overview

    Once installed, Runme transforms *.md and *.mdx files into interactive notebooks with the following capabilities:

    • Notebooks Explorer: Access all Markdown files in the project directory.
    • Cell Execution: Run code blocks with a single click via the Run Cell Button.
    • Execution Status: Visual indicators show if a cell succeeded or failed (marked with an "X").
    • Integrated Results: View and copy execution output in an integrated terminal to avoid context switching.
    • Code Block Actions: Configure cell language and other execution settings directly on the code block.
    • Global Actions: Access notebook-wide input and execution options.

  11. Understand Runme Lifecycle Identity metadata

    The Lifecycle Identity feature assigns unique identifiers and versions to individual cells or the entire document. This allows for tracking changes and history. When enabled, the following metadata is added to the Markdown file:

    • id: A unique identifier representing the specific instance of the document or cell.
    • version: The current version number of the Runme instance being used.

    Users should not manually edit these identifiers to avoid conflicts.

    runme:
  id: 01HFY0VFSB5F1PF7C28BW2YSVT
  version: v3

  12. Render JSON data into human-friendly formats in Runme

    Runme transforms large JSON datasets into organized formats such as tabular arrangements, flat data grids, or data summaries. To achieve this, two primary configurations are used:

    1. MIME Type: Runme uses MIME types to identify the nature of the data. While Runme reliably auto-detects JSON and CSV files, you can manually specify the MIME type (e.g., application/json) in the advanced configuration dashboard.
    2. Interactive Mode: To successfully render JSON data, Interactive Mode must be turned off. If this mode is enabled, the script runs in a standard output terminal, which prevents the specialized data rendering.