osmoda: The System Platform
Where the AI Agent Runs the System

01 The Problem We Solve

A developer with a $3,500 Mac Studio tops out at 4-5 concurrent AI agents. When agent #5 spawns and the OOM killer fires, all five die. Your agents crash at 3am and nobody notices until morning. You're running critical automation on hardware with no audit trail, no rollback, no self-healing, and no way to prove what happened.

The AI agent ecosystem is exploding - Claude Code, Cursor, Devin, AutoGPT, CrewAI, LangGraph - but the infrastructure layer is stuck in the 2010s. Developers are running these agents on bare Linux VMs with systemd and docker-compose, praying nothing breaks. There's no system platform designed specifically for the workload patterns of autonomous AI agents: bursty resource usage, long-running sessions, inter-agent communication, and the absolute requirement for auditability.

osModa is that system platform. Not a container. Not a VM image. Not a SaaS platform. A NixOS distribution built from the ground up to make AI agent infrastructure self-managing, auditable, and resilient.

00b What's new since v1.3.1

The page underneath this banner was written at v1.3.1. The shipped product is at v1.3.36 + gateway v0.2.4. Material changes since the original write-up:

• v1.3.18 — gateway binds to 127.0.0.1 by default (was 0.0.0.0); single bindCredentialToGateway() path for dashboard + reseller key delivery.
• v1.3.20 — Stop button kills the whole process group, not just the leader. detached: true spawn + process.kill(-pid, "SIGTERM") + 2 s SIGKILL escalation.
• v1.3.24 — Long-running tasks supported. CHAT_WATCHDOG_MS 15 min, FIRST_SIGNAL_TIMEOUT_MS 10 min, OSMODA_CHAT_HARD_CAP_MS 8 h default (env-overridable). Same caps for both claude-code and openclaw drivers.
• v1.3.25 — Dual-signal wedge detection (heartbeat and chat-frame must both be stale before flagging wedged). Eliminates the "Agent stalled — restarting" false positive class.
• gateway v0.2.1 — Sessions persist to disk at /var/lib/osmoda/state/sessions.json (atomic tmp+rename, debounced 250 ms, mode 0600). Agent memory survives gateway restarts and idle gaps. Session.runtime tags every session so flipping claude-code ↔ openclaw via the Engine tab wipes the foreign session id and starts cleanly in the new runtime — no more "claude session not found" on swap.
• install.sh — openclaw binary installed on every spawn (was: only when --runtime=openclaw). Engine-tab runtime swap now always lands on a present binary.
• gateway v0.2.2 — optional CodeGraph code-intelligence MCP server (pure-WASM, env-gated OSMODA_CODEGRAPH_ENABLED=1): 9 codegraph_* tools + a pre-indexed knowledge graph over /opt/osmoda, /workspace/*, /srv/*, ~90% fewer grep/Read calls.
• v1.3.35 — chat replay + streaming overhaul: single-source replay (no duplicate messages), markdown-formatted restored replies incl. tables, a clear history/live divider, smooth requestAnimationFrame text reveal, even spacing.
• gateway v0.2.3 — OpenClaw 2026.5+ driver ported — selectable in the Engine tab again (the run→agent rename had blocked it). claude-code reply-corruption fix: reply text is de-duplicated per assistant message.id so multi-message turns (text → tool → text) no longer glue/garble. Tool-action targets: each tool call carries a command/path/url hint so the action log shows what the agent is doing.

02 Three-Tier Trust Architecture

Security isn't bolted on. It's the foundation. osModa implements a three-tier trust model inspired by CPU privilege levels, but applied to the agent ecosystem:

This isn't theoretical. Every API call, every file mutation, every network request flows through the trust model. The AI agent in Tier 0 can grant capabilities to Tier 1 apps, and Tier 1 apps can invoke Tier 2 tools - but never the reverse. Lower tiers cannot escalate privileges upward by design. Tier 0 remains the trusted computing base and must be governed by approval policies, spending limits, and audit review. NixOS rollback covers system configuration - it does not undo data sent to external APIs, signed transactions, or exposed secrets.

03 The 10 Daemons

osmoda runs 10 specialized daemons (9 in Rust + 1 in TypeScript), each with a single responsibility. Most communicate over Unix domain sockets. No cloud dependencies. The 9 Rust daemons are compiled for memory safety, performance, and zero-garbage-collection pauses. The 10th - osmoda-gateway - is the TypeScript modular agent gateway: it speaks HTTP+WS on a localhost port and routes per-agent to a pluggable runtime driver (claude-code or openclaw), making credentials and models switchable at runtime via the dashboard.

04 91 MCP Tools

The AI agent doesn't shell out to run commands. It uses 92 structured, typed, audited MCP tools registered via the osmoda-bridge plugin (and consumed identically by the claude-code runtime via stdio). Every tool call is logged with the hash-chained event ledger. Every result is traceable. Here's what the agent can do:

System Operations

system_health - CPU, RAM, disk, load, uptime in one call. system_query - Query processes, services, ports, connections, NixOS generations. system_discover - Auto-detect all running services, listening ports, and systemd units. event_log - Browse the hash-chained audit trail with filters. shell_exec - Execute commands with full audit logging. file_read, file_write, directory_list - Filesystem operations with access control.

Memory & Intelligence

memory_store - Persist knowledge with categories and tags. memory_recall - FTS5 keyword search across all stored knowledge. The memory system uses SQLite FTS5 with Porter stemming for keyword search. Markdown files in /var/lib/osmoda/memory/ are ground truth. Vector search (ZVEC + nomic-embed) is planned for a future release.

Deployment & Self-Healing

safe_switch_begin, safe_switch_commit, safe_switch_rollback - Atomic deployments with health gates. Begin a deployment, run health checks, commit if everything passes, auto-rollback if anything fails. safety_rollback, safety_panic, safety_restart - Emergency controls for when things go wrong. watcher_add, watcher_list - Define autopilot health checks that run continuously in the background. routine_add, routine_trigger - Schedule cron jobs, event hooks, and webhook handlers.

Crypto Wallets

wallet_create, wallet_list, wallet_sign, wallet_send, wallet_delete, wallet_receipt - Full wallet lifecycle. Create ETH/SOL wallets, sign transactions with policy gates (daily limits, address allowlists), and generate audit receipts. Keys are AES-256-GCM encrypted and never leave the keyd daemon.

P2P Mesh Networking

mesh_identity, mesh_invite_create, mesh_invite_accept, mesh_peers - Establish encrypted peer-to-peer connections between osModa nodes. mesh_peer_send, mesh_room_create, mesh_room_join, mesh_room_send, mesh_room_history - Direct messages and group communication channels. mesh_health, mesh_peer_disconnect - Monitor and manage the mesh topology. All traffic encrypted with Noise_XX + ML-KEM-768 hybrid post-quantum cryptography.

MCP Server Management

mcp_servers, mcp_server_start, mcp_server_stop, mcp_server_restart - Manage any MCP server as a first-class OS capability. The mcpd daemon handles lifecycle, health monitoring, and auto-restart. Add MCP servers via NixOS config and they become available to the agent instantly.

Code Intelligence (CodeGraph)

codegraph_search, codegraph_context, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_node, codegraph_explore, codegraph_files, codegraph_status - A pre-indexed code knowledge graph (tree-sitter AST → SQLite, 100% local, 19+ languages). The agent queries symbol relationships, call graphs, and change blast-radius instantly instead of grep-spraying — ~90% fewer tool calls on code tasks. Auto-indexed across the OS's own source (/opt/osmoda), spec-kit projects (/workspace/*), and deployed apps (/srv/*), kept synced every 30 min. Your agent knows your code's structure before it reads a single file.

Voice Control

voice_status, voice_speak, voice_transcribe, voice_record, voice_listen - Talk to your server. All processing happens locally via whisper.cpp (STT) and piper (TTS). No audio data ever leaves the machine. Zero cloud dependency.

05 Hash-Chained Audit Trail

Every mutation in osModa is logged to an append-only SQLite event log with cryptographic hash chains. Each event includes a SHA-256 hash computed from the event ID, timestamp, type, actor, payload, and previous event hash. This creates a tamper-evident chain - if any event is modified or deleted, the hash chain breaks and the tampering is immediately detectable.

This isn't just logging. It's cryptographic proof of everything your system has done. The tamper-evident audit trail provides supporting infrastructure useful for compliance-oriented environments (SOC 2, HIPAA) - though the ledger alone does not constitute regulatory readiness. For incident forensics, for understanding exactly what happened at 3am when an agent made a decision. The hash chain can be independently verified with the agentctl verify-ledger command - no trust required, pure math.

06 NixOS: Atomic, Reproducible, Rollbackable

osModa is built on NixOS, the only Linux distribution with truly atomic system configuration. Every system state is a "generation" - a complete, immutable snapshot of the entire OS configuration. Rolling back to any previous state takes less than a second.

This means: a bad configuration change doesn't brick your server. A failed software update doesn't leave your system in an inconsistent state. The AI agent can make system changes with confidence, because every change is reversible. The SafeSwitch daemon (osmoda-watch) integrates directly with NixOS generations - deploy a change, run health checks, and auto-rollback if anything fails.

NixOS also means reproducibility. The exact same system configuration produces the exact same system state on every machine, every time. No more "works on my machine" for infrastructure. If it works on one osModa node, it works on all of them.

07 Post-Quantum Encrypted Mesh

osModa nodes communicate via a peer-to-peer encrypted mesh network. No central server. No cloud relay. Direct connections between nodes using the Noise_XX handshake protocol with X25519 key exchange, ChaCha20-Poly1305 symmetric encryption, and BLAKE2s hashing.

But we go further: ML-KEM-768 hybrid post-quantum key encapsulation is layered on top of the Noise handshake. Even if a quantum computer breaks the X25519 key exchange in the future, the ML-KEM-768 layer ensures your historical traffic remains confidential. This is defense-in-depth for the post-quantum era.

Pairing is invite-based: one node creates an invite code, another accepts it. No discovery protocol that could leak your network topology. No DNS. No central registry. Each node has an Ed25519 identity key for signing and an X25519 key for encryption, plus the ML-KEM-768 key for post-quantum protection.

Use cases: multi-server agent fleets that coordinate via encrypted mesh. Edge devices reporting to a central node. Distributed agent swarms that communicate without any internet dependency.

08 Self-Healing Infrastructure

The core promise of osModa: your server fixes itself at 3am so you don't have to.

The self-healing loop works at three levels:

Level 1 - Autopilot Watchers (osmoda-watch): Deterministic health checks that run continuously. CPU above 90% for 5 minutes? Restart the heaviest process. Disk above 85%? Clean Nix store garbage. Service crashed? Restart it. If restart fails, escalate.

Level 2 - SafeSwitch Deployments (osmoda-watch): Every system change goes through the SafeSwitch engine. Apply the change, run health gates (HTTP checks, port checks, process checks), and auto-rollback to the previous NixOS generation if any gate fails. Zero-downtime deployments with guaranteed rollback.

Level 3 - Agent Intelligence (agentd + teachd): The AI agent analyzes patterns across the event log, memory system, and operational data. It doesn't just react to failures - it predicts them. Disk usage trending toward 100%? The agent schedules cleanup before you run out of space. A service crashes every Tuesday at 3am? The agent investigates the root cause and proposes a fix.

All three levels are logged to the hash-chained audit trail. You can see exactly what the system did, when it did it, and why - down to the millisecond.

09 20 System Skills

Beyond the 91 tools, osmoda ships with 20 pre-built skills - structured workflows that combine multiple tools into higher-level capabilities. Each skill is a markdown file under skills/<name>/SKILL.md with YAML frontmatter; the agent invokes one when its description matches the user's intent.

Operational

self-healing - detect failures → diagnose → auto-fix · morning-briefing - daily infra health digest · security-hardening - continuous scoring + auto-remediation · natural-language-config - "enable Postgres on port 5433 with 2GB shared buffers" turns into a NixOS PR · predictive-resources - forecasts exhaustion before it happens · drift-detection - finds imperative changes that left declarative config · generation-timeline - time-travel debugging across NixOS generations · flight-recorder - black-box telemetry for post-incident analysis · nix-optimizer - reclaims store disk space safely.

Surfaces

system-monitor · system-packages · system-config · file-manager · network-manager · service-explorer - every system admin surface, fronted by AI.

Application + agent deployment

app-deployer - deploy + manage user apps as systemd units (app_deploy, app_logs, app_remove). deploy-ai-agent - deploy LangChain / CrewAI / AutoGen / Dify workloads onto the same machine, sharing memory and audit ledger.

Multi-perspective analysis (swarm)

swarm-predict - multi-perspective risk analysis via persona debate. Same prompt, 5-9 distinct personas, scored convergence. scaled-swarm-predict - 50-200 simulated agents on a synthetic Twitter/Reddit topology, useful for product launch + content reception forecasting.

teachd's SKILLGEN loop (see § 4b) auto-generates new SKILL.md files when it detects the agent repeating the same tool sequence across sessions. The skill catalog grows as the system learns your patterns.

4b Self-Learning (TeachD)

The osmoda-teachd daemon turns operational data into knowledge and new skills. Three loops run continuously, each at a different cadence:

The TEACH API (POST /teach) injects context-relevant KnowledgeDocs into agent prompts at runtime - so when the agent picks up a problem similar to one it solved last week, it remembers what worked. The Optimizer proposes system-level optimizations (NixOS config tweaks, sysctl knobs, service tunings) which the operator promotes through SafeSwitch with full rollback.

Endpoints (Unix socket /run/osmoda/teachd.sock): /observations, /patterns, /knowledge, /teach, /optimize/suggest, /optimize/apply, /skills/candidates, /skills/detect, /skills/generate/{id}, /skills/promote/{id}, /observe/action, /skills/execution, plus 7 read-only views. 19 endpoints total.

4c Spec-Kit (spec-driven dev, every spawn)

From v1.2.2 (2026-04-30), github/spec-kit v0.8.4 is baked into every spawn at install time (uv + specify-cli + 9 speckit-* skills). Each spec-kit project lives under /workspace/<slug>/ with a five-phase lifecycle:

spec-kit project layout:
  /workspace/<slug>/
    ├── .specify/                  spec-kit metadata
    ├── memory/                    project-scoped agent memory
    ├── .claude/                   per-project agent profile
    └── specs/<n-name>/
        ├── spec.md                phase 1 - what + why
        ├── plan.md                phase 2 - tech stack + constraints
        └── tasks.md               phase 3 - work breakdown

Phase progression: scaffolded → constitution → specifying → planning → tasking → implementing → tests-green. The dashboard's Factories tab shows every spec-kit project on a server with its current phase.

MCP tools

spec_kit_init - scaffold a new project from a one-line brief. spec_kit_run - execute a phase command (/speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement, etc.) inside the project directory, using claude with allowlisted tools. Output streamed back as JSON; full conversation log persisted to .claude/.

Public endpoints

GET /api/v1/spec-kit/projects                              # reseller (osk_), aggregated across orders
GET /api/dashboard/servers/{id}/spec-kit/projects          # dashboard, single server

Both return per-project metadata: slug, current phase, last implement timestamp, spec.md first lines, paths to spec/plan/tasks.md on the source server.

10 Who Is This For

osModa is useful when agents need to operate autonomously on real infrastructure - deploying services, managing configs, signing transactions, recovering from failures - without a human in the loop for every action.

Autonomous agent infrastructure - agents that run 24/7, self-heal, deploy code, and make system-level decisions. Typed tools, not shell scripts. Audit trails, not log files.

Compliance-sensitive operations - hash-chained audit ledger provides tamper-evident logging useful for compliance-oriented environments. A foundation for audit programs, not a turnkey compliance solution.

Offline / edge / air-gapped - P2P encrypted mesh, local voice processing, no cloud dependencies. Nodes operate indefinitely without internet connectivity.

Crypto and financial agents - policy-gated key management (osmoda-keyd), spending limits, address allowlists, every signing operation audited. Keys never leave the daemon.

11 Daemon / Use Case Matrix

Which daemons matter depends on the workload.

12 Installation

One command gives your server a brain. The installer handles everything: NixOS conversion, Rust builds, modular osmoda-gateway (claude-code + openclaw drivers), 91 MCP tools, agent identity, and daemon startup.

Quick Install

Installer Options

What the Installer Does

Directory Layout After Install

Supported Platforms

Architectures: x86_64, aarch64. Base OS: Ubuntu 22.04+, Debian 12+, existing NixOS. Tested on: major cloud providers and bare metal. Requirements: Root access, 4GB+ RAM recommended.

12b Full Installation from GitHub

Everything lives in one repo: github.com/bolivian-peru/os-moda. You can install osModa three ways: one-line installer, manual clone + build, or NixOS flake.

Method 1: One-Line Installer (Recommended)

Works on any Ubuntu 22.04+, Debian 12+, or existing NixOS box. Handles everything automatically.

The installer auto-detects your cloud provider (supports major cloud providers) and configures NixOS accordingly. After reboot (Ubuntu/Debian only), re-run with --skip-nixos.

Method 2: Manual Clone + Build

For developers who want more control over the build process.

Method 3: NixOS Flake (Native)

The proper NixOS way. Add the osModa flake to your system configuration.

Post-Install: Configure API Key

The legacy plaintext path (/var/lib/osmoda/config/api-key) still loads if present at boot, but new installs should use the encrypted store. Never paste raw keys into shell history or log files.

For OpenClaw runtime credentials, use the same POST /config/credentials endpoint with "provider":"anthropic" and "type":"api_key". The gateway writes the per-agent auth-profiles.json automatically before each session, serialized per-agent to prevent races between concurrent credential swaps.

Post-Install: Start All Daemons

Post-Install: Verify Everything Works

12c AI Agent Setup Guide

This section is for AI agents themselves - everything an autonomous agent needs to know to use osModa as its system platform. If you're an AI reading this, this is your manual.

How osModa Works for You (the Agent)

osModa gives you full system access to the machine through a structured API. You don't shell out to run commands blindly. You call daemon endpoints over Unix sockets that return structured JSON. Every action you take is logged to a tamper-proof audit trail.

Your 91 Tools (Grouped by Function)

Socket Addresses (All Local Unix Sockets)

How to Call Daemon Endpoints Directly

If you need to call endpoints outside the 92 registered tools, use curl over Unix sockets:

Agent Behavior Rules

If you are an AI agent running on osModa, follow these rules:

Setting Up Messaging Channels

osModa agents can be reached via web chat (port 18789), Telegram, and WhatsApp. All channels share one conversation - one agent, one mind.

Setting Up Remote Access

Connecting to Other Agents (Mesh)

osModa agents can form encrypted P2P networks. No central server. Invite-based pairing with post-quantum encryption.

Background Automation (Heartbeat)

osModa runs recurring tasks between conversations. These keep the system healthy without human intervention.

Self-Learning Loop (teachd)

The teach daemon runs two background loops that make your agent smarter over time:

13 Agent Identity & Personality

osModa's AI agent isn't a chatbot running on a server. It IS the server. Every process, file, network connection, and service is part of it. When you talk to it, you're talking to your machine.

Core Traits

Behavior Rules

The agent follows strict operational rules baked into its identity:

1. Diagnose before fixing - understand the problem before making changes. 2. Explain before changing - tell the user what will happen and why. 3. Validate before applying - dry-run NixOS rebuilds, check diffs. 4. Log everything - every mutation creates a hash-chained event. 5. Rollback on failure - NixOS makes this atomic and safe. 6. Ask for approval - destructive operations require explicit consent. 7. Remember - store diagnoses, preferences, and patterns for future recall.

Personality

Calm - never flustered, even when things break. Competent - knows the system inside and out. Proactive - volunteers information about issues it's noticed. Honest - says when it's unsure, warns when something is risky. Efficient - matches the user's technical level, doesn't over-explain obvious things.

Memory

The agent remembers past interactions, diagnoses, system changes, and user preferences. Memory is stored locally in the SQLite ledger with FTS5 full-text search. Markdown files in /var/lib/osmoda/memory/ are ground truth - always rebuildable, never dependent on cloud services. The agent recalls past solutions when similar issues arise, learns user preferences over time, and correlates events across subsystems. Vector search (ZVEC + nomic-embed) is planned for a future release.

Multi-Channel Presence

The agent exists across web chat, Telegram, and WhatsApp simultaneously - all one conversation, one mind. It adapts response length to the channel: shorter on Telegram/WhatsApp (phone), more detailed on web (desktop). Messages from any channel reach the same agent context.

14 Full API Reference

Every daemon exposes a JSON API over Unix domain sockets. The 10th, osmoda-gateway, also exposes HTTP+WS on a localhost port for the modular runtime + credential surface. No public HTTP. All communication is local. Here's the complete endpoint reference.

14a Reseller surface — full parity with the dashboard

Every operational capability the dashboard surface offers is mirrored on the v1 reseller surface. Same shape, same events, only the auth differs (osk_ Bearer instead of sk_live_/cookie). Drop these endpoints into your integrator UI and you get the same chat-bubble experience osmoda's own dashboard renders.

Reference integration (browser, Node, edge — any fetch-capable runtime)

// 1. On chat tab open: replay history first
const r = await fetch(`https://spawn.os.moda/api/v1/servers/${orderId}/chat-history`, {
  headers: { Authorization: `Bearer ${osk}` },
});
const { events } = await r.json();
events.forEach(renderBubble);   // user / agent / tool bubbles

// 2. Subscribe to live events (request lifecycle, agent.wedged/healed, etc.)
// Browsers: use eventsource-polyfill + Authorization header,
// Node: import EventSource from 'eventsource'.
const es = new EventSource(
  `https://spawn.os.moda/api/v1/servers/${orderId}/events?cursor=0&filter=request,state,agent`,
  { headers: { Authorization: `Bearer ${osk}` } }
);
es.addEventListener('server', e => renderEventBubble(JSON.parse(e.data)));

// 3. Open the live chat WS for new messages
const ws = new WebSocket(`wss://spawn.os.moda/api/v1/chat/${orderId}?token=${osk}`);
ws.onmessage = e => renderLiveFrame(JSON.parse(e.data));

// 4. Set/rotate AI key (Engine-tab equivalent for resellers)
await fetch(`https://spawn.os.moda/api/v1/servers/${orderId}/api-key`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${osk}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ api_key: 'sk-ant-api03-…', provider: 'anthropic' }),
});
// then watch the events stream for `state.changed has_api_key:true`

// 5. Wedged-agent recovery (auto-fired by spawn-server's wedge detector too)
await fetch(`https://spawn.os.moda/api/v1/servers/${orderId}/agents/osmoda/restart`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${osk}`, 'Content-Type': 'application/json' },
  body: '{}',
});

Same bubbles as the dashboard. The dashboard chat UI renders identical bubbles for these events; integrators reusing the event shapes get the same loaders + status indicators by mapping each event type to a UI component. The reference dashboard implementation lives in apps/spawn/public/dashboard.html (search for renderServerEventBubble, loadDashChatHistory).

14b v1.3.0 Unified Server Event Plane

Every async action on a spawned server (chat message, agent restart, key delivery) returns a typed request_id and emits typed lifecycle events on a per-server SSE stream. One subscription, all actions. Cursor-resumable, 15 s keepalive, 30 min hard timeout. Same shape on the dashboard surface (sk_live_ Bearer or session cookie) and the reseller surface (osk_ Bearer).

14c v1.3.1 Wedge Detection & Self-Serve Recovery

Driven by a real integrator bug report: a wedged-agent state where heartbeats kept landing (daemon alive) but the chat-agent was silent, the v1.2.7 detector never fired (heartbeat-only signal), and the auto-restart was one-shot — one SSH failure left orders wedged forever. v1.3.1 ships three additive layers.

v1.3.25 update — dual-signal detection. The wedge detector now requires both the agentd heartbeat and the gateway chat-frame signal (agent_last_frame_at) to be stale before flipping agent_wedged=true. Recovery clears the flag the moment either signal goes fresh. This removes a false-positive class where the heartbeat sender was wedged but the agent was actively answering chat — previously the order showed "Agent stalled — restarting" while the agent was perfectly responsive. The recovery log now includes alive_via: "heartbeat" | "agent_frame" so operators can see which plane carried the heal.

1. chat_responsive signal (decoupled from heartbeat)

New boolean on the server-list and spawn-log responses. Tracks the last frame received from the customer gateway WebSocket — independent of the agentd heartbeat cron. true = frame in last 5 min. false = WS connected but silent for >5 min while heartbeats continued. null = no recent session, fall back to agent_responsive. Integrator guidance: gate canChat on chat_responsive !== false (treat null as unknown-OK).

2. Retry-with-backoff auto-restart

Was one-shot in v1.2.7; now retries 4 times across 0/5/10/30 min backoff before emitting agent.escalation_required on the unified plane. New surfaces: auto_restart_attempts, auto_restart_status (restarting | ready | failed | timeout | exhausted), last_auto_restart_attempt_at. Counters reset on recovery.

3. Reseller spawn-log endpoint

Also: typed 503 codes from chat-async — gateway_wedged (room exists, agent_wedged) vs gateway_unreachable (room exists, WS closed) vs agent_disconnected (no room) — each carrying fallback_recommendation. Stale-conversation auto-clear after 6 min so a dead prior chat doesn't permanently 409-block future requests.

15 Complete Tool Reference91 tools

All 91 tools registered by osmoda-bridge via the api.registerTool() factory pattern. These are the structured, typed, audited commands available to the AI agent regardless of which runtime (claude-code or openclaw) is driving it.

System & Core 10

Memory & Intelligence 2

Network 1

Deployment & SafeSwitch 4

Watchers & Routines 5

Crypto Wallets 6

P2P Mesh 11

MCP Servers 4

Teaching & Learning 8

Voice 5

Identity, Receipts & Backup 6

Safety & Emergency 4

Wallet TX builder 1

Approval gate 4

Anything destructive routes through this gate. The agent requests; the human approves. Backed by SQLite, expiring entries, exportable for audit.

The four approval tools are wired and persist to SQLite, but enforcement is currently advisory — the agent's system prompt instructs it to call approval_request before destructive ops. Hard-blocking enforcement (a wrapper around shell_exec + the wallet daemon's signing path that refuses to proceed without an approved id) is on the v1.4 roadmap.

Sandbox + capability tokens 2

Fleet (multi-server) 4

When you run multiple osmoda servers in a mesh, deploys can be quorum-voted across the fleet rather than one-at-a-time SafeSwitches.

Apps (deploy + manage user workloads) 6

Spec-kit (spec-driven dev) 2

Spec-kit tools are MCP-protocol tools (managed by osmoda-mcpd), not osmoda-bridge api.registerTool() entries. The 91 count above refers only to the bridge surface.

Teaching - skill auto-generation 6

Channel routing (Telegram, WhatsApp, web) is handled by the gateway's binding map (agents.json · bindings[]), not a tool the agent calls. The agent's reply text on a Telegram or WhatsApp channel is delivered automatically by the gateway after the runtime emits a frame.

15b Multi-agent routing (osmoda + mobile)

Every spawn ships with two agent profiles, both with full tool access but different personalities and channels. The modular gateway routes per-channel via agents.json · bindings[]:

You can edit / add / remove agents at runtime through the dashboard's Engine tab (or the underlying /config/agents endpoints). Saving fires SIGHUP on the gateway; in-flight chat sessions keep their original snapshot, new sessions see the new config. Zero WS drops.

Each agent has its own workspace (/var/lib/osmoda/workspace-<agent-id>), its own memory dir, and its own credential binding. You can plug a different OAuth token or API key into each agent independently - useful when you want a personal Claude Pro driving the web agent and a metered API key driving the mobile agent.

16 Background Automation (Heartbeat)

osModa runs 6 default background routines via the osmoda-routines daemon. These run continuously between agent conversations, keeping the system healthy even when nobody is watching. All managed via routine_add, routine_list, and routine_trigger tools.

Routine definitions are stored in /var/lib/osmoda/routines/routines.json. Add custom routines via the routine_add tool - supports cron expressions, fixed intervals, and event-based triggers.

17 Safety & Emergency Commands

These commands execute directly - they bypass the AI and run immediately. They exist so the user always has a way out, even if the AI is broken or stuck. Never intercepted, delayed, or second-guessed.

Verify Audit Integrity

18 Messaging Channels & Remote Access

The agent is reachable via web chat (port 18789), Telegram, and WhatsApp. All channels share one conversation - one mind, not three separate bots. You can also set up remote access so you don't need SSH tunnels.

Telegram Setup

WhatsApp Setup

Remote Access: Cloudflare Tunnel (Quick)

Remote Access: Cloudflare Tunnel (Persistent)

Remote Access: Tailscale

19 Links & Resources

Everything you need to get started, contribute, or get help.

The complete source code is open. Every daemon, every tool, every skill, every NixOS module - all in the repo. Install.sh is the fastest way to go from a bare server to a fully autonomous AI infrastructure platform.