fix(runtime-host): harden managed service lifecycle Serialize managed configuration and catalog mutations across processes, and bind detached startups to expiring revision-pinned attempts. This keeps Stop, Restart, edits, and crash recovery linearizable without treating stale registrations or process IDs as ownership authority. Release the configuration transaction only after the Host has published its recovering registration, while preserving bootstrap Stop and shutdown cleanup during asynchronous startup commit. Centralize the manager permission packs so issued credentials remain aligned with the CLI presets.
A local-first Agent workspace built for real work.
Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages and tool calls as recoverable execution facts. Desktop, the terminal TUI, the non-interactive CLI, and Maka evaluation subjects all execute through Runtime Host.
[!IMPORTANT] Maka is under active development. The macOS Apple Silicon desktop build is an early public release; data formats, CLI commands, and experimental capabilities may still change.
Read Maka Backend Architecture for the complete design.
| 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 | Using Maka in the current project directory or running one non-interactive Turn | maka, maka run; shares workspace and model connections with Desktop |
| Eval | Reproducible benchmark experiments across Maka and external subjects | maka eval run <spec> --out <directory> |
Read, Write, Edit, Bash, Glob, and Grep;The signed and notarized Desktop app is available from GitHub Releases for Apple Silicon Macs only (arm64).
Maka-<version>-mac-arm64.dmg;ripgrep with brew install ripgrep to enable Runtime's Grep tool;Settings → Models.Computer Use is not included in this first public build. Intel Macs, Windows, and Linux packages are not supported yet.
Windows is still an unsigned preview, not a supported release tier. When a release includes Windows assets, follow the Windows preview installation and verification guide before running Maka-<version>-win-x64.exe. SmartScreen will identify the installer as coming from an unknown publisher; do not bypass that warning unless the downloaded SHA-256 matches the checksum published with the same release.
packageManager is npm 11);ripgrep, used by Runtime's Grep tool.git clone https://github.com/Maka-Agent/maka-agent.git cd maka-agent npm ci npm run dev
npm run dev starts the Desktop development environment with HMR. To build every workspace before starting Electron, use:
npm run dev:full
If dependencies were installed with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary before starting:
node node_modules/electron/install.js
Maka does not bundle a shared model account. On first launch:
Settings → Models;The app distinguishes configured, send-ready, and experimental connection states. An account flow that is not wired into Runtime is not presented as a usable model.
Build the workspaces first:
npm run build
Then start the TUI or run one Turn:
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" npm run cli:dev -- --help
The TUI also accepts /graph on, /graph off, and /graph <task>. Non-interactive --graph runs wait for the durable Graph to finish before printing the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.
The repository CLI uses the same Maka Dev profile as a development Desktop build. The released maka binary continues to use the Maka profile; the two profiles are not copied or synchronized automatically. Evaluation specs and adapters live in packages/eval.
The backend spine is:
Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun ↓ Model + Tool Runtime → Runtime Event Log ↓ Context / Session / UI projections Experiment → Cells → Attempts → Results ↓ Runtime Host executes Maka subjects
Start with ARCHITECTURE.md. It provides the system map, code boundaries, problem-oriented reading paths, and six bilingual deep dives.
apps/desktop/ Electron main / preload / React renderer packages/core/ Pure contracts for Sessions, Events, Permissions, and Connections packages/storage/ SQLite operational state, configuration, and payload stores packages/runtime/ AgentRun, model adapters, tools, context, and recovery packages/eval/ Experiment cells, attempts, results, and executor/subject adapters packages/cli/ TUI and non-interactive CLI packages/ui/ Shared conversation, Markdown, Artifact, and UI primitives docs/ Architecture, product, security, privacy, and test contracts scripts/ Build hygiene, visual checks, smoke tests, and release helpers
Maka stores workspace data under Electron userData by default:
<Electron userData>/workspaces/default/ runtime.sqlite llm-connections.json credentials.json settings.json artifacts/
Current boundaries that matter:
runtime.sqlite;credentials.json, behind the OS account boundary, with POSIX directory mode 0700 and file mode 0600 enforced;credentials.json — the single authority for Runtime Host clients. Pre-existing Electron safeStorage credential/token files are not imported; affected users must re-authenticate;Read SECURITY.md for security reporting and policy, and docs/README.md for current privacy and sandbox contracts.
runtime.sqlite is the sole operational authority. It owns RuntimeEvents, session metadata and message history, Agent Graph control, core execution state, workflow state, usage and pricing, Artifact metadata, Automations, Daily Review, and Runtime continuation records. Artifact payload bytes remain regular files under artifacts/; connections, credentials, settings, MCP configuration, skills, and device identity remain configuration files.
This storage generation does not import earlier File/JSONL authorities. On upgrade, legacy session titles may still be discoverable through current metadata, but conversation history that exists only in legacy transcript files is not copied into session_messages and opens as an empty thread. Likewise, pre-version or safeStorage-encrypted credential/token files are not migrated; users with only those copies must re-authenticate. This data-loss boundary is intentional for this release and must be considered before upgrading an existing workspace.
Full operational backup uses the database owner‘s online SQLite backup API and copies canonical Artifact payloads under the Artifact writer lock. Its manifest binds every file by size and SHA-256. Validation checks the standalone SQLite snapshot’s integrity, foreign keys, schema registry and required tables, decodes canonical session-message and Artifact records, and verifies Artifact payload sizes against SQLite metadata before restore. Backup and restore use owner-only file modes, file and directory synchronization, staging, and atomic publication.
Runtime continuation remains opt-in:
MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 enables the Desktop interrupted-turn Safe resume action, CLI/TUI /resume, and Desktop startup auto-resume. These paths may call the configured model provider and consume tokens. Enable the flag only when that behavior is explicitly desired.Phase 2 provides the durable write-side boundary and fail-closed safe-boundary continuation. Phase 3 reconciliation for indeterminate tool side effects is not implemented yet; ambiguous tool outcomes remain parked rather than retried.
Before sending a change, read CONTRIBUTING.md.
Common repository-level commands:
npm run build npm run typecheck npm test npm run check:release
Run one workspace in isolation:
npm --workspace @maka/runtime test npm --workspace @maka/eval test npm --workspace @maka/desktop test
Use the following commands to update packages/core/src/model-metadata.generated.ts from models.dev and run the focused tests. Keep access-path-specific overrides in model-metadata.ts; do not edit the generated file by hand.
npm run sync:model-metadata npm --workspace @maka/core test
Desktop real-window and visual verification:
npm --workspace @maka/desktop run e2e npm --workspace @maka/desktop run smoke:real-window
Before submitting code, run typecheck, build, and focused tests proportionate to the change, followed by git diff --check.
Maka is licensed under the Apache License 2.0. See NOTICE for attribution information. Third-party components remain subject to their respective licenses and notices.