Introducing the New Runbook Execution Engine

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.

What's New?

Persistent

Runbooks 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.

Reproducible

Runbooks 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.

With the fundamentals fixed, we pushed the template system further:

Templates Everywhere

We 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 Variables

Since 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:

Two Types of Execution Context

The new engine introduces two types of context:

Passive Context is set automatically when your document updates. This includes:

• Working directory changes
• Environment variable definitions
• SSH host connections
• Explicit template variable assignments

This 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.

Foundation for Future Collaboration

Atuin 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 Context

Because 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 Sync

In 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.

No Standard Error in Script Variables

Script 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 Hood

For 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 changes
• execute - executes the block, sending messages to the client to update active context and any other relevant data

There 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 Runner

Run 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.

Improved Serial Execution

Running 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 Management

Secrets 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 Runbooks

Markdown 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.

Try It Out

The new execution engine is available now in v0.2.0. Update your Atuin Desktop installation and experience the difference yourself.

Community links

Discord: Discord

Forum: Forum