Apache Maka FAQ

Apache Maka is a local-first AI agent workspace designed for real work. It inspects projects, runs tools under a sandbox boundary, and records model messages and tool calls as recoverable execution facts on your machine through one Runtime Host.

Key features include:

• Local-first approach - your data stays on your machine
• Durable execution records with crash recovery
• Multiple model connections and built-in tools
• Desktop, CLI, and evaluation surfaces

To run Apache Maka, you'll need:

• Node.js 22.19 or newer (CI uses Node.js 24)
• npm (the lockfile and scripts use npm; current packageManager is npm 11)
• Git
• ripgrep, used by Runtime's Grep tool
• macOS Apple Silicon (arm64) for the Desktop app

Intel Macs and Linux are not yet supported. Windows is an unsigned preview.

Apache Maka is currently in incubation and hasn't made an official Apache release yet. You can build and run from source:

For Terminal entry points:

Apache Maka supports multiple model connections including:

• Cloud APIs (OpenAI, Anthropic, etc.)
• Local models (compatible with standard APIs)
• Compatible gateways and proxy services

You can configure models in the Settings → Models section. The app distinguishes between configured, send-ready, and experimental connection states.

Apache Maka includes several built-in tools:

• Read - Read files from the workspace
• Write - Create or update files
• Edit - Modify files with targeted changes
• Bash - Execute shell commands in a sandbox
• Glob - Find files matching patterns
• Grep - Search file contents

Computer Use and catalog skills are optional and not enabled by default.

Apache Maka maintains a durable execution record that includes:

• Model messages and responses
• Tool calls and their results
• Permission decisions
• Termination events
• How each turn ended

This record is stored locally and used for recovery, search, and UI representation. The UI and next model call are views of this record, not the only copy.

Workspace data is stored under Electron `userData` by default:

• <Electron userData>/workspaces/default/
• runtime.sqlite - The live execution record
• connection-catalog.json - Model connection configurations
• credential-vault.json - API keys and secrets (encrypted)
• settings.json - Application settings
• artifacts/ - Generated artifacts and outputs

API keys are stored in a local plaintext file readable only by your OS account. The renderer never sees these credentials.

Apache Maka implements several security measures:

• Tools that write files or run shell commands must pass a sandbox boundary
• API keys are stored in a local vault readable only by your OS account
• Tools that leave the sandbox require explicit approval
• Runs can be aborted at any time
• Failures are classified and logged

See our Security Policy for detailed information.

Resume functionality is optional and off by default. To enable it:

• Set MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 environment variable
• Use Desktop Safe resume feature
• Use CLI /resume command
• Enable startup auto-resume

Note: Resume features hit the model API and consume tokens. The workspace must be in a clean state before resuming.

We welcome contributions! Here's how you can help:

• Read the Contributing Guide
• Report bugs or request features via GitHub Issues
• Submit pull requests with improvements
• Join our community discussions
• Help with documentation and testing

Before submitting code, run typecheck, build, and focused tests proportional to your changes.

The backend architecture consists of:

• Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
• Model + Tool Runtime → Runtime Event Log
• Context / Session / UI projections
• Experiment → Cells → Attempts → Results

The system is organized into packages: core, storage, runtime, eval, cli, ui, and desktop. See the Architecture Documentation for details.

For support, consider these resources:

• GitHub Issues for bug reports and feature requests
• Apache Incubator Mailing List for development discussions
• Documentation for technical guides
• Community channels in our GitHub repository

Please check existing issues before creating new ones.

Apache Maka is licensed under the Apache License 2.0. This is a permissive open-source license that allows you to use, modify, and distribute the software freely.

See the NOTICE file for attribution information. Third-party components remain subject to their respective licenses.

Apache Maka is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision-making process have stabilized.

While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. See our DISCLAIMER-WIP for current known issues.

Yes, Apache Maka, Maka, Apache, the Apache feather, and the Apache Maka project logo are either registered trademarks or trademarks of The Apache Software Foundation. Please follow the Apache Trademark Policy when using these marks.