HART OS

Hevolve Hive Agentic Runtime

The AI-native operating system for every device, from your computer to embodied AI. Local-first, federated, OpenAI-compatible.

HART = the bare engine (pip install hart-backend, listens on :6777).
HART OS = the full AI-native OS. It boots on a laptop, server, or edge node, runs on phones, and reaches into embodied AI, and it ships the agentic Liquid Shell, Model Bus, model catalog, channel pairing, agent dashboard, and hive view.
Nunba = the consumer companion app, one signed client across Windows / macOS / Linux.

AI-native means the OS adapts to the machine, not the other way around. On each device it probes what the hardware can actually do, serves LLM, vision, and speech to every app over the Model Bus (socket, D-Bus, or HTTP), and lets the on-device model compose the interface and learn each task once so it can replay it later. The runtime that drives a desktop is the same one that drives a robot, so a robot's AI access is just another Model Bus call. It is one Python codebase that runs in three shapes (flat laptop, regional LAN, or central cloud mesh), speaks the OpenAI protocol on :6777/v1/chat/completions, and federates with peers over PeerLink (direct peer-to-peer WebSocket, no broker). A boot-time guardrail hash, re-checked every 300 seconds, plus Ed25519 release signing, keep humans in control.

You would notice it last, the way you notice anything alive: it improves on its own. Each node learns from what it does and gets quietly better, locally, on your own hardware, with nothing leaving the device. Calling an operating system alive should make you reach for the off switch, so that came first: the self-improvement is a toggle, every node is killable on its own, and it runs only as long as you let it.

This README is written to be read by people and by agents alike. Every capability below names the file it lives in, so whether you are a developer or an AI agent exploring the repo, you can go from a feature straight to its source.

Status: public alpha. The runtime, the Model Bus and the channel
adapters are in daily use; APIs still move. Issues and PRs are genuinely
wanted — see Contributing.

Table of Contents

• Why HART OS?
• 60-second start
• How it compares
• Capabilities
• Hello, agent
• Architecture map
• API surface
• How auto-evolve works
• How hive connectivity works
• Topology
• Build / extend
• Economics (for node operators)
• Documentation index
• License

Why HART OS?

Most software described as AI-powered ships an assistant: a separate app,
usually talking to somebody else's server, that can drive a few functions.
Remove the assistant and everything underneath works exactly as before.

HART OS inverts that. Inference becomes a service the system provides, the
way it provides a filesystem or a network stack. An application does not
bundle a model or hold an API key — it asks the OS, and the OS decides which
model answers, running locally where it can. Ten apps on one machine do not
each load their own copy or each pay their own bill.

That has a practical consequence worth stating plainly: every device
becomes the same target. The runtime driving a laptop is the runtime
driving a robot, so a robot's AI access is just another Model Bus call, and
code written against :6777/v1/chat/completions runs unchanged on both.

If you are here to contribute, the parts that most need outside eyes are
the auto-evolve loop (autoresearch_loop.py), the guardrails that gate every
self-improvement (hive_guardrails.py), and the 31 channel adapters — the
most self-contained place to start. See CONTRIBUTING.md.

60-second start

git clone https://github.com/hertz-ai/HARTOS.git && cd HARTOS
python3.10 -m venv venv && source venv/Scripts/activate   # Windows: venv\Scripts\activate.bat
pip install -r requirements.txt
echo "OPENAI_API_KEY=sk-..." > .env       # or GROQ_API_KEY, or none for local llama.cpp
python hart_intelligence_entry.py         # listens on :6777

# OpenAI-compatible (drop-in for any OpenAI SDK / LangChain / LiteLLM / Aider / Continue)
curl -X POST http://localhost:6777/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "hevolve", "messages": [{"role": "user", "content": "Hello"}]}'

Live demo · Full quickstart · Nunba desktop

How it compares

Capabilities

Agent runtime

Auto-evolve, baselining, benchmarking

Hive connectivity + federation

Idea engine (thought experiments)

LLM + multimodal

Channels (31 adapters)

ResponseRouter fan-out + WAMP desktop mirror; per-channel agent + prompt assignment; AutoGen-side tools so agents can register/send via channels themselves. Catalog endpoint: GET /api/social/channels/catalog.

Personality + resonance

Memory + knowledge

Distributed compute + economics

Security + governance

HevolveArmor (source protection)

Platform layer (HART OS specific)

Desktop / OS management (Nunba surface)

Vision + robotics

Other integrations

• Agent Protocol 2 (e-commerce, payments) - integrations/ap2/
• Google A2A (dynamic agent registry) - integrations/google_a2a/
• MCP (Model Context Protocol) servers - integrations/mcp/
• Internal A2A (task delegation between agents) - integrations/internal_comm/
• Skills (reusable capability bundles) - integrations/skills/
• Marketing tools (campaigns, content gen, video orchestrator) - integrations/marketing/, marketing_tools.py, video_orchestrator.py
• Trading agents (SmartLedger-tracked, budget-gated) - trading_tools.py
• Coding agent (idle compute -> distributed code tasks via Aider in-process) - integrations/coding_agent/
• Web crawler - integrations/web_crawler.py
• Kids learning (25+ educational game templates) - api_games.py

Hello, agent

import requests

# 1. CREATE: teach a task once, save the trace as a recipe
requests.post("http://localhost:6777/chat", json={
    "user_id": "alice",
    "prompt_id": "research_assistant",
    "prompt": "Find arXiv papers from the last week on speculative decoding",
    "create_agent": True,
})

# 2. REUSE: replay the recipe, no LLM calls on cached steps
for query in ["mixture of experts", "constitutional AI"]:
    res = requests.post("http://localhost:6777/chat", json={
        "user_id": "alice",
        "prompt_id": "research_assistant",
        "prompt": query,
    })
    print(res.json()["output"])

Custom tools, channel bindings, agent plugins: docs.hevolve.ai/agent-plugin.

Architecture map

HART OS  (port 6777)
|-- Engine            CREATE -> save Recipe -> REUSE (90% faster replay)
|-- Agent runtime     GoalManager . AgentDaemon . SpeculativeDispatch . ParallelDispatch . AutoEvolve
|-- Auto-evolve       Hypothesis -> 33-rule filter -> hive vote -> sandbox -> RSI-2 gate -> federate
|-- Baselining        agent_baseline_service . benchmark_registry . benchmark_tracker . hive_benchmark_prover
|-- Memory            Shared LangChain + AutoGen buffer (zero parallel paths) . MemoryGraph . SimpleMem
|-- Channels (31)     ResponseRouter fan-out + WAMP desktop mirror + per-channel agent binding
|-- Providers (15)    Universal gateway . AES-256 keys . cost/latency/capability routing
|-- Multimodal        Whisper STT . 6 TTS engines . MiniCPM VLM . VRAM-tiered
|-- Hive              PeerLink P2P (NAT-traversed) . FederatedAggregator (equal-weighted)
|                     Gossip + verification . hash-gated handshake . EventBus + WAMP bridge
|-- Idea Engine       Thought experiments . ComputePledge . type-aware agents . Hive View
|-- Compute           3-tier topology (flat/regional/central) . SmartLedger . ComputeMesh . ComputeEscrow
|-- Economics         AdService (70/50) . RevenueAggregator (90/9/1) . log-scaled compute democracy
|-- Security          33 guardrails . Ed25519 master key . 3-tier cert chain . RuntimeMonitor
|                     ImmutableAuditLog . tool allowlist . ActionClassifier . DLP . rate limiter
|-- HevolveArmor      AES-256-GCM modules . BCC compile-to-C . RFT AST renaming . anti-debug
|-- Platform          ServiceRegistry . AppRegistry . AppManifest . Bootstrap . EnvironmentManager
|-- Desktop           Shell APIs . app installer . NixOS modules . LiquidUI . themes . remote desktop
|-- CLI               hart (21 subcommands) . OpenAI-compatible client . Aider in-process backend
`-- Other             AP2 . Google A2A . MCP . skills . marketing . trading . coding agent . vision

Full architecture: docs.hevolve.ai/architecture.

API surface

POST /chat                                Core agent (LangChain + AutoGen)
POST /v1/chat/completions                 OpenAI-compatible (drop-in)
POST /time_agent                          Scheduled task execution
POST /visual_agent                        VLM + computer use
GET  /status                              Health

# Hive + thought experiments
POST /api/social/experiments/auto-evolve  Start evolution cycle
GET  /api/social/hive/active              All parallel agents (Hive View)
POST /api/social/hive/<id>/inject         Inject mid-experiment variable
GET  /api/social/tracker/experiments      Experiment tracker with task progress

# Channels
GET  /api/social/channels/catalog         All 31 channels + capabilities
POST /api/social/channels/bindings        Bind a channel to an agent
POST /api/social/channels/pair/generate   QR for cross-device pairing

# Goals + dashboard
POST /api/goals                           Create an autonomous goal
GET  /api/social/dashboard/agents         Truth-grounded agent overview

# Compute + earnings
GET  /api/compute-earnings/summary        Per-node earnings breakdown
GET  /api/settings/compute                Local compute policy
PUT  /api/settings/compute                Update policy
PUT  /api/settings/provider               Provider config (cause alignment, electricity rate)
PUT  /api/settings/provider/join          Opt into provider role

# A2A protocol
GET  /a2a/<prompt_id>_<flow_id>/.well-known/agent.json
POST /a2a/<prompt_id>_<flow_id>/execute

195+ endpoints total. Full reference.

How auto-evolve works

chat / tool call / observed outcome
   v
autoresearch hypothesis            (what could improve next response)
   v
33-rule guardrail filter           (immutable, hash-verified, rejects unsafe)
   v
hive vote                          (humans + agents, confidence-weighted)
   v
top-k dispatched to parallel sandboxes
   v
benchmark replay vs baseline       (per-agent baseline at agent_data/baselines/)
   v
RSI-2 monotonic gate               (must beat last commit on every metric)
   v
PR review                          (auto-rejects regression, hive contests merge)
   v
upgrade orchestrator               (BUILD -> TEST -> AUDIT -> BENCHMARK -> SIGN -> CANARY -> DEPLOY)
   v
FederatedAggregator broadcasts the delta to peer nodes
   v
hart-update-service (OTA) pulls signed upgrade on every node

Owner can pause, resume, or veto at any stage. Mechanism details.

How hive connectivity works

Same-user devices
  trust = SAME_USER          -> no encryption (user_id auth), LAN or WAN
  
Cross-user peers
  trust = PEER               -> E2E encryption (per-link key)
  
Through relay (NAT-bound)
  trust = RELAY              -> E2E encryption (relay can't read)

Crossbar = safety measure (telemetry metadata + kill switch). Never content path.

Connection budget per tier:  flat=10  regional=50  central=200
ALL tiers participate equally in hive consensus.
Federation handshake = byte-for-byte guardrail hash match. Mismatch -> refused.

PeerLink is wired into bootstrap, gossip, federation, compute_mesh, world_model_bridge. Wire format.

Topology

Same code path. Env-detected at boot via HART_OS_MODE or /etc/os-release ID=hart-os. Port resolution: override > env var > OS / app mode default.

Build / extend

Front it with /v1/chat/completions (any OpenAI client), the hart CLI, or build for the desktop with Nunba.

Economics (for node operators)

Advertisers pay for witnessed impressions
   |
   v
Ad service           70% witnessed view, 50% unwitnessed
   |
   v
Compute democracy    log scaling, max 5% influence per entity, +20% diversity bonus
   |
   v
   90% -> Contributors  (compute, hosting, training)
    9% -> Infrastructure (regional hosts, bandwidth)
    1% -> hevolve.ai     (master key, central coordination, security)

Idle GPU in Tokyo serves Berlin. Reward score weighted by gpu_hours, inferences, energy_kwh, api_costs. Per-node cause_alignment and electricity_rate_kwh affect dispatch routing. Joining the Hive.

Documentation index

License

Apache License 2.0.