# How Maka's Local-First Architecture Works: Runtime Host and SQLite Ledger

> Discover Maka's local-first architecture. Learn how the Runtime Host and SQLite ledger manage execution state, user data, and session history with full data sovereignty.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: architecture
- Published: 2026-08-24

---

**Maka stores all execution state, user data, and session history locally in a SQLite ledger, using a single Runtime Host to coordinate all interactions while ensuring crash recovery and complete data sovereignty.**

Apache Maka implements a strict local-first design where AI agent execution state never leaves the user's machine unless explicitly configured. This architecture centers on a single **Runtime Host** that manages every entry point—Desktop GUI, TUI, CLI, and bots—while persisting every interaction to a durable SQLite database. By keeping the `runtime.sqlite` ledger, credential vault, and workspace settings on local disk, Maka ensures users retain full ownership of their data and can recover interrupted sessions without cloud dependencies.

## The Runtime Host: Single Authority for Local Execution

All client interfaces submit work to the **Runtime Host**, the sole execution authority in Maka's architecture. According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), the Runtime Host owns session identity, tool sandboxing, permission checks, and the durable event log that records every turn. This design eliminates distributed state management—whether you interact via the Electron Desktop app, the TUI, or the CLI, all requests route through the same local authority that maintains the canonical session state.

This centralization ensures that **model messages**, **tool calls**, **results**, and **termination facts** all flow through one coordinator before persisting to disk. The Runtime Host acts as the boundary between user-facing interfaces and the operational storage layer.

## Durable Event Log and SQLite Ledger

Maka's local-first guarantee relies on an **append-only SQLite ledger** stored at `runtime.sqlite` within the Electron `userData` directory. As documented in the repository's README, this log serves as the *canonical source* for any reconstruction or replay of a turn. Every event—whether a model generation, tool execution, or session termination—writes immediately to this local database.

The physical workspace location typically resides at `apps/desktop/userData/workspaces/default/`, containing:
- `runtime.sqlite` – The operational ledger storing all turns
- [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) – Local service configurations
- [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) – User secrets stored as local plaintext readable only by the OS account
- [`settings.json`](https://github.com/apache/maka/blob/main/settings.json) – User preferences and runtime configuration

Nothing automatically transmits to remote services unless the user explicitly configures a cloud-based model or external tool provider.

## Crash Recovery and Session Resumption

Because every turn records to the durable log, Maka supports **crash-safe recovery** without data loss. When the environment variable `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` is enabled, the Runtime Host can resume an interrupted turn by replaying events from `runtime.sqlite`. This mechanism reads the immutable event structures defined in [`packages/core/RuntimeEvent.ts`](https://github.com/apache/maka/blob/main/packages/core/RuntimeEvent.ts) to reconstruct the exact state prior to the crash.

The recovery process demonstrates the power of local-first architecture: the system needs no cloud checkpointing or external database to restore complex, multi-tool agent workflows.

## Modular Package Boundaries

Maka separates local-first concerns into six clearly bounded packages, as detailed in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md):

- **`packages/core`** – Defines contracts for sessions, events, and permissions
- **`packages/storage`** – Implements SQLite stores for operational state
- **`packages/runtime`** – Contains [`SessionManager.ts`](https://github.com/apache/maka/blob/main/SessionManager.ts), `AgentRun`, model adapters, tools, context management, and recovery logic
- **`packages/runtime-host`** – The sole hosted execution authority that enforces the local-first boundary
- **`packages/cli`** – TUI and non-interactive CLI that share the same Runtime Host as the Desktop app
- **`apps/desktop`** – Electron UI that communicates with the Runtime Host via local IPC

This modularity ensures that storage, execution, and interface concerns remain isolated while all components respect the single authority of the Runtime Host.

## Working with Local Storage

You can inspect Maka's local-first storage directly using standard SQLite tools and the TypeScript SDK.

Clone and run Maka locally:

```bash

# Clone and install Maka (all data stays local)

git clone https://github.com/apache/maka.git
cd maka
npm ci

# Start the desktop UI – workspace files are created under

# <Electron userData>/workspaces/default/

npm run dev

```

Execute a turn via CLI and inspect the ledger:

```bash

# Run a turn via CLI; the ledger persists automatically

npm run cli:dev -- run "Summarize this repository"

# Inspect the SQLite schema and tables directly

sqlite3 ./apps/desktop/userData/workspaces/default/runtime.sqlite ".tables"
sqlite3 ./apps/desktop/userData/workspaces/default/runtime.sqlite "SELECT * FROM events LIMIT 5;"

```

Programmatically read the event log from the runtime package:

```typescript
import { RuntimeEventLog } from "@maka/runtime";

const log = new RuntimeEventLog("/path/to/runtime.sqlite");
const events = await log.readAll(); // All events stored locally
console.log(events);

```

## Summary

- **Single Runtime Host** acts as the execution authority for Desktop, CLI, and TUI interfaces, ensuring consistent local state management.
- **SQLite ledger** (`runtime.sqlite`) stores every model message, tool call, and result as an append-only log for canonical reconstruction.
- **Crash recovery** works by replaying events from the durable log, enabled via the `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` environment variable.
- **Local data sovereignty** means workspace files, credentials, and settings reside in the Electron `userData` directory unless explicitly configured otherwise.
- **Modular architecture** separates core contracts, storage, runtime logic, and interfaces while maintaining strict local-first boundaries.

## Frequently Asked Questions

### Where does Maka store conversation history and execution state?

All conversation history and execution state persist in a local SQLite database named `runtime.sqlite`, located within the Electron `userData` directory (typically `apps/desktop/userData/workspaces/default/`). This includes every model message, tool invocation, and result, stored as immutable events defined in [`packages/core/RuntimeEvent.ts`](https://github.com/apache/maka/blob/main/packages/core/RuntimeEvent.ts).

### Can Maka resume an AI agent turn after a crash or power loss?

Yes. When the `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME` environment variable is set, the Runtime Host can resume an interrupted turn by reading and replaying events from the local SQLite ledger. Because `packages/storage` maintains an append-only log of all actions, the system reconstructs the exact execution context without requiring cloud connectivity.

### How does Maka keep credentials secure in a local-first model?

User credentials and connection secrets are stored in [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) as local plaintext, readable only by the operating system user account owning the process. Unlike cloud-hosted solutions, this vault never transmits to external servers unless the user explicitly configures a remote model provider or tool integration.

### How do the Desktop UI and CLI share the same local state?

Both the Electron Desktop application (`apps/desktop`) and the command-line interface (`packages/cli`) communicate with the same **Runtime Host** process. Because the Runtime Host maintains the canonical SQLite ledger and session management in [`packages/runtime/SessionManager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/SessionManager.ts), all interfaces operate against identical local state without synchronization conflicts.