Maka is a local-first agent workspace. The maka-agent npm package installs the interactive terminal UI, the non-interactive CLI, Runtime Host tooling, and the Eval command. That package is published under the nightly dist-tag; latest holds an early alpha stub (see Install).
Apache Maka is undergoing incubation at The Apache Software Foundation. The published npm README includes the canonical work-in-progress disclaimer below directly from the release commit's DISCLAIMER-WIP; the Maka podling status page records current status.
Beta: The CLI is under active development. Commands and local data formats may change before the stable release.
The release gate validates the following installed-package matrix:
| Platform | Architecture | Node.js | TUI, CLI, Runtime Host | Real Harbor/Pier Eval |
|---|---|---|---|---|
| Linux | x64 | 22.19 | Validated | Preflight only |
| Linux | x64 | 24 | Validated | Validated |
| Linux | arm64 | 24 | Validated | Preflight only |
| macOS | arm64 | 24 | Validated | Preflight only |
| Windows | x64 | 24 | Validated | Preflight only |
Other combinations that satisfy the Node.js minimum may work, but are not part of the current release gate. Real Eval executor validation currently runs on Linux x64 with Node.js 24.
Two dist-tags are live on npm, and they are not interchangeable:
nightly carries the complete CLI. The line moves daily — resolve the tag (or query its current version) instead of copying a version number from any document:
npm install --global maka-agent@nightly maka --version maka --help
latest points at an early alpha (0.0.0-alpha.0) whose command surface is limited to doctor, help, and version. Because of that split, do not use a bare npm update --global maka-agent: it follows latest and may switch the installation to the other release line.
The public command is maka. For a one-off invocation, use npx --yes --package maka-agent@nightly maka; the unrelated maka package on npm is not this project. runtime-host service install uses the persistent global installation above; runtime-host setup creates its own managed copy from the exact package invoked by npx.
Start Maka from the project directory the agent should work in:
cd path/to/project maka
If no model connection exists, Maka opens the provider setup flow. Select a provider, enter its API key, choose the enabled models, and save. Run /setup later to add or update a provider and /model to switch models.
API keys and workspace state stay in the local Maka profile. The current credential vault is a local plaintext file protected by the operating-system account boundary; on POSIX systems Maka enforces owner-only directory and file modes. It is not an OS keychain. See the repository security policy for the current boundary.
Run one non-interactive turn with:
maka run "Summarize this project and identify its highest-risk area" maka run --help
Maka asks before privileged tool operations by default. maka run --yolo grants the task full file and network access and should only be used in an environment you are prepared to let the task modify.
Update within the nightly line by pinning the exact release (--target accepts latest, next, or an exact Maka version — there is no nightly channel name). Resolve the current nightly version first and pass that exact value: the updater refuses downgrades, so a copied version number goes stale as soon as the nightly line moves on.
version="$(npm view maka-agent@nightly version --registry=https://registry.npmjs.org)" maka update --target "$version" maka --version
Do not use a bare npm update --global maka-agent to upgrade: it follows latest, which holds the early alpha stub, and may switch the installation to the other release line.
The update stages and verifies the exact release before replacing the local Runtime Host or the npm-global package. It refuses to interrupt active or durable work by default. Use --allow-interrupt-active-tasks only after deciding that interruption is safe. A direct npm install --global maka-agent@nightly remains available for installation repair.
To set up a persistent remote Runtime Host from an exact released package on Linux or macOS:
npx --yes --package maka-agent@nightly maka runtime-host setup \ --principal my-client \ --preset terminal-client
Rerunning setup replaces that Client credential. The service no longer depends on the temporary npx cache after setup succeeds.
Check a managed service against the nightly release it should track, without changing the running Host — pass the exact version resolved above rather than latest, which holds the early alpha:
maka runtime-host service check-update --target "$version" --json
The result pins the selected channel to an exact version and package integrity. It also reports whether the package carries enough compatibility evidence for unattended use; this command never installs or switches a package. Installation-management callers can pass the same selector to service update --target. That path verifies the archive and extracted manifest before delegating to the existing exact-package update transaction, and does not mutate a candidate that requires manual review.
The installation owner can persist one update target and reconcile it with the same verified transaction. Pin the exact nightly version resolved above: there is no nightly target name, and latest holds the early alpha, which the reconciliation assesses as a downgrade for a nightly installation. Following successive nightlies therefore means resolving the current version again and re-running update-policy with the fresh value:
maka runtime-host service update-policy --target "$version" \ --expected-service-id <service-id> \ --expected-root-path <state-root> \ --expected-root-id <root-id> maka runtime-host service reconcile-update --json
Use update-policy --target manual to disable automatic reconciliation. Reconciliation is a bounded one-shot command: it never interrupts active work and does not install a scheduler.
# When a managed Runtime Host service was installed on Linux or macOS npx --yes --package maka-agent@nightly maka runtime-host service uninstall # If Maka was installed globally npm uninstall --global maka-agent
Remove the managed service before removing a global package so the OS service manager does not retain a service pointing to the deleted CLI. Neither command deletes model connections, credentials, sessions, or artifacts. Those remain in the profile shared by the released CLI and Desktop app:
| Platform | Profile directory |
|---|---|
| macOS | ~/Library/Application Support/Maka |
| Linux | $XDG_CONFIG_HOME/Maka, or ~/.config/Maka when unset |
| Windows | %APPDATA%\Maka |
Back up and remove that directory separately only when you intend to delete all local Maka data. Close the CLI and Desktop app first.
Run a declarative experiment with:
maka eval run experiment.json --out .maka-eval/run-001
The npm package includes Maka‘s Eval runtime, relay, wrapper, and container policy assets. It does not install the executor’s external software or machine-local benchmark data. Before starting any trial, Eval checks the exact prerequisites declared by the spec and fails without running a cell if one is missing.
For Docker-based Harbor or Pier specs, provide:
executor.config.frameworkVersion;pythonPathEnv;trialsRootEnv;tasksRootEnv;Harbor and Pier must use separate Python environments. The currently validated versions are:
python3.12 -m venv ~/.venvs/maka-harbor-0.20.0 ~/.venvs/maka-harbor-0.20.0/bin/python -m pip install 'harbor==0.20.0' python3.12 -m venv ~/.venvs/maka-pier-0.3.0 ~/.venvs/maka-pier-0.3.0/bin/python -m pip install 'datacurve-pier==0.3.0'
Set the spec's pythonPathEnv to the corresponding bin/python path. Do not reuse one environment for both frameworks: their dependency and trial contracts differ. Advanced experiment and toolchain details live in the Eval documentation.
Start by recording the installed versions:
node --version npm --version maka --version
maka is not found after a global install, ensure npm's global executable directory is on PATH./setup.Report issues at https://github.com/apache/maka/issues.