# What Is Apache Maka? A Local-First, Agent-Driven Workspace Explained > Discover Apache Maka, a local-first, agent-driven workspace. Run AI-augmented tools on your machine with a unified Runtime Host coordinating UI, terminal, and bots. - Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka) - Tags: getting-started - Published: 2026-08-24 --- **Apache Maka (Incubating) is a local-first, agent-driven workspace that lets users run AI-augmented tools on their own machine through a unified Runtime Host that coordinates Desktop UI, terminal, and bot clients.** Apache Maka is an Apache Incubator project designed as a privacy-preserving platform for AI-assisted software development. Unlike cloud-dependent alternatives, Maka keeps all execution, data, and model interactions on the user's machine through a centralized **Runtime Host** architecture. This design ensures that every tool invocation, model call, and session transition operates under a single, auditable execution authority as documented in the project's [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md). ## Core Architecture of Apache Maka ### The Runtime Host and Execution Authority The **Runtime Host** serves as the central nervous system of Apache Maka. According to the source code in `packages/runtime/`, it functions as the sole execution authority that owns session identity, tool lifecycles, permissions, and event logging. All clients—including the Electron Desktop UI, terminal-based TUI/CLI, bots, and evaluation clients—must request work from this host rather than executing independently. This design prevents fragmentation of state or permission grants across different entry points. ### SessionManager and AgentRun Lifecycle Session and turn management happens through the `SessionManager` and `AgentRun` classes located in `packages/runtime/`. The `SessionManager` handles the lifecycle of a **session** (a persistent workspace), while `AgentRun` coordinates a **turn** (a single model interaction). The `AgentRun` component manages model adapters and invokes the **Tool Runtime** during execution. This separation allows precise control over admission policies, tool provisioning, and state transitions for each interaction. ### Tool Runtime and Built-in Capabilities Maka provides a built-in **Tool Runtime** with essential file system and shell operations: `Read`, `Write`, `Bash`, `Glob`, and `Grep`. These tools are available by default to agents operating within the workspace. Optional "computer-use" and catalog skills are plug-in-able but disabled by default, allowing users to strictly control the agent's capabilities. All tool executions are logged to the Runtime Event Log for auditability. ### Runtime Event Log and Recovery Durability is guaranteed by the **Runtime Event Log**, a SQLite-backed immutable record stored in `runtime.sqlite` within the Electron `userData` directory. As implemented in `packages/storage/`, this log captures every model message, tool call, tool result, and termination fact. It serves as the canonical source for crash recovery and context pruning, ensuring that interrupted sessions can resume from their exact prior state. ### Agent Graph for Multi-Agent Pipelines For complex workflows, the **Agent Graph** scheduling layer creates child sessions for dependent work. This enables multi-agent pipelines—where one agent's output becomes another's input—while maintaining the architectural invariant that all activity routes through the Runtime Host. Graph mode can be enabled via CLI flags for reproducible experiment tracking and workflow visualization. ## Repository Structure and Source Organization The Apache Maka codebase is organized as a monorepo that reflects its architectural layers: - **`apps/desktop/`** — Electron main process, preload scripts, and React-based Desktop UI - **`packages/core/`** — Pure TypeScript contracts for sessions, events, and permissions used by all other packages - **`packages/runtime/`** — Implementation of the Runtime Host, `SessionManager`, `AgentRun`, recovery logic, and tool execution - **`packages/storage/`** — SQLite stores and configuration handling, including [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) management - **`packages/eval/`** — The `@maka/eval` subsystem for benchmark experiments and result aggregation - **`packages/cli/`** — Terminal UI (TUI) implementation and non-interactive CLI commands - **`packages/ui/`** — Shared React primitives for conversation views, markdown rendering, and artifact display ## Getting Started with Apache Maka ### Setting Up the Development Environment To build and run the Desktop UI from source, clone the repository and install dependencies: ```bash git clone https://github.com/apache/maka.git cd maka npm ci npm run dev ``` For a full build before launching Electron, use `npm run dev:full` instead. ### Running Interactive and Non-Interactive Sessions Execute a single, non-interactive turn via the CLI entry point documented in `packages/cli/`: ```bash # Build the workspace first npm run build # Run a single turn npm run cli:dev -- run "Summarize this repository and identify its most important risk" ``` ### Enabling Graph Mode for Reproducible Experiments To record agent graph execution for complex, multi-step tasks: ```bash # Enable graph recording npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review" # Disable graph mode npm run cli:dev -- run /graph off ``` ## Evaluation and Testing ### The Eval Subsystem (@maka/eval) Located in `packages/eval/`, the evaluation subsystem is architecturally separate from the core runtime. It defines **experiments** composed of cells (task × repetition × subject) and owns benchmark semantics. Crucially, it delegates all execution to the Runtime Host, ensuring that evaluation runs use the same tool runtime and permissions as production sessions. ### End-to-End Testing Run the desktop UI's smoke tests using the workspace commands defined in `apps/desktop/`: ```bash npm --workspace @maka/desktop run e2e npm --workspace @maka/desktop run smoke:real-window ``` ## Storage and Configuration Apache Maka persists state through a **Storage Layer** utilizing SQLite. Key files include `runtime.sqlite` (the event log) and [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json) (configuration metadata), both stored under the Electron `userData` directory. The `packages/storage/` module abstracts all database operations, ensuring that the Runtime Host and Agent Graph layers remain agnostic to persistence details. ## Summary - Apache Maka provides a **local-first, agent-driven workspace** that keeps AI execution entirely on the user's machine - The **Runtime Host** in `packages/runtime/` serves as the sole execution authority, coordinating all Desktop, CLI, and bot clients - **SessionManager** and **AgentRun** manage the lifecycle of workspaces and individual model turns, routing all tool calls through the Runtime - The **Runtime Event Log** provides durable, SQLite-backed state in `runtime.sqlite` for crash recovery and audit trails - **Agent Graph** enables sophisticated multi-agent workflows while maintaining centralized control through the Runtime Host - The `@maka/eval` package supports reproducible benchmarking without bypassing the core runtime security model ## Frequently Asked Questions ### Is Apache Maka a cloud-based AI service? No. Apache Maka is explicitly designed as a **local-first** workspace. All model inference, tool execution, and data storage occur on the user's local machine. The **Runtime Host** architecture ensures that sensitive code and data never leave the local environment unless explicitly configured to do so. ### What programming languages and tools does Apache Maka support? The built-in **Tool Runtime** provides universal file system and shell access through `Read`, `Write`, `Bash`, `Glob`, and `Grep` tools. This allows the agent to interact with any codebase regardless of language. The Maka platform itself is implemented in TypeScript (Node.js/Electron) with SQLite for persistence, as seen in `packages/runtime/` and `packages/storage/`. ### How does Apache Maka handle session recovery after crashes? The platform uses the **Runtime Event Log**, an immutable SQLite-backed log stored in `runtime.sqlite`. According to the source documentation, this log records every model message, tool call, and termination fact, serving as the canonical source for crash recovery and context pruning. If the application terminates unexpectedly, the next session initialization reads this log to restore the exact prior state. ### Can Apache Maka run automated evaluations or benchmarks? Yes. The **`@maka/eval`** package in `packages/eval/` provides a complete experiment framework that defines tasks, repetitions, and subjects. It separates benchmark semantics from execution infrastructure, routing all evaluation work through the Runtime Host to ensure that measurements reflect real-world tool runtime performance and permissions.