- Spaces
- Projects
- Agents
- Tasks
- Workflows
- Approvals
- Marketplace

- Settings

document · 003 · architecture madarX OS · agent runtime atlas
← back to console

# madarX OS is the main operating layer for the madarX agent stack.

The OS orchestrates missions, calls specialist vertical agents such as RegOps and Butler/Concierge, manages approvals, and generates artifacts inside one governed workspace. This atlas shows how the runtime earns Hermes-class power without losing its audit floor.

filing meta

scope
  runtime architecture · approval contracts
repos
  madarx-os · hermes-agent · paperclip
classification
  internal · operator reference
palette
  Onyx · Platinum · Bone · Graphite · Mars

Core loop run_agent.py · gateway/run.py

Hermes is a personal AI runtime built around one loop. A platform adapter emits a normalised `MessageEvent`; `GatewayRunner` resolves a per-session `AIAgent`; the agent builds a prompt with optional memory + skills, calls the configured provider, dispatches tool calls through a self-registering registry, gates them through approval, and iterates until a final answer.

Click any step to see what is happening at that point in the loop.

#### 01 · Receive event · gateway/run.py · GatewayRunner

A platform adapter (WhatsApp, Slack, CLI) emits a MessageEvent with platform/chat/thread/user identifiers.

The WhatsApp adapter (gateway/platforms/whatsapp.py) starts scripts/whatsapp-bridge/bridge.js — a Node Baileys bridge — and polls inbound messages over a local HTTP loop (port 3010 on this machine).

Events are normalised before any agent code runs, so the same loop powers every platform.

State + storage~/.hermes

config
  `~/.hermes/config.yaml`
secrets
  `~/.hermes/.env`
state
  `~/.hermes/state.db` · SQLite + FTS
skills
  `~/.hermes/skills/<name>/SKILL.md`
cron
  `~/.hermes/cron/jobs.json` · `cron/output/`
WA bridge
  `scripts/whatsapp-bridge/bridge.js` · port `3010`

Memory is pluggable (`agent/memory_provider.py`) — built-in, Honcho, Mem0 etc. — and rendered into the prompt as a fenced block. Cron runs skip memory by default.

Delegation (`tools/delegate_tool.py`) spawns child `AIAgent` sessions with restricted toolsets and bounded concurrency/depth, returning only a summary to the parent.

Approval model tools/approval.py

Hardline. A non-negotiable blocklist refuses catastrophic commands — destructive system writes, credential exfil, fork bombs — with no override. This list never asks the user.

Smart classifier. Risky shell, file, and network actions are flagged and surfaced for `/approve` or `/deny` on the platform that initiated the call (CLI prompt, WhatsApp inline reply, gateway-managed approval).

Modes. `smart` (default), `manual` (every risky action asks), `off` (trusted env). Modes are per-session, never global. Decisions never leak between users or chats.

Comparison matrix Hermes · Paperclip · madarX

Capability | Hermes Agent | Paperclip | madarX OS
--- | --- | --- | ---
Storage | ~/.hermes/state.db (SQLite + FTS), ~/.hermes/config.yaml, ~/.hermes/.env | Postgres-style company control plane (companies, employees, goals, budgets, tasks, routines, governance, secrets, attachments). | data/madarx.sqlite (WAL, FK on) via node:sqlite + lib/schema.js.
Provider routing | Per-session + per-cron-job model override; provider router in run_agent.py. | Platform-agnostic — adapters phone home; the control plane does not run the model itself. | Engine string per agent (claude-code / anthropic / codex / ollama / hermes); no credential pool yet.
Memory | Pluggable memory_provider (built-in / Honcho / Mem0 / …) injected as a fenced block; cron skips memory. | Documents + attachments + activity feed give long-form recall; no LLM memory module of its own. | lib/agent-memory-context.js assembles a snapshot per run; no pluggable provider yet.
Skills | SKILL.md directories under ~/.hermes/skills, progressive disclosure via skills_list / skill_view. | Routines + work products + governance act as the skill substrate. | workspace/agents/<id>/skills.md + lib/agent-skills.js; not yet progressively loaded.
Sessions | Per (platform, chat, thread, user) AIAgent cached in GatewayRunner; FTS search across history. | Tasks / issues / activity per employee per workspace; durable, queryable. | chat_sessions + chat_messages; no full-text search.
Platforms | Pluggable adapters: WhatsApp (Baileys bridge on port 3010), CLI, more; uniform MessageEvent abstraction. | Adapters (Claude / Codex / CLI / HTTP / webhook) hooked in via plugins; hermes_local mentioned as external adapter. | Dashboard SSE + WhatsApp (Baileys on 127.0.0.1:3210); no shared adapter contract yet.
Cron / jobs | cron/jobs.json with prompt + schedule + skills + model + delivery + no_agent + toolsets; fresh AIAgent per run. | Routines + heartbeat at the company-process level. | lib/schedule.js parses human strings; cron-daemon queues heartbeat_tasks; worker honours retries, leases, approval pauses.
Approvals | tools/approval.py — hardline block + smart classifier; CLI / gateway /approve /deny; smart / manual / off modes. | Governance + approval workflows are first-class in the org model. | approval_requests rows; one-time consumption; irreversible_external tier always gated regardless of trust mode.
Subagents | delegate_tool spawns child AIAgent with restricted toolsets, bounded depth/concurrency; only summary returns. | Employees and routines compose, with explicit budgets. | lib/delegation.js + lib/delegation-contracts.js exist; concurrency / depth limits to harden.
Dynamic tools | MCP servers register tools at startup; toolsets.py gates exposure. | Plugins extend the control plane. | Static MARKETPLACE_TOOLS registry; no MCP dynamic registration yet.
Observability | state.db transcripts; cron/output artifacts. | Activity / events feed across the org. | audit_logs, agent_events, tool_egress, activity_log (SSE-bridged across processes).

Source-file map where the contracts live in this repo
Mission simulator type a goal — see tools, approvals, heartbeat, audit

This runs locally in the browser. It pattern-matches your prompt against the marketplace tool surface, then walks the approval / allowlist / heartbeat path the runtime would take in the active trust mode.

Open a PR titled “Fix WhatsApp pairing crash” in kareemodev777/madarx-os, email ak@madarx.io a 1-line summary, and read scripts/whatsapp-daemon.mjs first.

Active trust mode: `approval_required` · toggle modes in the madarX tab.

Output

Press Simulate mission to see the runtime decision trace.