Atuin’s New Runbook Execution Engine
Recorded: Nov. 29, 2025, 1:09 a.m.
| Original | Summarized |
Introducing the New Runbook Execution Engine Home Introducing the New Runbook Execution Engine Michelle Tilley 24 Nov 2025 We're excited to announce a major architectural improvement to Atuin Desktop: a completely redesigned runbook execution engine.This is a huge change, the first big step toward making runbooks a core automation primitive. If you’ve ever hit flaky context, disappearing state, or inconsistent execution, this release fixes it. Runbooks now keep their state, behave predictably, and don’t require constant re-running just to get back to where you were. We're laying the foundation for enhanced real-time collaboration and CLI-based execution. Runbooks should run. Workflows shouldn't live in someone's head. Docs shouldn't rot the moment you write them.Atuin Desktop looks like a doc, but runs like your terminal. Built to make local developer workflows repeatable, shareable, and reliable. Download Atuin Desktop What's New?PersistentRunbooks stay how you left them. No rebuilds. No re-running blocks. No friction.Previously, when you closed a tab or restarted Atuin Desktop, all execution state was lost. With the new execution engine, your runbook's context - which stores all of the execution-related state - now persists across app restarts and tab closures.In practice, this means that if you run a command like mktemp -d to create a tempflorary directory and save it to a template variable, that output is now saved locally along with your runbook. Close the tab or restart the app, and the context is still there - no need to re-execute blocks to rebuild your working environment.ReproducibleRunbooks behave the way you expect, every time.The new engine establishes a clear, predictable flow of context through your runbooks. Each block in your document can only influence the blocks below it. This means that, for example, setting a template variable in a block will not affect that same variable's usage in any blocks above it.A block’s context only affects blocks below itWith the fundamentals fixed, we pushed the template system further:Templates EverywhereWe now run all user input through our template system. This means you can use templates in variable names, context blocks like directory and SSH, and any other block that accepts input. If you find any input that doesn’t behave this way, it’s a bug and we’d love to know about it!Self-Referential VariablesSince all inputs run through the template system and variables don’t affect context above them, it’s possible for a variable to refer to itself. For example, you could trim the newline off a variable named output by using {{ var.output | trim }} and assigning it back to output again. You can get as deep as you want with variable metaprogramming:We heard you like variablesTwo Types of Execution ContextThe new engine introduces two types of context:Passive Context is set automatically when your document updates. This includes:Working directory changesEnvironment variable definitionsSSH host connectionsExplicit template variable assignmentsThis context persists even when you're not actively running blocks.Active Context is set during block execution and represents the output and runtime state of actively running blocks. When you re-run a block, its active context is cleared and rebuilt.The active context contains the data we store locally with your runbook, and persists across app restarts. A new button in the runbook header allows you to clear all active context for a runbook, in case you want to start with a clean slate.Reset your runbook’s execution state at any timeFoundation for Future CollaborationAtuin Desktop already supports real-time collaboration for editing runbook content, but the new architecture lays the groundwork to take this even further, setting us up for real collaborative execution. Imagine sharing not just the document, but the entire running environment - including environment setup, terminal output, and database query results - all in real time!What's Changed?No More Global ContextBecause this update changes the way blocks can affect one another, you may need to adjust any runbooks that relied on the old, global context (for example, setting a template variable in a block and using that variable in a block above the block that set it).Editor Variable SyncIn the old execution system, the editor block contained a toggle that kept the value in the editor in sync with a variable in the context. Whenever the variable changed anywhere in the document, the editor would update to reflect that change.This behavior doesn't work well with the new architecture, where context is no longer global. For this reason, we've removed the toggle, and replaced it with a UI element that allows you to manually set the editor content to the value of any defined template variable.Update an editor block's content to match the value of any available variableNo Standard Error in Script VariablesScript output variables now capture only stdout, not stderr. This prevents error messages and diagnostics from mixing with your actual output data, making variables cleaner and more reliable. You'll still see both stdout and stderr in the block's terminal output.Under the HoodFor those interested in the technical details, this update involved rewriting our entire block execution system, migrating it from our old front-end system written in TypeScript to the existing Rust backend. We've migrated every block to the new system, making every block's execution more portable and reliable.Each block implements a BlockBehavior trait, defining a couple key methods:passive_context - returns any context that should be set passively any time the document changesexecute - executes the block, sending messages to the client to update active context and any other relevant dataThere are other useful traits, such as QueryBlockBehavior, which allows quickly defining a block that queries a data source and returns a table of results.Combined with traits like MessageChannel (to facilitate sending messages to the client) and BlockContextStorage (to save and load context data), the new architecture has allowed us to completely extract the runtime system from the desktop application, paving the way for executing runbooks in any environment.For all the juicy details, check out the execution system docs in the repository.What's Next?CLI RunnerRun your runbooks from any terminal, even if Atuin Desktop isn't installed. The new runtime is designed to be environment-agnostic, making it possible to execute runbooks in CI/CD pipelines, deployment scripts, or automated workflows.It’s shells all the way downImproved Serial ExecutionRunning a runbook from top-to-bottom - which we call "serial execution" - currently depends on the runbook being open in your editor. Thanks to the new runtime, we'll be able to remove this constraint, and introduce improved tooling for monitoring and controlling runbook executions both inside and outside the app.Secrets ManagementSecrets are one of the most critical aspects of infrastructure management, and runbooks are no exception. We'll be adding first-class support for storing and retrieving secrets both locally and in the cloud, encrypted end-to-end.Markdown-Based RunbooksMarkdown is ubiquitous in modern development. It's lightweight, easy to read, and can be edited in any text editor. We're working on storing runbooks as pure markdown files with embedded metadata, making them more portable and easier to write, review, and version control.💬Got thoughts about terminals or runbooks? Grab a slot hereTry It OutThe new execution engine is available now in v0.2.0. Update your Atuin Desktop installation and experience the difference yourself.Community linksDiscord: DiscordForum: Forum Read more Atuin Desktop: Runbooks that Run — Now Open Source 30 Sep 2025 Atuin Desktop: Runbooks that Run 22 Apr 2025 Atuin Scripts: Shareable, Syncable Shell Snippets Your shell history holds a record of your 09 Apr 2025 Atuin v18.4.0 Announcing a new release of Atuin! v18.4 27 Dec 2024 Powered by Ghost Atuin Updates and news about Atuin, the magical shell tool Subscribe |
The Atuin Desktop team has announced a significant architectural overhaul of its runbook execution engine, marking a pivotal step toward establishing runbooks as a core automation primitive. This redesign addresses longstanding issues of flaky context, disappearing state, and inconsistent execution, fundamentally changing how runbooks operate. The core change centers around persistent, predictable runbook execution, allowing for repeatable and reliable workflows. Previously, runbooks suffered from a critical limitation: when a tab was closed or the Atuin Desktop application was restarted, all execution state was lost, requiring users to re-run blocks to restore the environment. The new execution engine permanently resolves this by introducing persistent runbooks. This means that state – including the output of commands like `mktemp -d` and the saved value of template variables – is now automatically preserved across app restarts and tab closures. This eliminates the friction of needing to constantly re-initialize the environment. The redesign also establishes a predictable flow of context through runbooks, preventing unintended side effects between blocks. A block’s context only influences blocks that follow it, guaranteeing a consistent and manageable execution environment. This is significantly aided by the introduction of a template system. All user inputs now flow through a template system, enabling the utilization of templates in variable names, context blocks, and other input areas. If a user finds an input that doesn't utilize this system, it’s identified as a bug. The new engine introduces two distinct types of context: Passive Context and Active Context. Passive Context is automatically set whenever a runbook document updates which includes changes to the working directory, environment variable definitions, and SSH host connections. Active Context is set during block execution and represents the runtime state including any output and data. When a block is re-run, its active context is cleared and rebuilt. The execution system is designed to be modular and adaptable. The team has implemented a BlockBehavior trait, defining two key methods: `passive_context` and `execute`. This allows for a flexible and extensible design. Furthermore, the team implemented a MessageChannel trait to facilitate communication between blocks and the client, and a BlockContextStorage trait to manage context data. Ultimately, these components have enabled the complete extraction of the runtime system from the desktop application, paving the way for executing runbooks in any surrounding environment. Looking ahead, the team is focusing on several key developments. One planned feature is a CLI runner, which would allow users to execute runbooks from any terminal, even if Atuin Desktop isn't installed. The team aims to make the runtime environment agnostic, supporting execution in environments like CI/CD pipelines or automated workflows. Another critical development is improved serial execution—currently reliant on the runbook being open within the editor—through better tooling for monitoring and controlling runbook executions. Additionally, the team is addressing secrets management with first-class support for storing and retrieving secrets, both locally and in the cloud, with end-to-end encryption. Finally, they're exploring Markdown-based runbooks, allowing users to store runbooks as pure markdown files with embedded metadata, which increases portability and eases version control. |