Atuin Desktop Documentation

Atuin Desktop is a local-first, executable runbook editor designed for terminal-heavy workflows. It bridges the gap between static documentation and automation by allowing users to create executable runbooks.

Core Concepts

• Executable Runbooks: Instead of just reading instructions, you can execute shell commands, database queries, and HTTP requests directly within the document.
• Embedded Execution: The interface includes terminal blocks for direct execution, database clients for live queries, and integrations for monitoring tools like Prometheus.
• Dynamic Templating: Uses Jinja-style templating to allow for variable substitution, conditional logic, and parameterized workflows (e.g., switching between staging and production environments).
• Local-First & Sync: Built with a CRDT-powered architecture, it works offline and synchronizes with Atuin Hub when connected, enabling collaborative runbook management.

Blocks in Atuin Desktop are categorized by their primary function: performing work or modifying the environment.

Execution Blocks

These blocks perform active tasks such as running commands, making network requests, or querying data:

• Script: Executes shell commands.
• Terminal: Starts interactive terminal sessions.
• Http: Performs HTTP requests.
• Postgres, MySQL, SQLite, Clickhouse: Executes database queries.
• Prometheus: Performs metrics queries.

Context Blocks

These blocks modify the execution environment for all subsequent blocks in the runbook using the passive_context method:

• Directory: Changes the working directory.
• LocalDirectory: Changes the working directory (note: this change is not persisted in the Runbook).
• Environment: Sets environment variables.
• Host: Selects a host for SSH connections.
• SshConnect: Configures SSH connection settings.
• Var: Sets document-level variables.
• LocalVar: Sets a variable (note: this change is not persisted in the Runbook).

The Grand Central (GC) event system is a robust, type-safe foundation for event-driven communication in Atuin Desktop. It facilitates communication between the backend (Rust) and the frontend (TypeScript) while maintaining strict architectural boundaries.

Key Architectural Benefits

• Boundary Preservation: The runtime layer maintains zero Tauri dependencies and uses clean interfaces (event emission through traits rather than concrete types) to ensure isolation.
• Type Safety: The system uses ts-rs to ensure that frontend TypeScript types match backend Rust types, providing compile-time guarantees and full IDE autocomplete.
• Performance: Events are emitted asynchronously to prevent blocking execution. The system uses a single efficient transport channel and supports selective subscription so components only process relevant events.
• Maintainability: All events are centralized in one system, making the system self-documenting and easy to extend without breaking changes.
• Developer Experience: Provides a global instance for easy access, simple subscription patterns, and automatic lifecycle management (cleanup and error handling).

The execution system follows a specific lifecycle for managing runbooks (documents) and their constituent blocks:

1. Document Opening: Triggered by open_document. The system creates a DocumentHandle, spawns a DocumentActor, parses blocks, loads active contexts from disk, and builds initial passive contexts.
2. Document Updates: Triggered by update_document. The actor identifies changed blocks, determines the earliest index requiring a rebuild, and rebuilds passive contexts for affected blocks, sending updates to the frontend.
3. Block Execution: Triggered by execute_block. The system creates an ExecutionContext using a ContextResolver (built from all blocks above the target), clears the block's active context, and calls block.execute(context).
4. Async Execution: Blocks typically spawn background tasks (e.g., via tokio::spawn). During execution, blocks can update their active context with output variables and finally update their execution status.
5. Handle Management: Execution handles are stored in state.block_executions to allow for task cancellation.

#[tauri::command]
pub async fn open_document(
    state: State<'_, AtuinState>,
    document_id: String,
    document: Vec<serde_json::Value>,
    document_bridge: Channel<DocumentBridgeMessage>,
) -> Result<(), String>