How Apache Maka Implements Local-First Agent Workspaces: Architecture, Identity, and Privacy Controls

Apache Maka implements local-first agent workspaces by binding every AI agent to a self-contained, UUID-identified directory on the user’s machine, enforced by the main process through a minimal privacy contract and SQLite-backed stores that never transmit data without explicit consent.

Apache Maka is an open-source framework for running AI agents with a privacy-by-default philosophy. At the core of its architecture are local-first agent workspaces—self-contained directories that serve as the atomic units of state, privacy, and persistence. Every task, credential, and skill instruction remains inside the user’s workspace unless explicitly configured otherwise.

Workspace Identity and the .maka-workspace.json Marker

Each workspace is authoritatively identified by a UUID stored in a hidden marker file named .maka-workspace.json. This file is created the first time a folder is initialized as a workspace and is never regenerated, ensuring stable identity even if the directory is moved or renamed.

The validation logic resides in packages/storage/src/workspace-identity.ts. The resolveWorkspaceIdentity() function reads this marker and detects tampering or relocation (such as inode changes). If validation fails, the function throws a WorkspaceIdentityError, preventing the agent from operating in an untrusted context.

Resolving Workspace Roots with resolveWorkspaceRoot()

Logical workspace names map to concrete filesystem locations through the resolveWorkspaceRoot() API, implemented in packages/storage/src/workspace-root.ts.

The function constructs the path by joining the client data root with the workspace name:

const workspaceRoot = pathApi.join(clientDataRoot, 'workspaces', workspaceName);

This ensures all workspaces live under a predictable, sandbox-friendly location—typically ~/.maka/data/workspaces/<name>—keeping agent data organized and isolated from system directories.

Privacy-First Architecture: The WorkspacePrivacyContext Contract

Privacy controls in Apache Maka follow a strict authority model defined in docs/workspace-privacy-context.md. The contract centers on a single boolean flag: incognitoActive.

The main process owns the definitive truth of this value; renderer processes may request changes but cannot assert the effective state. When incognitoActive evaluates to true, all privacy-sensitive consumers must fail-closed, aborting any external network requests or telemetry transmission.

This design guarantees that local-first agent workspaces remain truly local unless the user explicitly disables incognito mode.

Persistent Storage: SQLite Stores Bound to Workspace Roots

All persistent state lives inside the workspace directory via workspace-scoped SQLite databases. Two primary stores manage agent activity:

• WorkBoard Store (packages/storage/src/work-board-store.ts): Persists the UI-driven task board view.
• Task Ledger Store (packages/storage/src/task-ledger-store.ts): Records task history, scheduling, and execution metadata.

Both stores receive the resolved workspaceRoot and open their databases within that directory. This binding ensures that copying or archiving the workspace folder captures complete agent state, including full history and configuration.

Security Boundaries and Path Validation

To enforce containment, Apache Maka validates all durable storage paths against the workspace root in packages/storage/src/stable-storage.ts. Any attempt to write outside the resolved workspace directory raises an error, preventing data leakage or sandbox escapes.

Additionally, the desktop application communicates local-first guarantees to users through copy defined in apps/desktop/src/renderer/locales/settings-preferences-copy.ts. This messaging emphasizes that model keys, credentials, and skill instructions remain in local files, with no telemetry sent unless explicitly enabled.

Working with Local-First Agent Workspaces (Code Examples)

The following snippets demonstrate the typical workflow for interacting with an agent workspace.

Resolve the workspace root:

import { resolveWorkspaceRoot } from '@maka/storage';
const wsRoot = resolveWorkspaceRoot({ workspaceName: 'default' });
console.log('Workspace root:', wsRoot);
// → /Users/alice/.maka/data/workspaces/default

Verify workspace identity:

import { resolveWorkspaceIdentity } from '@maka/storage';
async function assertWorkspace() {
  const { workspaceId, workspaceIdentity } = await resolveWorkspaceIdentity(wsRoot);
  console.log('Workspace ID:', workspaceId);
}
assertWorkspace();

Check privacy context before external calls:

import { getWorkspacePrivacyContext } from '@maka/core';
async function isIncognito() {
  const ctx = await getWorkspacePrivacyContext();
  return ctx.incognitoActive;
}
if (await isIncognito()) {
  console.warn('Incognito mode – aborting external requests');
}

Store tasks locally:

import { createSqliteTaskLedgerStore } from '@maka/storage';
const taskStore = createSqliteTaskLedgerStore(wsRoot);
await taskStore.addTask({ id: 't1', description: 'Summarize notes', status: 'pending' });

Access the work board:

import { createWorkBoardStore } from '@maka/storage';
const board = createWorkBoardStore(wsRoot);
const tasks = await board.listTasks();
console.table(tasks);

Summary

• Atomic Identity: Each workspace is uniquely identified by a UUID in .maka-workspace.json, validated by packages/storage/src/workspace-identity.ts to prevent unauthorized access.
• Root Resolution: The resolveWorkspaceRoot() function in packages/storage/src/workspace-root.ts maps logical names to isolated directories under the user’s data root.
• Privacy Enforcement: The WorkspacePrivacyContext contract in docs/workspace-privacy-context.md ensures fail-closed behavior when incognitoActive is true, with the main process holding sole authority.
• Contained Storage: SQLite stores (work-board-store.ts and task-ledger-store.ts) and path validation (stable-storage.ts) guarantee that all data remains within the workspace boundary.
• User Transparency: UI copy in apps/desktop/src/renderer/locales/settings-preferences-copy.ts clearly communicates local-first guarantees to end users.

Frequently Asked Questions

What is the purpose of the .maka-workspace.json marker file?

The .maka-workspace.json file stores the workspace’s immutable UUID and serves as the authoritative identity marker. Created once during initialization, it allows Apache Maka to detect if the workspace directory has been moved, copied, or tampered with by validating the stored metadata against current filesystem properties.

How does Apache Maka ensure data remains local in agent workspaces?

Apache Maka enforces locality through multiple mechanisms: the WorkspacePrivacyContext contract requires components to fail-closed when incognito mode is active; the stable-storage.ts module validates that all write operations occur within the workspace root; and SQLite stores explicitly open database connections inside the workspace directory, ensuring no data persists to external locations without user consent.

Can I move an Apache Maka workspace to a different machine?

Yes, because workspaces are self-contained directories with all state stored locally in SQLite files and the .maka-workspace.json marker. However, the resolveWorkspaceIdentity() function in packages/storage/src/workspace-identity.ts will detect if the marker is missing or corrupted during the move, throwing WorkspaceIdentityError until the workspace is properly re-initialized or the marker is preserved intact during transfer.

What happens if code attempts to write outside the workspace directory?

The durable storage layer in packages/storage/src/stable-storage.ts validates every path against the resolved workspace root. Any attempt to escape the sandbox raises a runtime error, preventing accidental or malicious data leakage from the local-first agent workspace to other parts of the filesystem.

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