madarxOSDocs
v2.1.0 / auth + privacyshipped 2026-05-17

Your agents.
Your data.
Your machine.

madarX OS is a local-first agent operating system. SQLite-backed runtime, durable task delegation, voice main-agent, approval-gated tools. Runs on your laptop. Nothing leaves until you say so.

MIT
License
Node 22+
Runtime
SQLite
Local store
0 KB
Telemetry

Four pillars

A computer for agents,
not a wrapper around an API.

P/01

Local-first runtime.

SQLite via Node's built-in node:sqlite. An AES-256-GCM secrets vault that never lives in .env. Workspace files generated under your repo. Nothing ships to a cloud until you wire a tool that does — and then only with your key.

Data path
data/madarx.sqlite
P/02

Durable task delegation.

Cron queues, a heartbeat worker leases work and retries with backoff, stale leases recover after sleep. Tasks, runs, comments, and an append-only activity_log are first-class tables — not prompt convention.

Queue
heartbeat_tasks
P/03

Voice is the main agent.

Jarvis console mints a 60-second OpenAI Realtime session over WebRTC. The long-lived key never crosses to the browser. The voice model sees every tool the typed agent sees — same approvals, same audit, same gates.

Surface
38 tools, parity
P/04

Approval-gated by default.

Four risk tiers. An irreversible_external tier above high that always requires human approval — even in auto-trust mode. Email sends, PR merges, destructive SQL, force pushes. The model cannot ship them silently.

Gate
always-on

Per-agent engine routing

Your choice,
not ours.

Every agent picks its own engine. Default is Ollama on your machine. Swap to Claude Code, Anthropic, Codex, or Hermes per agent — without rewriting prompts.

EngineDefault modelBest forNetwork
ollamaqwen3.5:latestDefault. Local Qwen 3.5. Zero outbound calls.local
claude-codesonnetRepo-aware coding. Spawns the CC CLI under bypassPermissions.cloud
anthropicclaude-sonnet-4-6Tool-use loops, generate_ui, marketplace adapters via Messages API.cloud
codexgpt-5-codexOpenAI CLI parity. Second-opinion review and adversarial mode.cloud
hermesLong-running background jobs. Local Python sidecar.hybrid

Privacy posture

Sovereign
by construction.

The four guarantees the product makes about your data. Auditable in the source, enforced at the runtime.

01Secrets never touch .env.
API keys live in an AES-256-GCM vault inside SQLite. Decrypted in-process on use. .env.local holds non-credential config only.
02Default-deny destinations.
Write tools (email, GitHub, Supabase) require allowlist entries scoped to a domain, repo, or table. No allowlist, no call.
03Append-only audit log.
SQLite triggers raise on UPDATE and DELETE of audit_logs. The trail is tamper-evident at the database layer, not on app trust.
04No telemetry. None.
The product does not phone home. No analytics, no error reporting, no crash uploads. Egress only happens when a tool you enabled calls out.

Install · ~ 90 seconds

Four lines.

No installer, no setup wizard. Clone, install, run. Open http://127.0.0.1:8787 and create your first agent.

terminal · zsh
git clone https://github.com/kareemodev777/madarx-os.git
cd madarx-os
npm install
npm run dev
Node.js
≥ 22.5
OS
macOS · Linux
Port
8787
Disk
~500 MB

Background daemons run in-process by default — set MADARX_DISABLE_INPROC_DAEMON=1 to run them as separate processes.

Open source

MIT. Read every line.

The whole runtime — vault, audit log, approval gates, voice session minting — is auditable in the repository. Three recent entries from the changelog.

github.com/kareemodev777/madarx-os
  1. 2026-05-17228db2d

    Voice main-agent tool parity.

    The Realtime model now sees every tool the typed dashboard agent sees — 38 tools, dynamic, auto-tracks marketplace state.

  2. 2026-05-17v2.1.0

    Auth + privacy foundation.

    Pluggable auth, multi-tenant orgs, artifact ACLs, per-org HKDF-derived DEK, append-only audit log enforced by SQLite triggers.

  3. 2026-05-15ee0f1a3

    Marketplace connections layer.

    WhatsApp pairing, Hermes local-binary detection, API-key providers (Anthropic, OpenAI, Kimi) all configurable from /marketplace.