Runme is a toolchain that turns Markdown into interactive, cloud-native, runnable Notebook experiences for DevOps.
Project Description
Runme: DevOps Notebooks Built with Markdown
Runme consolidates operational documentation and executable commands/code into interactive Notebooks or TUIs, seamlessly integrating with cloud-native infrastructure. The toolchain empowers engineering teams to build and maintain reliable, shareable documentation that can be tested in CI/CD.
Key Features:
Cloud Integration: Supports AWS, GCP, and GitHub Actions for managing deployments and automating cloud workflows directly from within Notebooks.
GitOps-Ready: Runme stores operational steps in Git-managed Markdown files, ensuring that runbooks, playbooks, and scripts are synchronized with infrastructure-as-code (IaC), tests, and GitOps processes, encouraging reviews/knowledge-sharing and keeping documentation up to date.
DevOps Tooling: Integrates with Kubernetes, Terraform, Helm, Docker, Dagger, and Argo CD for seamless orchestration and automation of infrastructure.
Environment Validation: Runme enables users to define and validate .ENV dependencies, ensuring all required resources and configurations are present before execution. Combined with devContainers, this delivers the most innovative and effective approach to repeatable, reliable documentation experiences.
Use Cases:
Runbooks and Playbooks: Document and execute operational processes like deployments, infrastructure management, or incident response directly from Notebooks, ensuring consistency and repeatability.
Automation: Automate workflows with tools like Terraform, Helm, Dagger, and Argo CD. Runme allows users to interact with these automated workflows one task (or category) at a time, without requiring the workflow to be a pipeline (although it can be run there as well).
Interactive Control Panels: Build real-time dashboards for monitoring and tuning systems, enabling interactive control over infrastructure.
Runme’s kernel, exposed over gRPC, converts between Markdown and Notebook formats (as required by the client) and maintains the .ENV state across Notebook sessions, transforming Markdown into an interactive and reliable docs experience. Delivered as a VS Code platform compatible extension, Runme makes it easy to distribute Notebooks across environments like Codespaces, Gitpod, and VSCodium.
[x] If the project is accepted, I agree the project will follow the CNCF IP Policy
Trademark and accounts
[x] If the project is accepted, I agree to donate all project trademarks and accounts to the CNCF
Why CNCF?
Starting in my time at Buoyant I would attend Kubecon events, which have great energy. We've started exploring DevOpsDays, whose audience feels like the right place to build our community. Given the use-cases we see, it's clear that the intersection of devContainers, cloud-native, security/authorization and reproducible/reliable process for complex workflows is our bread and butter. We also see a lot of potential for partnering in the CNCF project landscape and adding value by lowering project barriers to entry, while collecting feedback to guide Runme to add the most tangible value.
Benefit to the Landscape
There is a huge opportunity for CNCF projects to embrace Runme as a more human friendly interface. Not just utilizing Runme for a nicer interface for their tool, but also to make the experience when using their tool more deeply integrated and intuitive. I continue to find it interesting that there are so many tools to support production cloud-native operations, but very little to support training, streamlining, educating and documenting the interfaces people need to really use them. Maybe it's time to open a new category?
Cloud Native 'Fit'
The simplest answer is that the tool is fairly agnostic and flexible about the specifics of the workflows being defined. But the reason that we moved from basic development flows to DevOps is because of how common it is for operators to build custom bash scripts to manage their day-to-day. We see a hole in the tooling landscape when it comes to reliable repeatable process that need to also exist outside of pipelines.
Here are some other components that make us a good fit for the CNCF landscape:
We are building on Markdown that can be checked into Git as the basic philosophy
Community building is a primary focus of the project and we work hard to operate in the open
The primary components of these Notebooks are bash or code that either calls a project's CLI, or talks directly to APIs, many of these use cases interface with cloud-native tools or cloud providers already
Out of the box we are a better way to share DevOps process that interacts with kubectl, terraform, helm, argo CD than what currently exists
We have already built cloud provider integrations to enhance the operational experience for Notebooks using them
Our Notebook data can be accessed over gRPC and consumed using Otel, making us a good fit for existing observability tooling
We are also working to provide an even more cloud-native onboarding experience through revamping our CLI to allow Runme projects to be initialized and configured with an init that generates a YAML
The Runme kernel is built with GoLang making it easy to be packaged, distributed and understood by our DevOps audience
We are already members of the Linux foundation
Cloud Native 'Integration'
We feel that interactive Notebooks complement basically any CNCF project that has a CLI or cloud dashboard that the user needs to understand and configure. Both from an educational/onboarding and day-to-day operational perspective. A great example is the overhead in knowing and running the numerous 'kubectl' commands with all their flags and arguments. Codifying these workflows as a Notebook makes it easy to follow along while passing data down the line and make sure that you not only get them right but also that the output is formatted in a way that is fit for human consumption.
Cloud Native Overlap
It is still way too hard to codify operational knowledge, which leads to a relatively high bar and constant learning of the different available tools and interfaces. This makes it really hard to stay competent when it comes to the cloud-native toolchain. We think we can lower the bar for the whole ecosystem, enabling more people to both get involved, contribute and also more effectively do their jobs.
Similar projects
N/A
Landscape
No
Business Product or Service to Project separation
Runme is the open source project, Stateful is the commercial company/product, the only place there is overlap is that the Runme VS Code extension and CLI have an integration with the hosted product allowing users to authorize using the VS Code account manager and push their data (notebook results) to our cloud. There is absolutely no requirement, obligation or OSS feature withholding involved.
Application contact emails
adam@stateful.com
Project Summary
Runme is a toolchain that turns Markdown into interactive, cloud-native, runnable Notebook experiences for DevOps.
Project Description
Runme: DevOps Notebooks Built with Markdown
Runme consolidates operational documentation and executable commands/code into interactive Notebooks or TUIs, seamlessly integrating with cloud-native infrastructure. The toolchain empowers engineering teams to build and maintain reliable, shareable documentation that can be tested in CI/CD.
Key Features:
Use Cases:
Runme’s kernel, exposed over gRPC, converts between Markdown and Notebook formats (as required by the client) and maintains the
.ENVstate across Notebook sessions, transforming Markdown into an interactive and reliable docs experience. Delivered as a VS Code platform compatible extension, Runme makes it easy to distribute Notebooks across environments like Codespaces, Gitpod, and VSCodium.For more, visit the Runme Documentation.
Org repo URL (provide if all repos under the org are in scope of the application)
N/A
Project repo URL in scope of application
https://github.com/stateful/runme
Additional repos in scope of the application
https://github.com/stateful/vscode-runme https://github.com/stateful/runme.dev https://github.com/stateful/docs.runme.dev https://github.com/stateful/runme-action
Website URL
https://runme.dev
Roadmap
https://github.com/stateful/runme/issues
Roadmap context
Roadmap is currently managed by prioritizing work in Github issues, but soon we'll be doing this using a project kanban.
The roadmap content is prioritized as follows:
Contributing Guide
https://github.com/stateful/runme/blob/main/CONTRIBUTING.md
Code of Conduct (CoC)
https://github.com/stateful/runme/blob/main/CODE_OF_CONDUCT.md
Adopters
No response
Contributing or Sponsoring Org
https://stateful.com
Maintainers file
https://github.com/stateful/runme/blob/main/MAINTAINERS.md
IP Policy
Trademark and accounts
Why CNCF?
Starting in my time at Buoyant I would attend Kubecon events, which have great energy. We've started exploring DevOpsDays, whose audience feels like the right place to build our community. Given the use-cases we see, it's clear that the intersection of devContainers, cloud-native, security/authorization and reproducible/reliable process for complex workflows is our bread and butter. We also see a lot of potential for partnering in the CNCF project landscape and adding value by lowering project barriers to entry, while collecting feedback to guide Runme to add the most tangible value.
Benefit to the Landscape
There is a huge opportunity for CNCF projects to embrace Runme as a more human friendly interface. Not just utilizing Runme for a nicer interface for their tool, but also to make the experience when using their tool more deeply integrated and intuitive. I continue to find it interesting that there are so many tools to support production cloud-native operations, but very little to support training, streamlining, educating and documenting the interfaces people need to really use them. Maybe it's time to open a new category?
Cloud Native 'Fit'
The simplest answer is that the tool is fairly agnostic and flexible about the specifics of the workflows being defined. But the reason that we moved from basic development flows to DevOps is because of how common it is for operators to build custom bash scripts to manage their day-to-day. We see a hole in the tooling landscape when it comes to reliable repeatable process that need to also exist outside of pipelines.
Here are some other components that make us a good fit for the CNCF landscape:
Cloud Native 'Integration'
We feel that interactive Notebooks complement basically any CNCF project that has a CLI or cloud dashboard that the user needs to understand and configure. Both from an educational/onboarding and day-to-day operational perspective. A great example is the overhead in knowing and running the numerous 'kubectl' commands with all their flags and arguments. Codifying these workflows as a Notebook makes it easy to follow along while passing data down the line and make sure that you not only get them right but also that the output is formatted in a way that is fit for human consumption.
Cloud Native Overlap
It is still way too hard to codify operational knowledge, which leads to a relatively high bar and constant learning of the different available tools and interfaces. This makes it really hard to stay competent when it comes to the cloud-native toolchain. We think we can lower the bar for the whole ecosystem, enabling more people to both get involved, contribute and also more effectively do their jobs.
Similar projects
N/A
Landscape
No
Business Product or Service to Project separation
Runme is the open source project, Stateful is the commercial company/product, the only place there is overlap is that the Runme VS Code extension and CLI have an integration with the hosted product allowing users to authorize using the VS Code account manager and push their data (notebook results) to our cloud. There is absolutely no requirement, obligation or OSS feature withholding involved.
Project presentations
No response
Project champions
No response
Additional information
No response