An orchestrator for agents, not another chatbot.

The current generation of AI products optimizes for single-turn assistance: a user issues a prompt, receives an answer, then manually integrates the output into a downstream workflow. Enterprise and regulated use cases need three properties that chat does not provide — persistent agents that execute recurring work, human approval at every external boundary, and a verifiable record of intent, action, and outcome. madarX OS delivers all three on infrastructure the operator controls, with no data leaving the perimeter unless explicitly authorized.

Architecturally the product sits between the foundation-model layer (Anthropic, OpenAI, Ollama, Hermes, Claude Code CLI) and the end-user surfaces (chat, voice via OpenAI Realtime WebRTC, scheduled runs, WhatsApp via Baileys). The differentiation is not the LLM — it is the Agent-Computer Interface (ACI) and the policy plane wrapping it. Four primitives are shipped and load-bearing: (1) a four-tier risk taxonomy (low → medium → high → irreversible_external) where the top tier is never auto-approved — trust-mode auto bypasses high and below but the irreversible_external gate stands, so no LLM can authorize money, code merges, deploys, deletes, or external sends without human-in-the-loop. This is the load-bearing safety claim. (2) Append-only compliance audit chain enforced at the SQLite trigger layer (BEFORE UPDATE / BEFORE DELETE raise) — WORM-style integrity at the storage primitive, not the application layer. (3) Per-tool destination allowlists keyed by scope (recipient_domain, repo_full_name, table) — capability-token shape — composed with sliding-window rate limits where main-agent and per-agent counters are independent. (4) AES-256-GCM secrets vault with KMS-replaceable master-key derivation and a wrapFetch egress recorder logging host / method / status / bytes / duration per outbound call (no payloads — data minimization by construction). Remaining work is productization: artifact taxonomy with hybrid retrieval, multi-tenant teams, A2A federation, and the hosting matrix.

Every artifact produced by an agent — a report, a brief, a draft message, a generated UI — moves through a three-stage lifecycle. Dashboard is the operator's working surface: recent runs, pinned items, the live control view. Library is the searchable corpus, navigable by project, space, author, and tag. Archive is retention storage: out of the agent's default retrieval scope, recoverable on request, never silently deleted. Transitions between stages are one-click metadata moves; the underlying file and citation address remain stable.

surface is a lifecycle bucket driving retrieval scoring: dashboard = hot working set, library = warm searchable corpus, archive = cold. New CHECK-constrained column on artifacts with a partial index (project_id, space_id, created_at DESC) WHERE surface='dashboard' for the live-pane query, and a covering composite on (project_id, space_id, surface, created_at DESC) for cross-surface scans. Surface transitions are metadata-only mutations — disk paths stay stable so citation URIs never break; audit rows record the transition. Pinned items get a pinned_at timestamp and are excluded from auto-eviction. The dashboard cap policy is a heartbeat-task GC driven by a per-project soft/hard cap, not a hot-path eviction.

Projects are the top-level scope — one per client, product, or initiative. Inside a project, work splits across distinct contexts: Operations, Marketing, Legal Review, Q3 Audit. Spaces formalize that split as a second axis of organization. Each space carries its own dashboard view, its own assigned agents, its own document scope, its own access list, and its own retrieval boundary. The result is a clean separation of concerns without inflating the project list.

Spaces are retrieval partitions and memory namespaces: each space scopes its own FTS5 query window, its own agent memory store, and its own access list, so cross-context leakage between e.g. Legal Review and Marketing is structurally impossible without an explicit handoff. New spaces table (id, project_id, slug, name, parent_space_id, status, …); the dangling tasks.workspace_id column is repointed to tasks.space_id in a one-shot migration; space_id flows into artifacts, agents, schedules, heartbeat_tasks, and the retrieval tools. Nullable space_id means project root. Schema supports nesting via parent_space_id; UX ships flat in v1 to avoid combinatorial explosion in retrieval scopes (see Decision 5).

When an agent retrieves "the latest pricing study on Veo3", it should resolve the target in a single step. Without structured metadata, the agent opens many candidates and consumes context-window budget before finding the right one — driving cost up and grounding quality down. We attach a self-describing header to every artifact: subject line, agent-written summary, author list, tags, source, and a stable citation address. Retrieval reads the summary, selects the correct artifact, and only then loads the full content.

The retrieval problem at agent scale is token economics: an agent that opens ten files to find one ground-truth burns context-window budget and increases hallucination surface. We solve it with self-describing artifacts. New columns on artifacts: subject, summary (LLM-written at creation, the cite-without-load primitive), source_kind, source_uri, authors_json, tags_json, parent_artifact_id, version, lifecycle_state, retention_until, pinned_at, last_referenced_at. Sibling tables artifact_authors and artifact_links form a provenance DAG — any agent-generated claim is traceable back to its source artifacts. Sparse retrieval ships first: FTS5 virtual table over subject + summary + tags + content_head with tokenize = 'porter unicode61', BM25-ranked. Phase D upgrades to hybrid retrieval by joining FTS5 with dense embeddings (sqlite-vec / Voyage / Cohere embed-v3) via Reciprocal Rank Fusion. Citation grade madarx:// URIs map cleanly onto Anthropic citations and OpenAI structured-output reference fields, so the same URI works inside the model's response, inside the dashboard, and across federation peers.

Every project, space, and surface uses an identical directory shape. An INDEX.md manifest at each level enumerates the artifacts in scope: title, summary, author, timestamp, citation URI. An agent reads the manifest first, selects the relevant artifacts, and only loads the files it needs — a pattern borrowed from Anthropic's file-search and tree-grounded retrieval work. The same tree is navigable by a human in Finder or VS Code without translation.

Deterministic layout is an ACI design choice: the agent's filesystem read is a single INDEX.md manifest per level, embeddable in the system prompt or fetched on demand by a file-search tool — so the agent locates artifacts in O(depth) reads, not O(n). Helpers in lib/artifact-paths.js compute canonical paths workspace/projects/<slug>/spaces/<space>/<surface>/<file>. lib/artifact-indexer.js rebuilds INDEX.md at project and space level on artifact mutation, debounced 1 s and queued through a heartbeat task so bursty writes don't hot-loop the indexer. scripts/rebuild-indexes.mjs handles cold rebuilds. The pattern resembles Anthropic's file-search and tree-grounded retrieval — citation paths are stable, the directory shape is identical across deployments, and a Claude Code sub-agent or external MCP client can crawl the tree without bespoke instructions.

workspace/
 projects/
 <project-slug>/
 INDEX.md # project-level agent index
 spaces/
 <space-slug>/
 INDEX.md # space-level agent index
 dashboard/ # surface = dashboard
 <artifact-id>--slug.md
 library/ # surface = library
 <yyyy>/<mm>/
 <artifact-id>--slug.md
 archive/ # surface = archive
 <yyyy>/<mm>/
 <artifact-id>--slug.md
 _project-root/ # space_id IS NULL
 dashboard/ library/ archive/
 uploads/ # Disk uploads
 <yyyy>/<mm>/<sha256>.<ext>

Inside one organization, a single madarX instance runs one main orchestrator and a team of specialist agents. The orchestrator delegates; the human operator approves the actions that matter. When two organizations collaborate, their orchestrators communicate across a cryptographically signed peering — neither side merges its data with the other. Agents on one side can request artifacts and deliverables from agents on the other. Trust is explicit, scope-bounded, and revocable.

Federation is our A2A (agent-to-agent) protocol with explicit capability scoping. Auth foundations are shipped: organizations, users, org_memberships, teams, team_memberships; agents and spaces gain team_id; approval_requests extends with phase and required_approver_role for multi-stage approval routing. The federation primitive is federation_peers(local_org_id, remote_endpoint_url, remote_org_pubkey, trust_label, scopes_json, status) where scopes_json is a manifest of the tools and project scopes this peer may delegate against — capability-token semantics. Transport is HTTPS POST to /api/federation/delegate with ed25519-signed payloads pinned to the peer pubkey; replay protection via signed nonce + monotonic clock. The delegate_to_peer tool sits at the irreversible_external tier — never auto-fired, always human-approved, even in trust-mode auto. Receivers materialize the brief as a sandboxed heartbeat task scoped to the delegated org; completion posts artifacts back to /api/federation/inbox with source_kind='federation' and a provenance link to the originating peer URI. Peer agents never execute on the local box. The protocol exchanges structured task briefs and artifacts, not code or weights — closing the obvious supply-chain attack vector that ad-hoc A2A schemes leave open.

Some customers want managed onboarding in minutes. Others must keep every byte inside their own infrastructure for residency or compliance reasons. madarX OS serves both from a single codebase. The deployment shape — managed cloud, customer-owned cloud, or on-premises appliance — is a configuration choice, not a separate product. Features and behaviors are identical across shapes.

One binary, three deployment shapes. Behavior gates on env: MADARX_HOST_MODE, MADARX_AUTH_MODE, MADARX_FEDERATION_ENABLED, MADARX_ARTIFACT_ENCRYPTION. Closed-source slices are additive packages (@madarx/cloud-billing, @madarx/cloud-quotas) with no runtime dependency in the OSS image. BYOK via per-org config (org.supabase_url + service key in customer-controlled KMS — we never see it). SQLite is the default store; Postgres adapter is the shape-C upgrade path for HA. Supply-chain hardening: deterministic Docker builds, CycloneDX SBOM on every release, cosign-signed images, optional in-toto attestations for ADGM-grade procurement. Residency invariants enforced at the auth + storage layer — the runtime never knows which region until env injection at boot, so the same image runs unmodified in UAE, EU, or air-gapped. Distribution: npm create madarx-app interactive installer, docker pull madarx/os:latest, hosted madarX.cloud signup.

Six decisions materially shape the product. Each card below presents the options, the trade-offs, and the recommended call. Recommendations are the current CTO position; alternative paths remain viable and reversible if subsequent evidence warrants a different choice.

Each decision is framed by three constraints in priority order: (1) minimize attack surface — every default starts in the most restrictive posture (default-deny allowlists, federation off, secrets vault required, irreversible_external never auto-approved); (2) maximize interoperability — MCP-shaped adapters, standardized tool registry, foundation-model-agnostic engines, stable citation URIs; (3) preserve forward optionality — where two options are close, pick the one that does not foreclose the other via a breaking migration. The recommendation column is the call I would make today as CTO; alternatives stay reversible.

Open source is the trust mechanism for security-sensitive infrastructure. madarX OS releases the orchestrator core under Apache-2.0 with installation paths for laptop, server, and on-prem appliance. The hosted edition is the managed convenience path; the OSS distribution is the sovereign path. Competitive differentiation is built on agent quality, depth of integrations, and the auditability of the governance plane — not on vendor lock-in.

The OSS surface is the load-bearing trust artifact: runtime, SQLite schema, agent registry, marketplace domain layer, tool adapters with their allowlists and rate limits, the A2A federation protocol, and the installer. Adapters expose an MCP-compatible tool shape so external MCP clients (Claude Desktop, IDE agents, custom harnesses) can consume the same registry. Engine layer is foundation-model-agnostic — Anthropic, OpenAI, Ollama, Hermes, Claude Code CLI all plug in behind a unified runAgentTick contract; switching engines is a per-agent config change, not a rewrite. Closed slices are optional add-ons (billing, quotas, telemetry aggregation, premium connectors). Repos: madarx-os (core, Apache-2.0), create-madarx-app (installer), madarx-docs (Diataxis structure on Vercel), madarx-cloud (private — billing, quotas, multi-tenant control plane).