Announcing Atuin Desktop's Redesigned Runbook Execution Engine

We are excited to announce a significant architectural improvement to Atuin Desktop: a completely redesigned runbook execution engine. This major change marks the first critical step towards establishing runbooks as a core automation primitive.

If you have experienced issues with flaky context, disappearing state, or inconsistent execution, this release provides a robust solution. Runbooks now maintain their state, behave predictably, and eliminate the need for constant re-execution to restore your working environment. This update also lays the groundwork for enhanced real-time collaboration and CLI-based execution.

Runbooks should execute reliably. Workflows should not be confined to individual knowledge, and documentation should remain relevant. Atuin Desktop combines the clarity of a document with the power of your terminal, built to make local developer workflows repeatable, shareable, and reliable.

What's New?

Persistent

Runbooks now retain their state exactly as you left them, eliminating the need for rebuilds, re-running blocks, or unnecessary friction. Previously, closing a tab or restarting Atuin Desktop would result in the loss of all execution state. With the new engine, your runbook's context—which encompasses all execution-related state—now persists across application restarts and tab closures.

Practically, this means if you execute a command like mktemp -d to create a temporary directory and save its path to a template variable, that output is now saved locally with your runbook. Close the tab or restart the app, and the context is still there, removing the necessity to re-execute blocks to rebuild your working environment.

Reproducible

Runbooks now behave consistently and predictably every time. The new engine establishes a clear, predictable flow of context throughout your runbooks. Each block in your document can only influence the blocks positioned below it. Consequently, setting a template variable in one block will not affect the usage of that same variable in any preceding blocks.

A block’s context only affects blocks below it

With these fundamental improvements, we have further advanced the template system:

Templates Everywhere

All user input is now processed through our template system. This allows you to utilize templates in variable names, context blocks such as directory and SSH configurations, and any other block that accepts input. If you discover any input that does not adhere to this behavior, please report it as a bug; we are keen to address such issues!

Self-Referential Variables

Given that all inputs pass through the template system and variables do not influence context above them, it is now possible for a variable to refer to itself. For instance, you can trim a newline character from a variable named output by using {{ var.output | trim }} and reassigning it back to output. This enables advanced variable metaprogramming.

We heard you like variables

Two Types of Execution Context

The new engine introduces two distinct types of context:

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

  • Working directory changes
  • Environment variable definitions
  • SSH host connections
  • Explicit template variable assignments This context remains active even when you are not actively running blocks.

• Active Context is set during block execution and represents the output and runtime state of actively running blocks. When a block is re-executed, its active context is cleared and rebuilt. The active context contains data stored 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, providing an option to start with a clean slate.

Reset your runbook’s execution state at any time

Foundation for Future Collaboration

Atuin Desktop already supports real-time collaboration for editing runbook content. This new architecture, however, provides the foundation to extend this capability even further, enabling truly 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

This update modifies how blocks can interact with one another. Consequently, you may need to adjust any existing runbooks that relied on the previous global context (e.g., setting a template variable in a block and using that variable in a block above where it was defined).

Editor Variable Sync

In the previous execution system, the editor block featured a toggle to synchronize its value with a variable in the context. Any change to the variable within the document would automatically update the editor. This behavior is not compatible with the new architecture, where context is no longer global. Therefore, we have removed this 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 variable

No Standard Error in Script Variables

Script output variables now capture only standard output (stdout), not standard error (stderr). This prevents error messages and diagnostics from mixing with your actual output data, resulting in cleaner and more reliable variables. You will still see both stdout and stderr in the block's terminal output.

Under the Hood

For those interested in the technical specifics, this update involved a complete overhaul of our block execution system. We migrated it from our legacy TypeScript-based front-end system to the existing Rust backend. Every block has been moved to this new system, enhancing its portability and reliability.

Each block now implements a BlockBehavior trait, which defines key methods:

• passive_context: Returns any context that should be set passively whenever the document changes.
• execute: Executes the block, sending messages to the client to update active context and other relevant data.

Other useful traits, such as QueryBlockBehavior, enable quick definition of blocks that query data sources and return tabular results. Combined with traits like MessageChannel (for sending messages to the client) and BlockContextStorage (for saving and loading context data), this new architecture has allowed us to completely separate the runtime system from the desktop application, opening the door for runbook execution in any environment. For comprehensive technical details, please consult the execution system documentation in the repository.

What's Next?

CLI Runner

Execute your runbooks from any terminal, even if Atuin Desktop is not installed. The new runtime is designed to be environment-agnostic, enabling runbook execution in CI/CD pipelines, deployment scripts, or automated workflows.

It’s shells all the way down

Improved Serial Execution

Running a runbook from top-to-bottom—referred to as "serial execution"—currently requires the runbook to be open in your editor. Thanks to the new runtime, we will remove this constraint and introduce enhanced tooling for monitoring and controlling runbook executions both inside and outside the application.

Secrets Management

Secrets are a critical component of infrastructure management, and runbooks are no exception. We will be adding first-class support for storing and retrieving secrets, both locally and in the cloud, with end-to-end encryption.

Markdown-Based Runbooks

Markdown is a ubiquitous format in modern development, known for its lightweight nature, readability, and compatibility with any text editor. We are working towards storing runbooks as pure Markdown files with embedded metadata, making them more portable, easier to write, review, and version control.

We welcome your feedback on terminals or runbooks.

Try It Out

The new execution engine is available now in Atuin Desktop v0.2.0. Update your installation to experience these improvements firsthand.