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. 91 structured tools. Modular agent runtime — swap between Claude Code (default) and OpenClaw without SSH or rebuilds. 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.

Public Beta — This is a working system deployed on real servers, not a demo. Expect rough edges and rapid iteration. You're early.

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. 91 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:
   • 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.
   • Agents section — Pick runtime (Claude Code or OpenClaw), credential, and model for each agent (osmoda for web / full access, mobile for Telegram / concise). Save.
4. 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.
5. 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-co