AI agents have quickly moved from tech-demo novelty to everyday workhorses. Most agent platforms, however, come with a hidden cost: your conversations, your tool logs, and often your API keys end up on someone else’s servers, routed through someone else’s gateway. Apache Maka (Incubating) takes the opposite approach. It is an open-source, local-first AI agent workspace where sessions, settings, and run records stay on your machine, and you bring the model — a cloud API, a local model, or a compatible gateway.
This guide covers what Maka actually is, why the local-first design matters, how to install it today (from source — there is no official Apache release yet), how to connect a model, and how to use it day to day.
1. What is Apache Maka?
Maka describes itself as “your work. your agent.” — a workspace where an AI agent inspects your projects, runs tools under a sandbox boundary, and writes down everything it does as recoverable execution facts. The project is incubating at the Apache Software Foundation, is written in TypeScript, and ships as three connected surfaces: a desktop app, a terminal CLI/TUI, and an evaluation harness.
Three design principles set it apart from hosted AI assistants:
- Your machine, your data. Sessions, settings, and run records stay local by default. You bring the model: a cloud API, a local model, or a compatible gateway — Maka bundles no shared model account.
- The record is kept. Every model message, tool call, tool result, permission decision, and termination event is written into an append-only execution log. The UI and the next model call are views of that record, not the only copies of it.
- Shorter context is not deleted history. Maka can omit old tool output from the next prompt without throwing away the saved evidence. Nothing needs to be destructively trimmed to save tokens.
2. Why local-first matters
The local-first architecture is not a marketing claim; it changes how the tool behaves in practice.
When the agent makes a decision, the reasoning happens against a durable event log — event-sourced, with projections for the context, the session UI, and recovery. If a run crashes or your laptop dies mid-task, the execution record survives, and Maka can resume an interrupted turn (resume is off by default and can be enabled for the desktop, the CLI /resume command, and startup auto-resume).
This also means the interface is honest about what happened: a tool timeline shows precisely which tools ran, what they returned, and how each turn ended — including failures, which are explicitly classified rather than silently swallowed.
3. The three surfaces
| Entry point | Best for | Current capability |
|---|---|---|
| Desktop | Daily interaction, file and artifact workflows, model and permission setup | Electron + React with streaming sessions, tool timelines, branching, search, and recovery |
| TUI / CLI | Working in the current project directory or running one non-interactive turn | maka, maka run; shares workspace and model connections with the desktop |
| Eval | Reproducible benchmark experiments across Maka and external subjects | maka eval run <spec> --out <directory> |
All three surfaces go through the same backend spine: Runtime Host → SessionManager → AgentRun → Model + Tool Runtime → Runtime Event Log. One place runs the agent; the desktop app, the terminal, and evaluation are just different front doors.
4. What the agent can do (and what it cannot do on its own)
Maka ships with a small, focused set of built-in tools: Read, Write, Edit, Bash, Glob, and Grep. That is deliberate — the core is lean. Computer use and catalog skills exist but are optional and off by default.
The sandbox boundary is the security backbone:
- Tools that write files or run a shell must pass the sandbox boundary first.
- Tools that would leave the sandbox must be approved — you decide.
- Runs can be aborted at any time.
- Failures are classified, so you can see why a turn ended badly.
5. Installing Maka (build from source)
Important status note: Apache Maka has not made an official Apache release yet, and everything published so far was produced before or during incubation. Until an approved source release exists, the README recommends no prebuilt download — you build and run from source. The desktop currently targets Apple Silicon Macs (arm64). Windows is an unsigned preview, and Intel Macs and Linux are not supported yet.
Requirements
| Dependency | Minimum |
|---|---|
| Node.js | 22.19 or newer (CI uses Node 24) |
| npm | 11 (the lockfile and scripts use npm) |
| Git | any recent version |
| ripgrep | required by the runtime’s Grep tool |
Build and start the desktop app
git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run devnpm run dev starts the desktop development environment with hot module replacement. To build every workspace before launching Electron, use npm run dev:full instead. If you installed dependencies with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary once first:
node node_modules/electron/install.jsFirst run: connecting a model
Maka does not bundle a shared model account, so the first launch is a two-minute setup:
- Open Settings → Models.
- Add an API, local-model, or supported account connection.
- Test it and choose your default model.
- Return to the workspace and start a task.
The app distinguishes configured, send-ready, and experimental connection states, so an account flow that is not actually wired into the runtime is not presented as a usable model.
6. Using Maka day to day
Session management (desktop)
The desktop workspace is built around sessions you can create, archive, search, rename, retry, regenerate, and branch. Branching from a turn is the standout feature: instead of replaying a whole conversation, you fork at any point and take the agent in a different direction without losing the branch you left. Artifact lists and previews, workspace instructions, model settings, and sandbox settings all live in the same workspace.
The terminal: one-off turns and graphs
After building the workspaces, the development CLI runs like this:
npm run cli:dev
npm run cli:dev -- run "Summarize this repository and identify its most important risk"
npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review the result"The interactive TUI also accepts /graph on, /graph off, and /graph <task>. Graph runs decompose a task and implement it in isolated Git worktrees, then wait for the durable graph to finish before printing the final supervisor output — so your source project must be a clean Git worktree for graph mode to work.
Evaluation: measuring agents properly
Maka’s eval surface treats benchmarks as declarative multi-arm experiments: each experiment expands into task × repetition × subject cells, each attempt is immutable, and results carry a compact kernel — score, normalized usage, attributable cost, duration, status, failure reason, and artifacts. Maka subjects execute only through Runtime Host, and external subjects plug in through generic adapters. If you are comparing models or measuring agent changes, this is the piece that keeps experiments honest and reproducible.
7. Privacy and security: where everything lives
All workspace data is stored locally under your Electron user data directory:
<userData>/workspaces/default/
runtime.sqlite # the live execution record
connection-catalog.json # your model connections
credential-vault.json # API keys (local plaintext, OS-account readable)
settings.json # workspace settings
artifacts/ # generated filesThe security model is straightforward: API keys and similar secrets live in a local plaintext file readable only by your OS account, and the renderer never sees them. Tools that write files or run a shell must pass the sandbox boundary, and anything leaving the sandbox needs your approval. Note that if you upgrade from very early builds, older JSONL transcripts are not imported, so empty threads can appear and credentials must be entered again.
8. What incubating status means for you
Incubation at the ASF does not reflect the completeness or stability of the code, but it does mean the project has not yet been fully endorsed by the ASF. For practical purposes:
- Expect change. Data formats, CLI commands, and experimental capabilities may still change between releases (the project ships in the v0.1.x range, with releases roughly monthly).
- No official download yet. Build from source, as shown above, until a source release is approved and voted on by the podling PPMC and the Incubator PMC.
- Contribute if you use it. The repository is Apache 2.0-licensed, and the project publishes architecture, security, and design docs openly on GitHub.
FAQ
See the questions above — but the short version: Maka is free and open source, keeps your data local, supports any model you can connect, and is currently macOS-Apple-Silicon-first with Windows as a preview and Linux on the way. If you value owning your agent’s history and keys, it is well worth building from source and running a few sessions — especially now, while the project is young enough that your feedback can still shape it.
Hero image: Sergei Magel/HNF, CC BY-SA 4.0, via Wikimedia Commons.
Frequently Asked Questions
Is Apache Maka free to use?
Yes. Maka is open source under the Apache License 2.0, and it is in incubation at the Apache Software Foundation. There is no bundled model account: you bring your own model connection, so the only running cost is whatever your chosen model provider charges for the tokens you use.
Do I need a cloud account to run Maka?
No. You can connect a cloud API, a fully local model, or a compatible gateway. Sessions, settings, and run records stay on your machine by default — only the prompts and tool output you send to a remote model provider ever leave it.
Is there an official Apache release of Maka yet?
Not yet. Apache Maka is incubating and has not made an Apache release, so the project recommends no prebuilt download. The supported path today is to build and run it from source, as shown in this guide.
Which platforms does Maka support?
The desktop app currently targets Apple Silicon Macs (macOS arm64). Windows exists as an unsigned preview build, and Intel Macs and Linux are not supported yet — Linux support is planned.
Where does Maka store my sessions, settings, and API keys?
In your Electron user data directory under workspaces/default: runtime.sqlite holds the live execution record, credential-vault.json holds API keys as a local plaintext file readable only by your OS account, plus connection-catalog.json, settings.json, and an artifacts folder. The renderer never sees your credentials.
Is my conversation data sent anywhere?
By default it stays local. The execution record — model messages, tool calls, tool results, and how each turn ended — is written to a local event log, and the UI is just a view of that record. Data only leaves your machine when you call a remote model or web search you have configured.
