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: