How Apache Maka Implements a Local-First Agent Workspace: Architecture Deep Dive

Apache Maka implements a local-first agent workspace through three integrated mechanisms: NPM-style workspace resolution for local package mapping, immutable SQLite-based append-only ledgers for durable session state, and a sandboxed runtime host that executes all file operations within a user-controlled directory.

Apache Maka is an open-source framework designed to run AI agents entirely on local hardware without dependency on remote servers. The platform implements a local-first agent workspace that ensures all code, conversation history, and file operations remain on the user's machine unless explicitly exported. This architecture provides durability, privacy-by-default, and the ability to replay or resume terminated sessions exactly where they left off.

NPM-Style Workspaces for Local Package Resolution

The foundation of Maka's local-first approach begins with workspace discovery. The system treats the agent itself as an NPM workspace residing in a normal directory on the user's machine, discovered by reading the workspaces field in package.json.

In scripts/windows-package-source-closure.mjs, the workspace source plugin resolves imports prefixed with @maka/... to local workspace directories. Lines 71-85 implement the mapping logic that walks the workspace paths declared in the top-level package.json and resolves imports to <workspace-dir>/src/... without contacting any external registry. This ensures the maka-agent package and its dependencies resolve locally, enabling offline operation.

Append-Only Ledgers for Durable State Management

Every model message, tool call, permission decision, and runtime event is persisted to an immutable, append-only ledger stored in SQLite tables. Because the ledger never rewrites historical data, the entire session remains reproducible and recoverable.

The implementation resides in packages/storage/src/task-ledger-store.ts. Lines 48-57 define the task ledger store that writes events to the workflow_task_ledger_events table and enforces a hard cap on total tasks per session. This append-only structure ensures that if the host crashes, the ledger can be replayed to reconstruct the exact file state and conversation context, providing the durability guarantee fundamental to the local-first paradigm.

Workspace-Aware Runtime Host and Security Sandboxing

The Runtime Host—the process responsible for executing the LLM agent—operates within a strictly sandboxed environment where all file-system operations are confined to the workspace directory.

Launch scripts such as scripts/verify-windows-sandbox-e2e.mjs (lines 120-130) demonstrate this by creating a temporary directory, passing it as the current working directory (cwd) to the Runtime Host, and verifying that no write operations escape the workspace boundaries. The host stores the ledger path under <workspace>/ledger, enabling automatic recovery and state reconstruction after unexpected termination. All external calls, including model APIs and tool binaries, require explicit permission, ensuring the workspace remains "private by default."

Practical Implementation: Working with the Workspace

Developers interact with these components through TypeScript APIs that abstract the underlying storage and resolution mechanisms. The following workflow demonstrates resolving the workspace, using the source plugin, and recording operations to the immutable ledger.

First, resolve the workspace root by reading the repository's package.json workspaces configuration:

import { resolve } from 'node:path';
import { readFileSync } from 'node:fs';

const repoRoot = resolve(__dirname, '..');
const rootPkg = JSON.parse(readFileSync(`${repoRoot}/package.json`, 'utf8'));
const workspaces = rootPkg.workspaces ?? [];

Use the workspace source plugin to map internal imports to local directories:

import { workspaceSourcePlugin } from '../scripts/windows-package-source-closure.mjs';
const plugin = workspaceSourcePlugin(repoRoot, new Map(/* … populated from workspaces … */));

Open a task ledger for a new session within the workspace:

import { openInteractiveTaskLedgerStoreForWrite } from '@maka/storage';
import { join, mkdir } from 'node:path';

const workspace = join(repoRoot, 'workspace');
await mkdir(workspace, { recursive: true });

const ledger = await openInteractiveTaskLedgerStoreForWrite({
  workspaceRoot: workspace,
  sessionId: 'session-001',
});

Record a task to the append-only ledger, which the UI renders via packages/ui/src/task-ledger-panel.tsx:

await ledger.append({
  key: 'tool-run',
  subject: 'Run echo',
  status: 'completed',
  meta: { command: 'echo Hello' },
});

Version Authority and Workspace Evolution

The architecture includes formal specifications for workspace versioning and upgrade semantics without breaking reproducibility. The docs/architecture/runtime-workspace-version-authority-v1.md document explains how workspace versions are anchored in the ledger, ensuring that upgrades apply deterministically.

Additionally, docs/architecture/agent-graph-stream-scheduling-draft.md details how the agent-graph stream scheduler records task execution in the ledger, maintaining the append-only guarantee across complex multi-step workflows while keeping all scheduling decisions local to the workspace.

Summary

• NPM-style workspaces enable local resolution of all @maka/* imports through the plugin in scripts/windows-package-source-closure.mjs, eliminating remote registry dependencies.
• Append-only ledgers in packages/storage/src/task-ledger-store.ts provide immutable storage for all session events, enabling exact recovery and replay of terminated sessions.
• Sandboxed execution via the Runtime Host confines all file operations to the workspace directory, with verification logic in scripts/verify-windows-sandbox-e2e.mjs ensuring no data escapes local boundaries.
• Privacy-by-default architecture ensures no data leaves the local machine unless explicitly exported by the user, supporting fully offline operation.

Frequently Asked Questions

What makes Apache Maka "local-first" compared to cloud-based agents?

Unlike cloud-based solutions that persist data on remote servers, Apache Maka stores all code, conversation history, and operational logs in a local workspace directory on the user's machine. The SQLite-based append-only ledger in packages/storage/src/task-ledger-store.ts ensures no data leaves the local environment unless explicitly exported by the user, while the workspace source plugin resolves all dependencies locally without registry access.

How does the append-only ledger enable session recovery?

The task ledger writes every event to the workflow_task_ledger_events table without modifying historical entries, as implemented in packages/storage/src/task-ledger-store.ts lines 48-57. If the Runtime Host crashes, the system reads the ledger sequentially to reconstruct the exact file state and conversation context, allowing users to resume sessions precisely where they terminated without data loss.

Can the workspace run without internet connectivity?

Yes. The workspace source plugin in scripts/windows-package-source-closure.mjs resolves all @maka/* imports to local directories defined in the workspaces field of package.json, eliminating the need for NPM registry access during runtime. All model inference and tool execution occur within the sandboxed Runtime Host, enabling fully offline operation once the initial workspace is established.

How does Maka prevent file operations outside the designated workspace?

The Runtime Host receives the workspace directory as its cwd (current working directory) during initialization, as demonstrated in scripts/verify-windows-sandbox-e2e.mjs lines 120-130. All file-system operations are sandboxed to this directory, and the test suite explicitly verifies that no write operations escape the workspace boundaries, providing security-by-default for the local-first agent workspace.

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