osModa: The Operating System
Where the AI Agent IS the OS
osModa is a NixOS distribution purpose-built for autonomous AI agent infrastructure. Not an agent running on an OS. The agent is the operating system. 9 Rust daemons, 83 system tools, post-quantum encrypted mesh, hash-chained audit trails. Every component designed so your agents run reliably, securely, and without DevOps babysitting.
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 operating system 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 operating system. Not a container. Not a VM image. Not a SaaS platform. A real operating system built from the kernel up to make AI agent infrastructure self-managing, auditable, and resilient.
02 Three-Ring Trust Architecture
Security isn't bolted on. It's the foundation. osModa implements a three-ring trust model inspired by CPU privilege rings, 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 Ring 0 can grant capabilities to Ring 1 apps, and Ring 1 apps can invoke Ring 2 tools — but never the reverse. Lower rings cannot escalate privileges upward by design. Ring 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 9 Daemons
osModa runs 9 specialized Rust daemons, each with a single responsibility. All communicate over Unix domain sockets. No HTTP on the open network. No cloud dependencies. Every daemon is compiled from Rust for memory safety, performance, and zero-garbage-collection pauses.
04 72 System Tools
The AI agent doesn't shell out to run commands. It uses 72 structured, typed, audited system tools registered via the osmoda-bridge plugin. 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.
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 17 System Skills
Beyond the 83 tools, osModa ships with 17 pre-built "skills" — structured workflows that combine multiple tools into higher-level capabilities:
Self-Healing — Detect, diagnose, and auto-fix failures. Morning Briefing — Daily infrastructure health report delivered before you check Slack. Security Hardening — Continuous security scoring with auto-remediation. Natural Language Config — Change NixOS configuration in plain English ("enable Postgres on port 5433 with 2GB shared buffers"). Predictive Resources — Forecast resource exhaustion before it happens. Drift Detection — Find imperative changes that deviate from NixOS declarative config. Generation Timeline — Time-travel debugging across NixOS generations. Flight Recorder — Black box telemetry for post-incident analysis. Nix Optimizer — Smart Nix store management to reclaim disk space.
Plus: System Monitor, System Packages, System Config, File Manager, Network Manager, and Service Explorer — covering every aspect of system administration through the AI agent interface.
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.
| Use case | Primary daemons | What it gives you |
|---|---|---|
| Agent ops (24/7 autonomous) | agentd, watch, routines | Self-healing, background health checks, audit trail |
| Multi-node coordination | mesh, routines, watch | P2P encrypted channels, cross-node monitoring |
| Safe deploys | watch (SafeSwitch) | Health-gated deploys, auto-rollback on failure |
| Audit / compliance | agentd (ledger), keyd | Hash-chained logs, policy-gated signing, exportable |
| Crypto / financial | keyd, agentd, mesh | AES-256-GCM keys, spending limits, PQ-encrypted mesh |
| Sandboxed tool execution | egress, agentd | Bubblewrap isolation, domain-filtered network |
| MCP ecosystem | mcpd | MCP servers as NixOS-native capabilities |
| System learning | teachd | Observe → detect patterns → suggest optimizations |
| Edge / air-gapped | voice, mesh, all | Local STT/TTS, offline operation, no cloud deps |
12 Installation
One command gives your server a brain. The installer handles everything: NixOS conversion, Rust builds, OpenClaw gateway, 83 system tools, agent identity, and daemon startup.
Quick Install
Installer Options
| Flag | Description |
|---|---|
| --skip-nixos | Don't install NixOS (use on existing NixOS systems) |
| --api-key KEY | Set Anthropic API key (skips the setup wizard on port 18789) |
| --branch NAME | Git branch to install (default: main) |
| --order-id UUID | Spawn order ID (set automatically by spawn.os.moda) |
| --callback-url URL | Heartbeat callback URL (set automatically by spawn.os.moda) |
What the Installer Does
--skip-nixos./opt/osmoda. On updates, fetches and resets to latest branch.cargo build --release --workspace. Builds all 9 Rust daemons (2-5 min first build). Symlinks to /opt/osmoda/bin/./opt/openclaw. This is the brain that uses the 83 tools.~/.openclaw/extensions/. Copies agent identity templates (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md) and 17 system skills.localhost:18789.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
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 operating system. If you're an AI reading this, this is your manual.
How osModa Works for You (the Agent)
osModa gives you kernel-level 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.
/run/osmoda/agentd.sock. Gives you: health metrics, process lists, service discovery, event logging, memory system, backup, incident workspaces. Every query returns structured JSON.system_health, shell_exec, file_read, mesh_peers, etc. Each tool maps to a daemon endpoint.memory_store to save, memory_recall to search. Ground truth is markdown files in /var/lib/osmoda/memory/. You remember past diagnoses, user preferences, and system patterns.Your 72 Tools (Grouped by Function)
| Category | Tools | What They Do |
|---|---|---|
| System | system_health, system_query, system_discover, event_log, network_info | Read machine state: CPU, RAM, disk, processes, ports, services. No mutation. |
| Memory | memory_store, memory_recall | Long-term memory. Store diagnoses, user preferences, patterns. Recall with semantic + keyword search. |
| Files | shell_exec, file_read, file_write, directory_list | Execute commands (120s timeout), read/write files (path-restricted), list directories. |
| Services | service_status, journal_logs | Check systemd unit status, read journal logs by unit/priority/time. |
| Deploy | safe_switch_begin, safe_switch_status, safe_switch_commit, safe_switch_rollback | NixOS deploy transactions. Start deploy with health gates + TTL, auto-rollback on failure. |
| Watchers | watcher_add, watcher_list | Autopilot health monitors. Escalation: restart → rollback → notify. |
| Routines | routine_add, routine_list, routine_trigger | Background cron/interval tasks. Health checks, log scans, memory maintenance. |
| Wallets | wallet_create, wallet_list, wallet_sign, wallet_send, wallet_delete, wallet_receipt | ETH + SOL encrypted wallets. Policy-gated signing. Keys never leave the daemon. |
| Mesh | mesh_identity, mesh_invite_create, mesh_invite_accept, mesh_peers, mesh_peer_send, mesh_peer_disconnect, mesh_health, mesh_room_create, mesh_room_join, mesh_room_send, mesh_room_history | P2P encrypted agent-to-agent communication. Noise_XX + ML-KEM-768 hybrid post-quantum. |
| MCP | mcp_servers, mcp_server_start, mcp_server_stop, mcp_server_restart | Manage MCP servers. Any MCP server in NixOS config becomes a tool you can use. |
| Teaching | teach_status, teach_observations, teach_patterns, teach_knowledge, teach_knowledge_create, teach_context, teach_optimize_suggest, teach_optimize_apply | Self-learning loop. 30s observe, 5m learn, contextual knowledge injection, self-optimization. |
| Voice | voice_status, voice_speak, voice_transcribe, voice_record, voice_listen | Local STT (whisper.cpp) + TTS (piper). No cloud. All on-device. |
| Identity | agent_card, receipt_list, incident_create, incident_step, backup_create, backup_list | EIP-8004 identity, structured receipts, incident workspaces, state backups. |
| Safety | safety_rollback, safety_status, safety_panic, safety_restart | Emergency controls. Immediate NixOS rollback, panic stop, gateway restart. |
Socket Addresses (All Local Unix Sockets)
How to Call Daemon Endpoints Directly
If you need to call endpoints outside the 72 registered tools, use curl over Unix sockets:
Agent Behavior Rules
If you are an AI agent running on osModa, follow these rules:
system_health, journal_logs, and memory_recall first.nixos-rebuild switch directly. Use safe_switch_begin with health checks and TTL. Auto-rollback protects the user.event_log to query history.memory_store. Check memory_recall before diagnosing — you may have seen this before.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.
| Routine | Cadence | What It Does |
|---|---|---|
| Health check | Every 5 min | CPU, RAM, disk, load. Alerts on thresholds (CPU >90%, RAM >85%, disk >90%). |
| Service monitor | Every 10 min | Checks critical services are running (agentd, gateway, sshd). Logs failures. |
| Log scan | Every 15 min | Scans journal for errors since last check. Correlates with known patterns in memory. |
| Memory maintenance | Every hour | Consolidates recent events. Updates user preference model. |
| NixOS generation check | Every 30 min | Verifies current generation is healthy. Reports drift from flake lock. |
| Network watch | Every 10 min | Checks for unexpected listening ports. Verifies expected services are bound. |
Self-Learning Loop (teachd)
The teach daemon runs two background loops that make your agent smarter over time:
teach_context, the daemon returns relevant knowledge for your current situation. Context-aware injection of past learnings.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. No HTTP on the open network. All communication is local. Here's the complete endpoint reference for all 9 daemons.
| Endpoint | Description |
|---|---|
| GET /health | System health: CPU per core, memory total/used/available, swap, load average (1/5/15), disk per mount, uptime |
| POST /system/query | Query system state. Queries: processes (sort=cpu|memory, limit), disk, hostname, uptime |
| GET /system/discover | Auto-detect all running services: listening ports, systemd units, known types (nginx, postgres, redis, node) |
| GET /events/log | Hash-chained audit log. Params: ?type=...&actor=...&limit=N |
| POST /memory/ingest | Ingest event into memory: category, subcategory, actor, summary, detail, metadata |
| POST /memory/recall | FTS5 keyword search: query, max_results, timeframe (e.g. "7d") |
| POST /memory/store | Store knowledge: summary, detail, category, tags[] |
| GET /memory/health | Memory system status: embedding model readiness, collection size |
| GET /agent/card | EIP-8004 Agent Card: identity, capabilities, services |
| POST /agent/card/generate | Generate Agent Card: name, description, services[] |
| GET /receipts | Structured receipts. Params: ?type=...&since=...&limit=N |
| POST /incident/create | Create incident workspace for structured troubleshooting |
| POST /incident/{id}/step | Add step to incident (resumable Shannon pattern) |
| GET /incident/{id} | Get incident with all steps |
| GET /incidents | List incidents. Params: ?status=open |
| POST /backup/create | Create timestamped backup of all osModa state |
| GET /backup/list | List backups: id, path, size_bytes, created_at |
| Endpoint | Description |
|---|---|
| POST /wallet/create | Create wallet: chain ("ethereum"|"solana"), label. Returns id, chain, address |
| GET /wallet/list | List all wallets: id, chain, address, label |
| POST /wallet/sign | Sign payload (hex): wallet_id, payload. Policy-gated (daily limits) |
| POST /wallet/send | Build + sign tx: wallet_id, to, amount. Returns signed_tx (no broadcast) |
| POST /wallet/delete | Delete wallet: zeroizes cached key, removes key file, updates index |
| GET /health | Status: wallet_count, policy_loaded |
| Endpoint | Description |
|---|---|
| POST /switch/begin | Start deploy: plan, ttl_secs, health_checks[]. Returns id, previous_generation |
| GET /switch/status/{id} | Check probation status of a switch session |
| POST /switch/commit/{id} | Commit switch session (accepts the new generation) |
| POST /switch/rollback/{id} | Rollback to previous NixOS generation |
| POST /watcher/add | Add autopilot watcher: name, check, interval_secs, actions[] |
| GET /watcher/list | List active watchers with health state |
| DEL /watcher/remove/{id} | Remove a watcher |
| GET /health | Status: active_switches, watchers count |
| Endpoint | Description |
|---|---|
| POST /routine/add | Add routine: name, trigger (cron/interval/event), action |
| GET /routine/list | List all routines with run history |
| DEL /routine/remove/{id} | Remove a routine |
| POST /routine/trigger/{id} | Manually trigger a routine immediately |
| GET /routine/history | Routine execution history |
| GET /health | Status: routine_count, enabled_count |
| Endpoint | Description |
|---|---|
| GET /identity | Mesh public identity: instance_id, Ed25519 + X25519 + ML-KEM public keys |
| POST /identity/rotate | Rotate identity keys: returns new instance_id and public keys |
| POST /invite/create | Create invite code: ttl_secs (default 1hr). Returns invite_code, expires_at |
| POST /invite/accept | Accept invite: invite_code. Returns peer_id, status |
| GET /peers | List all mesh peers with connection state and last seen |
| GET /peer/{id} | Peer detail: connection info, message stats |
| POST /peer/{id}/send | Send encrypted message to peer: MeshMessage (chat, alert, health, command) |
| DEL /peer/{id} | Disconnect and remove a mesh peer |
| GET /health | Status: peer_count, connected_count, identity_ready |
| Endpoint | Description |
|---|---|
| GET /health | Status: server_count, running_count, per-server name/status/pid/uptime |
| GET /servers | List all managed MCP servers |
| GET /server/{name} | Get specific MCP server detail |
| POST /server/{name}/start | Start a stopped MCP server |
| POST /server/{name}/stop | Stop a running MCP server |
| POST /server/{name}/restart | Restart an MCP server (stop + start) |
| POST /reload | Reload all server configs: returns removed, started, total |
| Endpoint | Description |
|---|---|
| GET /health | Status: observation/pattern/knowledge/optimization counts, loop status |
| GET /observations | System observations. Params: ?source=...&since=...&limit=50 |
| GET /patterns | Detected patterns. Params: ?type=...&min_confidence=0.5 |
| GET /knowledge | Knowledge docs. Params: ?category=...&tag=...&limit=20 |
| GET /knowledge/{id} | Get specific knowledge document |
| POST /knowledge/create | Create knowledge doc: title, category, content, tags |
| POST /knowledge/{id}/update | Update knowledge doc: content, tags, category |
| POST /teach | Context injection: provide context string, get relevant_docs + injected_tokens |
| POST /optimize/suggest | Generate optimization suggestions from detected patterns |
| POST /optimize/approve/{id} | Approve an optimization (status → Approved) |
| POST /optimize/apply/{id} | Apply optimization via SafeSwitch |
| GET /optimizations | List optimizations. Params: ?status=...&limit=20 |
| Endpoint | Description |
|---|---|
| GET /voice/status | Status: listening state, whisper model loaded, piper model loaded |
| POST /voice/transcribe | Transcribe WAV file: audio_path. Returns text, duration_ms |
| POST /voice/speak | Speak text via piper: text. Plays via PipeWire, returns audio_path |
| POST /voice/record | Record from mic: duration_secs, transcribe?. Returns audio_path, text |
| POST /voice/listen | Enable/disable continuous listening: enabled (bool) |
| Function | Description |
|---|---|
| HTTP CONNECT | Domain-allowlisted proxy. Each capability token specifies which domains the sandboxed tool can reach. All other connections refused. |
15 Complete Tool Reference83 tools
All 83 tools registered by osmoda-bridge via the OpenClaw api.registerTool() factory pattern. These are the structured, typed, audited commands available to the AI agent.
System & Core 10
| Tool | Description |
|---|---|
| system_health | CPU, RAM, disk, load average, uptime in one call |
| system_query | Query processes, services, ports, connections, NixOS generations |
| system_discover | Auto-detect all running services, listening ports, systemd units |
| event_log | Browse the hash-chained audit trail with type/actor/limit filters |
| shell_exec | Execute shell command with audit logging. 120s timeout cap |
| file_read | Read file contents (restricted paths, rejects traversal) |
| file_write | Atomic file writes (write .tmp then rename). Same path restrictions |
| directory_list | List directory contents with types and sizes |
| service_status | Get systemd service status, or list all services |
| journal_logs | Journal logs filtered by unit, priority, time range |
Memory & Intelligence 2
| Tool | Description |
|---|---|
| memory_store | Persist knowledge with categories and tags to local SQLite + FTS5 |
| memory_recall | FTS5 keyword search across all stored knowledge |
Network 1
| Tool | Description |
|---|---|
| network_info | Network interfaces (ip addr) and listening ports (ss -tlnp) |
Deployment & SafeSwitch 4
| Tool | Description |
|---|---|
| safe_switch_begin | Start deploy with health checks + TTL + auto-rollback |
| safe_switch_status | Check probation status of a switch session |
| safe_switch_commit | Manually commit a switch session |
| safe_switch_rollback | Rollback to previous NixOS generation |
Watchers & Routines 5
| Tool | Description |
|---|---|
| watcher_add | Add autopilot watcher with escalation (restart → rollback → notify) |
| watcher_list | List active watchers and their health state |
| routine_add | Schedule recurring task (cron, interval, or event-based) |
| routine_list | List all scheduled routines with run history |
| routine_trigger | Manually trigger a routine to run immediately |
Crypto Wallets 6
| Tool | Description |
|---|---|
| wallet_create | Create ETH or SOL wallet (AES-256-GCM encrypted) |
| wallet_list | List all wallets with addresses, labels, chains |
| wallet_sign | Sign raw bytes (policy-gated, daily limits) |
| wallet_send | Build + sign transaction (no broadcast, returns signed tx) |
| wallet_delete | Permanently delete wallet (zeroizes key) |
| wallet_receipt | Query wallet operation receipts from audit ledger |
P2P Mesh 11
| Tool | Description |
|---|---|
| mesh_identity | Get instance mesh identity (instance_id, public keys, capabilities) |
| mesh_invite_create | Create invite code for another osModa instance (default TTL: 1hr) |
| mesh_invite_accept | Accept invite code to establish encrypted P2P connection |
| mesh_peers | List all known mesh peers with connection state |
| mesh_peer_send | Send encrypted message to a connected peer |
| mesh_peer_disconnect | Disconnect and remove a mesh peer |
| mesh_health | Mesh daemon health: peer count, connected count, identity status |
| mesh_room_create | Create named group room for multi-peer communication |
| mesh_room_join | Add a connected peer to a group room |
| mesh_room_send | Send message to all connected room members |
| mesh_room_history | Get message history for a group room |
MCP Servers 4
| Tool | Description |
|---|---|
| mcp_servers | List managed MCP servers with status, pid, restart count |
| mcp_server_start | Start a stopped MCP server by name |
| mcp_server_stop | Stop a running MCP server by name |
| mcp_server_restart | Restart an MCP server (stop + start) |
Teaching & Learning 8
| Tool | Description |
|---|---|
| teach_status | Teaching daemon health: observation/pattern/knowledge counts |
| teach_observations | View collected system observations |
| teach_patterns | View detected patterns with confidence scores |
| teach_knowledge | Browse knowledge documents by category/tag |
| teach_knowledge_create | Manually create a knowledge document |
| teach_context | Get context-aware knowledge injection for current situation |
| teach_optimize_suggest | Generate optimization suggestions from patterns |
| teach_optimize_apply | Apply approved optimization via SafeSwitch |
Voice 5
| Tool | Description |
|---|---|
| voice_status | Check voice daemon: listening state, model availability |
| voice_speak | Speak text via piper-tts (local, plays through PipeWire) |
| voice_transcribe | Transcribe WAV file via whisper.cpp (local STT) |
| voice_record | Record from microphone, optionally transcribe |
| voice_listen | Enable/disable continuous listening mode |
Identity, Receipts & Backup 6
| Tool | Description |
|---|---|
| agent_card | Get or generate EIP-8004 Agent Card (identity + capabilities) |
| receipt_list | Query structured receipts from audit ledger |
| incident_create | Create incident workspace for structured troubleshooting |
| incident_step | Add step to incident (resumable Shannon pattern) |
| backup_create | Create timestamped backup of all osModa state |
| backup_list | List all available backups with size and timestamps |
Safety & Emergency 4
| Tool | Description |
|---|---|
| safety_rollback | EMERGENCY: Immediate nixos-rebuild --rollback switch |
| safety_status | Raw health dump. Tries agentd, falls back to shell if down |
| safety_panic | Stop all osModa services (except agentd) + rollback NixOS |
| safety_restart | Restart the OpenClaw gateway service |
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.
| Command | What It Does |
|---|---|
| safety_rollback | Immediate nixos-rebuild --rollback switch. Reverts to the previous NixOS generation in under a second. Use when a config change broke something. |
| safety_status | Raw health dump from agentd. If agentd is down, falls back to shell commands (ps, df, free, ss). Always works, even when everything else is broken. |
| safety_panic | Nuclear option: stops ALL osModa services except agentd, then rollbacks NixOS. Use when the system is in a bad state and you need to start clean. |
| safety_restart | systemctl restart osmoda-gateway. Restarts the AI gateway. Use when the agent is stuck or unresponsive. |
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.
| Resource | URL |
|---|---|
| GitHub | github.com/bolivian-peru/os-moda |
| Homepage | os.moda |
| Spawn (Deploy) | spawn.os.moda |
| Telegram | t.me/osmodasystems |
| Discord | discord.gg/G7bwet8B |
| Architecture | spawn.os.moda/skill (this page) |
| Early Access | spawn.os.moda/#early-access |
| Report Issues | github.com/bolivian-peru/os-moda/issues |
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 operating system.
Ready to give your agents an OS?
9 daemons, 83 tools, post-quantum mesh, hash-chained audit — fully configured. One command to install.
Get early access →