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

> Discover how Apache Maka secures local-first agent workspaces. Learn about its architecture, UUID identity, and privacy controls for safe AI agent operation.

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

---

**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`](https://github.com/apache/maka/blob/main/.maka-workspace.json) Marker

Each workspace is authoritatively identified by a UUID stored in a hidden marker file named **[`.maka-workspace.json`](https://github.com/apache/maka/blob/main/.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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/workspace-root.ts).

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

```ts
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/work-board-store.ts)): Persists the UI-driven task board view.
- **Task Ledger Store** ([`packages/storage/src/task-ledger-store.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

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

```

Verify workspace identity:

```ts
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:

```ts
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:

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

```

Access the work board:

```ts
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`](https://github.com/apache/maka/blob/main/.maka-workspace.json), validated by [`packages/storage/src/workspace-identity.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/workspace-identity.ts) to prevent unauthorized access.
- **Root Resolution**: The `resolveWorkspaceRoot()` function in [`packages/storage/src/workspace-root.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/work-board-store.ts) and [`task-ledger-store.ts`](https://github.com/apache/maka/blob/main/task-ledger-store.ts)) and path validation ([`stable-storage.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/.maka-workspace.json) marker file?

The [`.maka-workspace.json`](https://github.com/apache/maka/blob/main/.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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/.maka-workspace.json) marker. However, the `resolveWorkspaceIdentity()` function in [`packages/storage/src/workspace-identity.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.