How the Maka Agent Workspace Architecture Works: Single-Authority Execution and Isolation

Maka's agent workspace architecture uses a single Runtime Host to own session state and provide a workspace-bound execution environment, where all agents route tool calls through one authority that enforces path containment, write locks, and deterministic event logging.

The Maka agent workspace architecture ensures secure, isolated, and reproducible operations across Desktop, TUI, CLI, and bot interfaces. According to the Apache Maka source code in ARCHITECTURE.md and packages/runtime/src/workspace-executor.ts, every agent sends work to a central Runtime Host rather than spawning separate runtimes. This design guarantees consistent permission checks and provenance tracking for all file system and tool interactions within a session.

Core Components of the Agent Workspace

The Runtime Host: Central Session Authority

The Runtime Host owns the session identity, agent lifecycle, continuation logic, tool registry, permission policy, and event logging. As defined in ARCHITECTURE.md (lines 24-31), it serves as the single point of authority for a given State Root, ensuring that all agents—whether interactive or automated—operate under unified governance. The host kernel implementation in packages/runtime-host/src/server/host-kernel.ts wires this authority to the public client protocol boundary.

Workspace Executor and Path Containment

The Workspace Executor provides the concrete implementation for running commands, reading and writing files, and applying patches within the workspace. The default implementation, LocalWorkspaceExecutor in packages/runtime/src/workspace-executor.ts (lines 96-115), uses Execution Boundaries to determine path resolution scope. The executor supports two scopes:

• workspace: Forces all paths to resolve inside the session's current working directory
• host: Permits access to absolute paths anywhere on the host machine

Path containment validation relies on helper functions in packages/runtime/src/path-containment.js, including isPathInside and realpathAllowMissing, to enforce these boundaries.

Write Locking and Concurrent Access

For write operations, the executor derives a write-lock key from the canonical path to ensure that different spellings of the same file map to identical locks. This mechanism, implemented in workspace-executor.ts (lines 22-33), prevents race conditions during concurrent file modifications.

How Commands Execute in the Workspace

When an agent triggers a tool call, the Runtime Host processes it through four deterministic stages:

1. Path Resolution and Validation – The executor canonicalizes the target path using canonicalPathInScope. If the caller specifies workspace scope and the resolved path escapes the session cwd, the resolver throws an error (see workspace-executor.ts, lines 96-105).

2. Write Lock Acquisition – For mutating operations, the system acquires a lock based on the canonical path to serialize access.

3. Process Execution with Bounds – Commands run via exec or execFile, wrapped by runProcessWithBoundedTail or runShellWithBoundedTail. These wrappers enforce timeouts, capture stdout/stderr, and optionally stream output back to the caller (workspace-executor.ts, lines 99-112).

4. Event Logging – The resulting WorkspaceExecResult—containing stdout, stderr, exit code, and timeout flags—is appended to the Runtime Event Log. This log serves as the single source of truth for replay, compaction, and crash recovery (ARCHITECTURE.md, lines 45-46).

The Runtime Event Log and Deterministic Recovery

All model messages, tool calls, tool results, and termination facts are appended to the canonical Runtime Event Log. This design enables deterministic replay of sessions and supports recovery mechanisms after host failures. The log's immutability guarantees provenance for every action taken within the workspace, allowing the system to resume from exact failure points without state corruption.

Scaling Work with the Agent Graph

Maka scales complex workloads through the Agent Graph, which schedules dependent work using child sessions. Each child session receives its own isolated workspace and tool set while routing every activation back through the same Runtime Host (ARCHITECTURE.md, lines 33-34). This architecture maintains the single-authority guarantee while allowing parallel, isolated execution contexts. Detailed design patterns are documented in docs/architecture/runtime-host-architecture.md.

Workspace-Aware System Prompts

Maka injects read-only workspace instructions into the system prompt via packages/runtime/src/system-prompt/workspace-instructions.ts. This module scans the user's global ~/.maka directory and the project cwd for files like AGENTS.md, CLAUDE.md, and GEMINI.md, building a context fragment with strict size caps (lines 59-96). These instructions provide the model with project-specific context without exposing mutable state.

Practical Implementation Examples

The following examples demonstrate how to interact with the workspace executor API:

// Create a local workspace executor (used by the desktop and CLI)
import { createLocalWorkspaceExecutor } from '@maka/runtime';

const executor = createLocalWorkspaceExecutor();

// Execute a command inside the current session workspace
await executor.exec({
  cwd: process.cwd(),
  command: 'git status',
  timeoutMs: 5000,
});

// Read a text file from the workspace
const file = await executor.readFile({
  cwd: process.cwd(),
  path: 'README.md',
});

// Write a file (writes are confined to the workspace)
await executor.writeFile({
  cwd: process.cwd(),
  path: 'notes.txt',
  content: 'Important observations',
});

To resolve paths with explicit workspace scope enforcement:

// Resolve a path with explicit workspace scope
const { path } = await executor.resolveWritablePath({
  cwd: process.cwd(),
  path: '../outside.txt',   // ❌ will throw because it escapes the cwd
  label: 'user file',
  scope: 'workspace',
});

For building system prompt fragments:

// Build the workspace-instruction prompt fragment for the current session
import { buildWorkspaceInstructionsPromptFragment } from '@maka/runtime';

const promptFragment = await buildWorkspaceInstructionsPromptFragment(process.cwd());
// `promptFragment` can be concatenated to the system prompt before sending to the model.

Summary

• Single authority: One Runtime Host per State Root guarantees consistent permission checks and provenance tracking across all agent types.
• Containment enforcement: The workspace executor's scope logic (workspace vs host) prevents accidental or malicious writes outside the session cwd.
• Deterministic replay: All actions are logged in the immutable Runtime Event Log, enabling safe resumption and crash recovery.
• Concurrent safety: Write-lock keys derived from canonical paths prevent race conditions during parallel file operations.
• Extensible tooling: Child sessions via the Agent Graph can be given distinct tool sets and workspaces while still routing through the same host authority.

Frequently Asked Questions

How does Maka prevent agents from accessing files outside the workspace?

The Workspace Executor validates all paths using canonicalPathInScope in packages/runtime/src/workspace-executor.ts. When the execution scope is set to workspace, the system throws an error if the resolved path lies outside the session's current working directory. Helper functions in packages/runtime/src/path-containment.js perform the actual containment checks using isPathInside and realpathAllowMissing.

What happens if a command times out or crashes during execution?

The executor wraps all process calls with runProcessWithBoundedTail or runShellWithBoundedTail, which enforce configurable timeouts. If a timeout occurs or the process crashes, the Runtime Event Log still records the WorkspaceExecResult including exit codes and error states. Because the log serves as the single source of truth, sessions can be replayed or resumed from the exact point of failure without data loss.

Can multiple agents work on the same workspace simultaneously?

Yes, through the Agent Graph architecture. The Runtime Host can spawn child sessions, each with isolated workspaces and tool sets, while routing all activations back through the same host authority. This allows parallel, dependent work while maintaining strict isolation between concurrent operations through the write-lock mechanism that serializes access to specific files.

How does Maka provide project context to the AI model without exposing the file system?

Maka uses the buildWorkspaceInstructionsPromptFragment function in packages/runtime/src/system-prompt/workspace-instructions.ts to scan for local instruction files (e.g., AGENTS.md, CLAUDE.md). It builds a read-only prompt fragment with strict size limits and injects it into the system prompt. This gives the model contextual awareness of the project without granting it direct file system access beyond the workspace scope.

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