What Is an Agent Workspace in Apache Maka?

An agent workspace in Apache Maka is a local-first, persistent directory that acts as the single source of truth for the Runtime Host, storing the append-only Runtime Event Log, SQLite state database, configuration files, and artifacts while enforcing strict sandbox boundaries.

Apache Maka defines its core abstraction as a local-first agent workspace—a dedicated on-disk container that maintains the complete operational history of the agent. According to the Apache Maka repository, this workspace ensures that all client interfaces operate on one authoritative state rather than spawning duplicate runtimes.

Core Definition and Architecture

The project describes itself in [README.md](https://github.com/apache/maka/blob/main/README.md#L24) as “a high-performance agent workspace that keeps a complete record of everything it did.” This definition captures the workspace’s fundamental role: it is not merely a cache, but the durable system of record for every action performed by the Runtime Host.

As documented in [ARCHITECTURE.md](https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L86-L94), the workspace is created automatically under the Electron userData folder. The default location resolves to …/workspaces/default/, though this path adapts to the host operating system’s conventions. Each workspace is owned by exactly one Runtime Host instance, which guarantees consistency across all connected clients.

Directory Structure and Contents

The agent workspace functions as a self-contained state container. Within the directory, you will find:

• Runtime Event Log – An append-only log that records every operation performed by the agent, enabling complete auditability and recovery.
• SQLite Database – The live state database (typically runtime.sqlite) that persists the runtime’s current memory and execution context.
• Configuration Files – Static and dynamic configuration parameters governing the agent’s behavior.
• Credential Vaults – Secure storage for authentication tokens and secrets required during sessions.
• Artifacts – Any files, build outputs, or intermediate data produced during agent execution.

Security and Isolation Model

The workspace establishes a sandbox boundary that prevents tools from escaping their designated execution environment. In [packages/storage/src/git-worktree-child-executor.ts](https://github.com/apache/maka/blob/main/packages/storage/src/git-workspace-child-executor.ts#L335), the source code enforces these boundaries, ensuring that sub-agents or invoked tools cannot write files outside the workspace directory.

Any file system operation or shell invocation must flow through the workspace’s controlled API. Attempts to traverse outside the workspace root are actively rejected, providing a security layer that isolates the host system from potentially malicious or buggy tool implementations.

Multi-Client Consistency

A significant architectural benefit of the agent workspace is its single-writer ownership model. Because one Runtime Host instance controls the workspace, all front-end clients—whether the Desktop application, TUI, CLI, automated bots, or evaluation tools—interact with the same authoritative state. This eliminates the risk of divergent runtimes or conflicting state mutations that would occur if each client maintained its own isolated runtime environment.

The [packages/cli/README.md](https://github.com/apache/maka/blob/main/packages/cli/README.md#L24) notes that the maka-agent npm package installs the interactive agent workspace, confirming that even programmatic consumers rely on this centralized persistence layer.

Working with the Agent Workspace

Locating the Workspace Programmatically

You can resolve the active workspace path at runtime using Electron’s API. The following TypeScript example demonstrates how to locate the default workspace and verify the existence of the runtime database:

import { app } from 'electron';
import { join } from 'path';
import { existsSync } from 'fs';
import { Database } from 'sqlite3';

// Resolve the workspace root under Electron userData
const userData = app.getPath('userData');
const workspaceRoot = join(userData, 'workspaces', 'default');

if (!existsSync(workspaceRoot)) {
  throw new Error(`Maka workspace not found at ${workspaceRoot}`);
}

// Open the runtime SQLite database (read-only example)
const dbPath = join(workspaceRoot, 'runtime.sqlite');
const db = new Database(dbPath, (err) => {
  if (err) console.error('Failed to open runtime DB:', err);
});

CLI Management

The command-line interface provides direct interaction with the workspace location and lifecycle:

# Display the absolute path of the active workspace

$ maka workspace path

# → /Users/you/Library/Application Support/Maka/workspaces/default

To reset the workspace and destroy all persisted history—including the event log, database, and artifacts—remove the directory and allow Maka to re-initialize on the next run:

# Reset workspace (destructive operation)

$ rm -rf "$(maka workspace path)"

# Re-initialize automatically on next execution

$ maka run "Hello world"

The scripts/verify-macos-arm64-cli.mjs script includes automated tests that verify the packaged CLI contains the expected workspace structure, ensuring distribution integrity across platforms.

Summary

• An agent workspace is the persistent, local-first directory that stores Apache Maka’s complete operational state.
• It resides under Electron’s userData folder by default and contains the append-only event log, SQLite database, credentials, and artifacts.
• A single Runtime Host owns each workspace, ensuring consistent state across Desktop, CLI, TUI, and bot clients.
• The workspace enforces sandbox boundaries through controlled APIs that prevent tool executions from escaping the directory.
• You can interact with the workspace programmatically via Electron APIs or through the maka workspace CLI commands.

Frequently Asked Questions

Where is the Apache Maka agent workspace stored on disk?

By default, the agent workspace is located within the Electron userData directory at …/workspaces/default/. The exact absolute path varies by operating system—on macOS this typically resolves to ~/Library/Application Support/Maka/workspaces/default/, while Linux and Windows follow their respective user data conventions.

What files are contained in an Apache Maka agent workspace?

The workspace contains the append-only Runtime Event Log, a SQLite database named runtime.sqlite that stores live execution state, configuration files, credential vaults for authentication secrets, and any artifacts generated during agent sessions. This collection represents the complete durable state of the Runtime Host.

How does the agent workspace prevent sandbox escapes?

The workspace implements a strict boundary enforced in the storage layer—specifically in [packages/storage/src/git-workspace-child-executor.ts](https://github.com/apache/maka/blob/main/packages/storage/src/git-workspace-child-executor.ts#L335)—which requires all file system operations and shell invocations to route through controlled APIs. Any attempt to write or read outside the workspace directory is rejected, isolating the host system from potentially unsafe tool behavior.

Can multiple Runtime Host instances share the same agent workspace?

No. The architecture enforces single-instance ownership where exactly one Runtime Host controls a given workspace. This design prevents conflicting state mutations and ensures that all connected clients—whether CLI, Desktop, or TUI—observe a consistent, authoritative view of the agent’s history and current state.

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