How Maka's Local-First Agent Workspace Architecture Differs from Remote Agent Services

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, 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, 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). 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, 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:

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

export MAKA_RUNTIME_HOST_ACCESS_CREDENTIAL='<credential>'

maka runtime-host profile set \
  --id office \
  --name "Office TLS" \
  --tls-url wss://office.example.com:7443/runtime-host \
  --expected-root '<remote‑root‑id>'

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:

# Select the remote profile and a remote project

maka --host office --project '<project-id>' \
     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:

maka --host local --project '<local-project-id>' 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 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 details the configuration patterns for connecting to remote Runtime Hosts via TLS, SSH, or plaintext transports.

• 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 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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}