osModa

The first operating system built for AI agents.

Your server has an AI brain. It monitors, fixes, deploys, and explains — without you SSH-ing in.

10 Rust daemons. 92 structured tools. Modular agent runtime — swap between Claude Code (default), OpenClaw, and a cloud managed-agent driver without SSH or rebuilds. Persistent named chats — multiple distinct conversations per server, each with its own session, transcript, and auto-compaction, plus cross-chat and cross-channel awareness. Pre-indexed code knowledge graph (CodeGraph) so the agent navigates codebases — including the OS's own source — without grep-spraying. Tamper-proof audit ledger. Atomic rollback on every change. Post-quantum encrypted mesh between servers. Self-teaching skill engine that learns from agent behavior. All running on NixOS — the only Linux distro where every system state is a transaction.

v1.3.0 — Stable. The core (10 daemons, the modular gateway, the agentd contracts + audit ledger, claude-code as the main runtime) is stable and deployed on real servers. Per-component maturity is tracked honestly in STATUS.md; some advanced security hardening (live-verifying the tier-0 tool gate, fleet-wide trust) is still maturing — see the Safety Model.

Quickstart · Architecture · What It Does · Safety · API · Development

---

Who Is This For

• Solo developers who run their own servers — your server monitors itself, fixes problems at 3am, and tells you about it in the morning
• AI agent builders who need infrastructure — deploy agents with API key management, health monitoring, crash recovery, and an encrypted mesh between machines
• Small teams tired of on-call rotations — the AI handles routine ops, escalates what it can't fix, and keeps a tamper-proof audit trail of everything it does
• Anyone building an AI workforce — osModa is the computer your agents live in. Not a VPS you SSH into. A machine that manages itself.

Why This Exists

Every AI agent framework assumes your infrastructure is someone else's problem. They give you an agent that can think — but nowhere for it to live. So you SSH into a VPS, install things manually, pray nothing breaks at 3am, and when it does, you're the one waking up.

osModa is the other half: the machine itself is AI-native. 92 structured tools across 10 Rust daemons give the AI typed, auditable access to the entire operating system. No shell parsing. No regex. system_health returns structured JSON. Every mutation is SHA-256 hash-chained to a tamper-proof ledger. If a deploy breaks something, NixOS rolls back the entire system state atomically. If a service dies at 3am, the watcher detects it, the agent diagnoses root cause, SafeSwitch deploys a fix — with automatic rollback if health checks fail.

Why NixOS? Every system change is a transaction. Every state has a generation number. Rolling back is one command. This makes AI root access meaningfully safer than on any traditional Linux distribution. (NixOS rollback covers OS state — not data sent to external APIs or deleted user data. See Safety Model.)

What Happens in the First 5 Minutes

1. Install — curl | bash the installer (or add the flake to NixOS). The installer converts to NixOS, builds the 10 Rust daemons, installs osmoda-gateway + claude CLI + 92 MCP tools, starts everything.
2. First boot of the gateway — agents.json + encrypted credentials.json.enc are created in /var/lib/osmoda/config/. If you passed --credential or --api-key at install, they're already loaded; if not, the agent is disabled until you add one.
3. Open the dashboard (https://spawn.os.moda/#/servers/<your-id>/engine if hosted, or the local web UI) → Engine tab:
4. Credentials section — Add one. Paste your sk-ant-oat01-… (Claude Pro — cheapest for heavy use), sk-ant-api03-… (Console, pay-per-token), or any OpenAI/OpenRouter key. Click Test to verify with a 1-token ping.
5. Agents section — Pick runtime (Claude Code or OpenClaw), credential, and model for each agent (osmoda for web / full access, mobile for Telegram / concise). Save.
6. Switch to the Chat tab — start a conversation. The agent has all 92 tools, already knows your system, and will do an initial system_health check if you ask.
7. Try something real — "Install nginx and reverse-proxy port 3000" — it edits NixOS config, rebuilds via SafeSwitch with auto-rollback if health checks fail.

Want to switch runtimes later? Engine tab → change the Runtime dropdown → Save. SIGHUP fires; in-flight sessions keep running on their old driver; the next message uses the new one. Zero downtime.

Want to bring a new provider? Add a credential with the new provider/type; pick it on any agent. The installer doesn't need to re-run.

See the full Getting Started Guide for a detailed walkthrough with expected output at each step.

System Requirements

osModa is a full NixOS operating system, not an app. It replaces your OS entirely — like installing Arch or Fedora, not like running apt install. It will NOT work inside Docker, LXC, or any container runtime. Containers lack systemd, NixOS package management, and the kernel-level access that osModa's 10 daemons require.

Requirement	Details
Platform	Bare metal server, cloud VM (Hetzner, DigitalOcean, AWS), or QEMU/KVM virtual machine
Architecture	x86_64 or aarch64
RAM	2 GB minimum (4 GB recommended)
Disk	20 GB minimum
OS	Fresh Ubuntu 22.04+, Debian 12+, or existing NixOS (installer converts to NixOS)
NOT supported	Docker, LXC, WSL, OpenVZ, or any container-based environment

Quickstart

NixOS (flake) — recommended

# flake.nix
inputs.os-moda.url = "github:bolivian-peru/os-moda";

# configuration.nix
imports = [ os-moda.nixosModules.default ];
services.osmoda.enable = true;

sudo nixos-rebuild switch
curl -s --unix-socket /run/osmoda/agentd.sock http://localhost/health | jq

This is the primary install path. NixOS flakes give you reproducible builds, atomic upgrades, and instant rollback.

Any Linux Server — experimental

Warning: This converts your host OS to NixOS. It is a destructive, irreversible operation. Use on fresh/disposable servers only. Not recommended for production machines with existing workloads.

curl -fsSL https://raw.githubusercontent.com/bolivian-peru/os-moda/main/scripts/install.sh | sudo bash

Converts Ubuntu/Debian to NixOS, builds 10 Rust daemons from source, installs osmoda-gateway (the TypeScript gateway that drives both Claude Code and OpenClaw), installs the Claude Code CLI + 92 MCP tools, starts everything. Takes ~10 minutes on a CX22.

Supports OAuth tokens (Claude Pro / Max subscription) or Console API keys (pay-per-token). OpenAI, OpenRouter, and future providers plug in the same way.

Pre-configure the agent at install time

Instead of logging in and adding a credential afterwards, you can pass everything on the install command:

# Bring your Claude Pro subscription — flat $20/mo, near-unlimited usage
curl -fsSL https://raw.githubusercontent.com/bolivian-peru/os-moda/main/scripts/install.sh | sudo bash -s -- \
  --runtime claude-code \
  --default-model claude-opus-4-6 \
  --credential "My Claude Pro|anthropic|oauth|$(printf 'sk-ant-oat01-…' | base64)"

# Or a pay-per-token API key
curl -fsSL https://raw.githubusercontent.com/bolivian-peru/os-moda/main/scripts/install.sh | sudo bash -s -- \
  --runtime claude-code \
  --credential "Anthropic Console|anthropic|api_key|$(printf 'sk-ant-api03-…' | base64)"

# OpenClaw (BYOK / multi-provider engine, API key only — does not accept OAuth)
curl -fsSL https://raw.githubusercontent.com/bolivian-peru/os-moda/main/scripts/install.sh | sudo bash -s -- \
  --runtime openclaw \
  --credential "Anthropic|anthropic|api_key|$(printf 'sk-ant-api03-…' | base64)"

Flags:

Flag	Values	Notes
--runtime	claude-code (default) / openclaw	Initial per-agent runtime. Changeable later from the dashboard without re-running this.
--default-model	e.g. claude-opus-4-6, claude-sonnet-4-6	Initial default for the osmoda agent.
--credential	label\|provider\|type\|base64-secret	Repeatable. provider ∈ {anthropic, openai, openrouter, deepseek}; type ∈ {oauth, api_key}.
--api-key	raw or base64 key	Legacy one-liner; auto-promotes to a credential.

Every flag is optional — you can set all of this up from the dashboard afterwards.

Supported: Ubuntu 22.04+, Debian 12+, existing NixOS. x86_64 and aarch64.

Deploy to Hetzner/DigitalOcean/AWS

git clone https://github.com/bolivian-peru/os-moda.git && cd os-moda
./scripts/deploy-hetzner.sh <server-ip> [ssh-key-path]

Verify

# System health (structured JSON, not text parsing)
curl -s --unix-socket /run/osmoda/agentd.sock http://localhost/health | jq

# Audit ledger integrity
agentctl verify-ledger

---

Architecture

10 Rust daemons communicating over Unix sockets. No daemon exposes TCP to the internet (except mesh peer port 18800, encrypted). The AI reaches the system exclusively through structured MCP tool calls, never raw shell. One modular gateway (osmoda-gateway, TypeScript) drives pluggable runtime drivers: claude-code (default, supports OAuth subscriptions or API keys), openclaw (multi-provider BYOK CLI, API-key only — does not accept OAuth), and a prototype managed-agent driver (runs in Anthropic's cloud sandbox — for untrusted / scale-out workloads, not the tier-0 system agent). Each agent picks its own runtime + credential + model; switch at runtime via the dashboard — no rebuilds.

┌──────────────────────────────────────────────────────────────────────────────┐
│  User — Terminal / Web / Telegram / WhatsApp                                  │
├──────────────────────────────────────────────────────────────────────────────┤
│  osmoda-gateway (modular, TypeScript) — ONE systemd unit                      │
│  ├─ claude-code driver   `claude` CLI/session — DEFAULT (streams + chats)     │
│  ├─ openclaw driver      `openclaw`/session — BYOK multi-provider, API-key    │
│  ├─ managed-agent driver Anthropic cloud sandbox — untrusted/scale-out work   │
│  └─ future drivers       drop-in files under src/drivers/                     │
│                                                                               │
│  Multi-Agent Router (hot-reloadable via agents.json)                          │
│  ├─ osmoda agent (Opus)         92 tools · 20 skills · full access · web      │
│  └─ mobile agent (Sonnet)       full access · concise replies · Telegram/WA   │
│  osmoda-mcp-bridge              92 typed tools via MCP protocol               │
│  MCP Servers (stdio)            managed by osmoda-mcpd                        │
├────────┬────────┬────────┬──────────┬────────┬───────┬──────┬───────┬───────┤
│ agentd │ watch  │routine │ teachd   │ mesh   │ voice │ mcpd │ keyd  │egress │
│ System │ Safe   │ Cron + │ System   │ P2P    │ Local │ MCP  │Crypto │Domain │
│ bridge │ Switch │ event  │ learn    │Noise_XX│ STT/  │server│wallet │filter │
│ ledger │ roll-  │automate│ self-    │+ML-KEM │ TTS   │life- │ETH+   │proxy  │
│ memory │ back   │        │ optim    │hybrid  │       │cycle │SOL    │       │
├────────┴────────┴────────┴──────────┴────────┴───────┴──────┴───────┴───────┤
│  NixOS — atomic rebuilds · instant rollback · generations                     │
└──────────────────────────────────────────────────────────────────────────────┘

Trust Model (3 tiers)

TIER 0  osmoda-gateway + agentd  Root. Full system. This is the agent.
TIER 1  Approved apps            Sandboxed. Declared capabilities only.
TIER 2  Untrusted tools          Max isolation. No network. Minimal filesystem.

Modular runtime — switch engines without rebuilds

The gateway reads /var/lib/osmoda/config/agents.json at startup and on SIGHUP. Every chat session looks up its agent in that file, fetches the credential, and hands off to the right driver. Switching runtimes is a single PATCH:

curl -X PATCH -H "Authorization: Bearer $(cat /var/lib/osmoda/config/gateway-token)" \
  -H "Content-Type: application/json" \
  -d '{"runtime":"openclaw","model":"claude-opus-4-6"}' \
  http://127.0.0.1:18789/config/agents/osmoda
systemctl reload osmoda-gateway   # SIGHUP — in-flight sessions keep running

Or, from the spawn.os.moda dashboard, open a server → Engine tab → pick runtime / credential / model from dropdowns → Save. Same result; no SSH.

Credentials are encrypted at rest in credentials.json.enc (AES-256-GCM). Secrets never leave the g