# How Maka's Local-First Agent Workspace Architecture Differs from Remote Agent Services > Discover how Maka's local-first agent workspace architecture empowers local state storage and execution authority, contrasting with remote agent services that offer extensions. - Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka) - Tags: architecture - Published: 2026-08-26 --- **Maka's local-first agent workspace architecture stores all interactive state—including durable ledgers, session data, tool runtimes, and user-owned Project files—in a local State Root directory, making the Runtime Host the sole execution authority, while remote agent services function as optional, isolated Runtime Host profiles that extend rather than replace this baseline local model.** Apache Maka is engineered as a local-first agent workspace that guarantees data sovereignty and execution authority remain under the user's direct control. Unlike conventional remote agent services that centralize state on external infrastructure, Maka's architecture ensures all work persists through crashes and reloads without network dependency. This design fundamentally inverts the traditional client-server model by establishing the local machine as the canonical authority for all agent operations. ## Core Principles of Local-First Design ### The State Root and Local Persistence At the heart of Maka's architecture lies the **State Root** directory, a persistent location on the user's file system that houses all interactive state. According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), this includes SQLite databases, ledger files, and session data that survive application restarts and system crashes. All user-owned Project files remain physically stored on the local machine unless explicitly exported, ensuring complete data sovereignty and offline functionality. ### The Runtime Host as Execution Authority The **Runtime Host** serves as the sole execution authority in Maka's local-first model. As implemented in the source code, this component owns the session and turn identity, manages agent lifecycles, enforces permissions, and maintains the canonical event log. When operating locally, the Runtime Host runs entirely on the client machine, scheduling sessions and running tools without external dependencies. This contrasts sharply with remote agent services, where execution authority resides on infrastructure outside the user's immediate control. ## Architectural Differences: Local-First vs. Remote Services ### State Storage and Durability In Maka's local-first agent workspace architecture, state storage is **persistent on the client's file system** using SQLite and ledger files that survive reloads and crashes. Remote agent services, by comparison, maintain state on a remote host; the client only receives a view of that remote state, creating dependency on external storage systems for session continuity. ### Execution Authority Distribution The local **Runtime Host** functions as the singular execution authority when operating in default mode. Remote services expose a Runtime Host via TLS, SSH, or WebSocket protocols, but these function as *additional* hosts that the client explicitly connects to. According to [`packages/runtime/src/message-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/message-authority.ts), both local and remote hosts implement the `RuntimeHostedRootAuthority` interface, ensuring consistent security contracts regardless of location. ### Data Sovereignty and Privacy User-owned data never leaves the local machine in the local-first model unless explicitly exported. Remote agent services process data on the remote host, requiring trust in the remote profile's permission boundaries and infrastructure security. This distinction makes Maka suitable for sensitive workflows where data residency is non-negotiable. ### Failure Semantics and Crash Recovery Crash recovery in the local-first architecture is handled by the local Runtime Host using the durable ledger (see the *Runtime resume* architecture in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)). A remote host failure does not affect local sessions, but conversely, remote sessions abort immediately if the network connection is lost, whereas local sessions continue uninterrupted. ### Network Dependence and Offline Capability Maka's local-first design remains **fully functional offline**; only remote services require network connectivity. Remote agent services demand an active network link—whether TLS, SSH, or explicit plaintext—to establish and maintain sessions with the remote Runtime Host. ## Remote Runtime Hosts as Architectural Extensions When integrating remote capabilities, Maka treats external hosts as **another Runtime Host profile** rather than replacing the local authority. As documented in [`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md), a remote profile points to a specific State Root on the remote machine, with client credentials scoped exclusively to that profile. The local Runtime Host remains the default authority for sessions that do not explicitly target a remote profile, maintaining the local-first baseline while extending capability through optional remote runtimes. ## Practical Implementation: Local and Remote Workflows ### Running Tasks with the Default Local Runtime Host To execute agent tasks using the built-in local authority: ```bash # Uses the built-in local Runtime Host maka run "Summarize the contents of ./project" ``` This command operates entirely within the local State Root, requiring no network connectivity and persisting all state changes to the local ledger. ### Configuring a Remote Runtime Host Profile To add a remote host using TLS authentication: ```bash export MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL='' maka runtime-host profile set \ --id office \ --name "Office TLS" \ --tls-url wss://office.example.com:7443/runtime-host \ --expected-root '' ``` This configuration creates a new Runtime Host profile that the CLI can target for specific sessions while maintaining the local workspace as the default. ### Executing Tasks on Remote Hosts To run operations on a remote Runtime Host: ```bash # Select the remote profile and a remote project maka --host office --project '' \ run "Generate a report for this repository" ``` The `--host` flag explicitly routes execution to the remote profile, though the local client still manages the session metadata and user interface. ### Returning to the Local Workspace To switch back to local-first operation: ```bash maka --host local --project '' run "Search local notes" ``` The `--host local` flag explicitly selects the default local Runtime Host, ensuring all execution and state changes remain on the client machine. ## Source Code Architecture The implementation of Maka's local-first agent workspace architecture spans several key files: - **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** provides the high-level description of the Runtime Host, SessionManager, and the local-first authority model that governs all agent interactions. - **[`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md)** details the configuration patterns for connecting to remote Runtime Hosts via TLS, SSH, or plaintext transports. - **[`packages/runtime/src/message-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/message-authority.ts)** defines the `RuntimeHostedRootAuthority` interface, which both local and remote hosts implement to ensure consistent authority semantics across deployment modes. - **[`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts)** implements the WebSocket transport layer used for communicating with remote Runtime Hosts, encapsulating the network-specific logic while preserving the local-first abstractions. - **[`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md)** documents Maka's identity as a local-first agent workspace and explains how the CLI interacts with both local and remote Runtime Hosts through unified command patterns. ## Summary - Maka's local-first agent workspace architecture stores all state in a local **State Root** directory using SQLite and ledger files, ensuring data persists through crashes without network dependency. - The **Runtime Host** serves as the sole execution authority locally, owning session identity, agent lifecycles, and the canonical event log. - Remote agent services function as optional **Runtime Host profiles** that extend the local baseline rather than replacing it, with credentials scoped to specific remote State Roots. - The `RuntimeHostedRootAuthority` interface in [`packages/runtime/src/message-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/message-authority.ts) unifies local and remote execution models under consistent security contracts. - Users maintain complete **data sovereignty** in local mode, while remote operations require explicit host selection via the `--host` flag and active network connectivity. ## Frequently Asked Questions ### What happens to my session data if the Maka Runtime Host crashes locally? The local Runtime Host recovers session data using the durable ledger stored in the State Root directory. Because all state persists locally in SQLite and ledger files, restarting the application resumes the exact session state prior to the crash, with no data loss or network dependency required. ### Can I use Maka entirely without an internet connection? Yes. Maka's local-first agent workspace architecture is fully functional offline. The default local Runtime Host requires no network connectivity to execute tasks, manage projects, or persist state. Network connections are only necessary when explicitly targeting a remote Runtime Host profile. ### How does Maka secure connections to remote Runtime Hosts? Remote connections are secured through the `RuntimeHostedRootAuthority` interface implementation and transport-layer encryption. As shown in [`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts), remote hosts communicate via TLS-encrypted WebSockets (WSS), SSH tunnels, or explicitly configured plaintext connections, with credentials scoped exclusively to specific remote profiles. ### Does adding a remote Runtime Host replace my local workspace? No. Remote hosts function as additional execution contexts that you explicitly select using the `--host` flag. The local Runtime Host remains the default authority for all sessions unless you specify otherwise, ensuring that the local-first architecture serves as the immutable baseline while remote services provide optional extension capabilities.