os-moda

osModa

An operating system built for AI agents.

You operate the server by talking to it. The agent has typed, audited access to the whole system — health, config, deploys, crash recovery — running on NixOS, where every change is a transaction you can undo with one command.

10 Rust daemons and 92 structured tools behind a modular runtime you can swap between Claude Code (default), OpenClaw, and a cloud managed-agent driver without SSH or rebuilds. Persistent named chats, a pre-indexed code knowledge graph, an append-only hash-chained audit ledger, atomic rollback on every change, an encrypted mesh between servers. It's a broad system, and the breadth is uneven on purpose — the runtime, the agentd contracts, and the ledger are solid; the mesh, the crypto wallet, voice, and the skill engine are earlier and less proven. STATUS.md grades every component honestly.

What to expect. osModa is an ambitious solo project (~250 commits; 247 tests + a self-run pentest — not an external audit), not battle-tested infrastructure. The core is stable, but the safety model has a known gap it's actively closing: the default runtime's native shell/file tools aren't yet routed through the approval gate and audit ledger (the hook that fixes this is built and wire-tested, but not yet verified end-to-end on a live box — see the Safety Model). Run it on a fresh, disposable server — not a production machine you care about. Per-component maturity is tracked honestly in STATUS.md.

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

Who Is This For

• Solo developers who run their own servers — talk to your server instead of SSH-ing in. It watches itself, attempts routine fixes, and tells you what it did — with every OS-level change reversible on NixOS, so a wrong move is an undo, not an incident.
• AI agent builders who need infrastructure — a place for agents to actually live: credential management, health monitoring, crash recovery, and an encrypted mesh between machines.
• Small teams tired of on-call rotations — let the agent handle routine ops and escalate what it can't, with a hash-chained audit trail of its structured actions (read the Safety Model for exactly what that covers — and what it doesn't yet).
• Anyone experimenting with an AI workforce — osModa is a computer your agents operate, not a VPS you SSH into. It's research-grade today: great on a disposable box, not something to point at production yet.

Why This Exists

Most AI-agent frameworks give you an agent that can think but nowhere for it to live — so you still SSH into a VPS, install things by hand, and own every page yourself.

osModa is the other half: the machine itself is AI-native. 92 structured tools across 10 Rust daemons give the agent typed, auditable access to the OS — system_health returns JSON, not text you have to regex. Structured mutations are SHA-256 hash-chained to an append-only ledger. And because it's NixOS, a bad deploy rolls back the whole system state atomically. When a service falls over, a watcher can catch it and the agent can attempt a fix through SafeSwitch, with automatic rollback if the health checks fail. The honest framing: this is supervised autonomy with an undo button — not a promise the agent is always right. A confident-but-wrong fix is exactly why every OS change is reversible and every run should be budget-capped and reviewed.

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.

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-8 \
  --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:

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.