Content
<div align="center">
# 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](docs/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](#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](docs/STATUS.md).
[](LICENSE)
[]()
[]()
[]()
[](https://www.rust-lang.org/)
[](https://nixos.org/)
[]()
[]()
[Quickstart](#quickstart) · [Architecture](#architecture) · [What It Does](#what-it-does) · [Safety](#safety-model) · [API](#api-reference) · [Development](#development)
[](https://t.me/osmodasystems)
[](https://discord.gg/G7bwet8B)
[](https://spawn.os.moda)
</div>
---
## 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](#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](#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](docs/GETTING-STARTED.md) 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
```nix
# flake.nix
inputs.os-moda.url = "github:bolivian-peru/os-moda";
# configuration.nix
imports = [ os-moda.nixosModules.default ];
services.osmoda.enable = true;
```
```bash
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.
```bash
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:
```bash
# 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:
| 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-8` (default), `claude-fable-5`, `claude-mythos-5`, `claude-sonnet-4-6` | Initial default for the osmoda agent. `claude-fable-5` is Anthropic's most capable model; `claude-mythos-5` is the Project Glasswing variant. |
| `--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
```bash
git clone https://github.com/bolivian-peru/os-moda.git && cd os-moda
./scripts/deploy-hetzner.sh <server-ip> [ssh-key-path]
```
### Verify
```bash
# 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:
```bash
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-8"}' \
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 gateway; the REST API returns a preview prefix only. `POST /config/credentials/:id/test` does a 1-token probe against the provider so you can validate before assigning.
The agent is tier 0 by design. It's not a chatbot with sudo — it's a system service with structured access to everything, constrained by NixOS atomicity and its own audit ledger, not by permission denials. Lower tiers cannot escalate privileges upward by design. Tier 0 remains the trusted computing base and must be governed by approval policies, spending limits, and audit review.
### Autonomy — runs itself, on a budget
The agent doesn't only answer when spoken to. Give it a **goal and a cadence** and it works on its own: `POST /loops` starts a loop (interval + iteration cap + stop-sentinel) that fires a real turn each tick toward the goal, persists across restarts, and pauses itself after repeated errors. `POST /agent/turn` injects a single turn — the surface cron/routines/external triggers use. Each loop is a named chat, so its progress shows up in the dashboard like any other conversation.
What makes unattended operation safe is a **per-agent daily spend kill-switch**: set `dailyTokenCap` / `dailyUsdCap` and every turn — interactive or autonomous — is checked *before* the model is invoked. Over the cap it's refused with a typed `spend_cap_exceeded`; the meter resets at 00:00 UTC and alerts at 80% / 100%. An unattended loop can never outrun its budget.
---
## Safety Model
The #1 question: "Why does the AI have root access?" Because it IS the system interface — the same way systemd has root access. The safety model is not about restricting the agent, but about making its actions auditable, reversible, and bounded.
### What protects you today
| Protection | How it works |
|-----------|-------------|
| **NixOS atomic rollback** | Every system change is a generation. Bad config? One command reverts the entire OS state. |
| **Hash-chained audit ledger** | Every action creates a SHA-256-chained event in SQLite. Tamper-evident. Verifiable offline with `agentctl verify-ledger`. 321+ events verified on live server with zero broken links. |
| **SafeSwitch deploys** | Changes go through a probation period with health checks. If any check fails, automatic rollback to the previous generation. |
| **Command blocklist** | 17 dangerous command patterns blocked in the structured `shell_exec` tool (rm -rf, dd, mkfs, etc.). Expanded and pentest-verified. *(Scope: `shell_exec`. The default agent's native `Bash` tool is not yet routed through it — see [below](#what-the-default-agent-bypasses-today).)* |
| **Rate limiting** | All public endpoints enforce rate limits (shell_exec: 30/60s, mesh TCP: 5/60s). |
| **Socket permissions** | All Unix sockets are 0600 (owner-only). All 10 daemons enforce `umask(0o077)` at startup. |
| **Approval gates** | Destructive operations *through the structured tools* require explicit approval via `approval_request`/`approval_approve`. Time-limited with auto-expiry. *(Not yet enforced on the default agent's native `Bash`/`Write`/`Edit` — see [below](#what-the-default-agent-bypasses-today).)* |
| **Fleet coordination** | Multi-server changes go through quorum voting via `fleet_propose`/`fleet_vote` before applying. |
| **Safety commands** | `safety_rollback`, `safety_panic`, `safety_status`, `safety_restart` bypass the AI entirely — the user always has an escape hatch. |
| **Pentest verified** | Full automated pentest: injection attacks (SQL, path traversal, shell), payload bombs, error hardening, stress testing (700/700 concurrent health checks). All pass. |
| **Session persistence** | The agent's claude-code session id is disk-persisted (`/var/lib/osmoda/state/sessions.json`, mode 0600). Restart the gateway, the box, even reinstall — the agent remembers the conversation. Sessions are runtime-tagged so swapping `claude-code` ↔ `openclaw` never resumes a foreign runtime's session id. |
| **Driver health checks** | Every runtime driver implements `healthCheck()`. The gateway probes the binary's CLI shape before allowing a runtime swap. Unhealthy drivers return `422 driver_unavailable` with the exact error + remediation rather than letting chat silently fail later. Caught the 2026-05-14 OpenClaw `run`→`agent` CLI rename within the same hour. |
| **Process-group abort** | The Stop button kills the entire subprocess tree (`detached: true` spawn + group-signal + 2 s SIGKILL escalation), not just the runtime leader. Bash spawned by the agent, file I/O, child processes — all stopped at once. |
| **Dual-signal wedge detector** | A server is flagged "wedged" only when both `last_heartbeat` AND `agent_last_frame_at` are stale ≥5 min. Eliminated the false-positive class where the heartbeat sender was broken but the agent was happily answering chat. |
### What the default agent bypasses today
**Be precise about what is and isn't enforced.** The blocklist, approval gate, and audit ledger above sit in front of the structured MCP tools (`shell_exec`, `file_write`, `safe_switch_*`, …). But the default `claude-code` runtime also gives the agent the **native `Bash`, `Write`, and `Edit` tools**, which execute directly and **currently bypass the blocklist, the approval gate, and the ledger.** So today, governance of the tier-0 agent rests on NixOS atomic rollback, spending limits, and audit review — *not* on per-action approval of everything the agent does.
A **PreToolUse enforcement hook** that routes the native tools through agentd's approval + hash-chained ledger is now **implemented** (ships via `install.sh` + the NixOS module): native `Bash` is checked against agentd's ApprovalGate and every gated decision is appended to the ledger; writes to guardrail/secret paths require approval. The hook↔agentd **wire contract is integration-tested end-to-end** — the hook runs as a real subprocess against a stub agentd over a Unix socket, covering allow, deny-with-reason, secret-path self-protect, the catastrophic-command backstop when agentd is unreachable, and fail-open on malformed input — alongside the gateway + agentd unit suites. **What's still unverified is that it fires in front of a real `claude-code` Bash call on a running box.** Until that's confirmed, keep osModa on disposable/dedicated boxes, set provider spend limits, review the ledger, and treat "every mutation is approval-gated" as the *goal*, not yet a proven guarantee. See [SECURITY.md](docs/SECURITY.md) for what it does and how to verify.
### What NixOS rollback covers — and what it doesn't
**Covered:** OS configuration, package state, service definitions, firewall rules, system generations. Any bad config change can be atomically reverted.
**NOT covered:** Data already sent to external APIs, signed crypto transactions, deleted user data, exposed secrets, or side effects on remote systems. Tier 0 access means the agent can do anything the system can do — the safety model relies on structured tools, audit trails, and NixOS atomicity, not on restricting the agent's access.
### What's planned but not yet complete
- **Tier-0 tool-gate enforcement (PreToolUse hook)** — *implemented; wire contract integration-tested; on-box verification pending.* Routes the default agent's native `Bash`/`Write`/`Edit` through agentd's approval + audit ledger so the blocklist and approval gate cover the path the agent actually uses (not just the structured `shell_exec`/`file_write` tools). Ships in `install.sh` + the NixOS module; see [SECURITY.md](docs/SECURITY.md).
- **Tier 1/Tier 2 sandbox enforcement** — the trust tier model is designed and `sandbox_exec` exists, but bubblewrap isolation isn't fully wired for all third-party tools yet.
- **Capability token auth** — `capability_mint` can create time-limited tokens, but socket authentication is still primarily file-permissions based.
- **External security audit** — mesh crypto uses standard primitives (Noise_XX, ML-KEM-768) but hasn't had independent review.
- **Semantic memory** — `memory/recall` uses FTS5 BM25 keyword search. Semantic vector search (usearch + fastembed) is designed but not yet wired.
### Audit Ledger
Every mutation creates a hash-chained event in SQLite:
```
hash = SHA-256(id | ts | type | actor | payload | prev_hash)
```
Append-only. Tamper-evident. Any single modification invalidates the chain. Verifiable offline with `agentctl verify-ledger`.
---
## What It Does
### Core: System Management
| Daemon | What it does | Key feature |
|--------|-------------|-------------|
| **agentd** | System bridge: processes, services, network, filesystem, NixOS config, sysctl parameters. Hash-chained audit ledger. FTS5 memory search. | The structured interface between AI and system |
| **osmoda-watch** | SafeSwitch: deploy with a timer, health checks, and automatic rollback if anything fails. Autopilot watchers with escalation (restart -> rollback -> notify). | Blue-green deploys with automatic undo |
| **osmoda-routines** | Background cron/event/webhook automation. Runs between conversations. Health checks, log scans, service monitors. | Agent actions that persist when nobody's chatting |
| **osmoda-teachd** | OBSERVE loop (30s) collects metrics. LEARN loop (5m) detects patterns. SKILLGEN loop (6h) detects repeated agent tool sequences and auto-generates SKILL.md files. TEACH API injects knowledge. Optimizer suggests fixes. | The OS learns from its own behavior and teaches itself new skills |
### Communication
| Daemon | What it does | Key feature |
|--------|-------------|-------------|
| **osmoda-mesh** | P2P encrypted agent-to-agent communication. Noise_XX + ML-KEM-768 hybrid post-quantum. Invite-based pairing. | Servers talk to each other, end-to-end encrypted |
| **osmoda-voice** | Local speech-to-text (whisper.cpp) + text-to-speech (piper). All processing on-device. No cloud APIs. | Fully local voice, zero cloud dependency |
### Infrastructure
| Daemon | What it does | Key feature |
|--------|-------------|-------------|
| **osmoda-mcpd** | MCP server lifecycle manager. Starts, monitors, restarts MCP servers from NixOS config. | Any MCP server becomes an OS capability |
| **osmoda-egress** | HTTP CONNECT proxy with domain allowlist per capability token. | Sandboxed tools can't phone home |
### Optional: Crypto Wallet
| Daemon | What it does | Key feature |
|--------|-------------|-------------|
| **osmoda-keyd** | Crypto wallet daemon for AI agent workloads that need signing. AES-256-GCM encrypted keys, ETH + SOL. Policy-gated (daily limits, address allowlists). | Network-isolated (`PrivateNetwork=true`) — keys never leave the daemon |
> **Note:** `wallet/send` signs an intent string, not a fully-encoded blockchain transaction. Broadcasting requires external tooling. See [STATUS.md](docs/STATUS.md) for details.
### 92 Bridge Tools
The AI doesn't shell out. It calls typed tools that return structured JSON:
```
system_health system_query system_discover
event_log memory_store memory_recall
shell_exec file_read file_write
directory_list service_status journal_logs
network_info safe_switch_begin safe_switch_list
safe_switch_status safe_switch_commit safe_switch_rollback
watcher_add watcher_list routine_add
routine_list routine_trigger agent_card
receipt_list incident_create incident_step
voice_status voice_speak voice_transcribe
voice_record voice_listen backup_create
backup_list 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
mcp_servers mcp_server_start mcp_server_stop
mcp_server_restart teach_status teach_observations
teach_patterns teach_knowledge teach_knowledge_create
teach_context teach_optimize_suggest teach_optimize_apply
teach_skill_candidates teach_skill_generate teach_skill_promote
teach_observe_action teach_skill_execution teach_skill_detect
approval_request approval_pending approval_approve
approval_check sandbox_exec capability_mint
fleet_propose fleet_status fleet_vote
fleet_rollback app_deploy app_list
app_logs app_stop app_restart
app_remove wallet_create wallet_list
wallet_sign wallet_send wallet_delete
wallet_receipt wallet_build_tx safety_rollback
safety_status safety_panic safety_restart
```
### 20 System Skills
Predefined behavioral patterns the agent can follow:
**Self-healing** — detect failure, diagnose root cause, fix automatically, log receipt.
**Morning briefing** — daily infrastructure health report.
**Security hardening** — continuous CIS benchmark scoring with auto-remediation.
**Natural language config** — "enable nginx with SSL for example.com" becomes NixOS config.
**Predictive resources** — forecast disk/RAM/CPU exhaustion before it happens.
**Drift detection** — find imperative changes that diverge from NixOS declarations.
**Generation timeline** — correlate "what changed" with "when things broke" across NixOS generations.
**Flight recorder** — black box telemetry for post-incident analysis.
**Nix optimizer** — smart garbage collection and store deduplication.
**App deployer** — deploy and manage user applications as systemd services with resource limits and boot persistence.
**Deploy AI agent** — deploy AI agent workloads (LangChain, CrewAI, AutoGen, custom) with GPU checks, API key management, and health monitoring.
**Swarm predict** — multi-perspective risk analysis using 6-8 expert persona debate before infrastructure changes, with SafeSwitch integration.
**Scaled swarm predict** — large-scale social simulation with 50-200 demographically diverse personas on simulated Twitter/Reddit boards for outcome prediction.
**Spec-driven development** — the github/spec-kit workflow (`specify init` / plan / implement) wired into the agent and backed by CodeGraph.
Plus: system monitor, package manager, config editor, file manager, network manager, service explorer.
### Remote Access
Access your server from anywhere — no SSH tunnels required:
```nix
# Cloudflare Tunnel (quick tunnel — no account needed)
services.osmoda.remoteAccess.cloudflare.enable = true;
# Or with your own tunnel
services.osmoda.remoteAccess.cloudflare.credentialFile = "/var/lib/osmoda/secrets/cf-creds.json";
services.osmoda.remoteAccess.cloudflare.tunnelId = "your-tunnel-id";
# Tailscale VPN
services.osmoda.remoteAccess.tailscale.enable = true;
services.osmoda.remoteAccess.tailscale.authKeyFile = "/var/lib/osmoda/secrets/tailscale-key";
```
### Safety Commands
Emergency controls that bypass the AI entirely:
| Command | Action |
|---------|--------|
| `safety_rollback` | Immediate NixOS rollback to previous generation |
| `safety_status` | Raw health dump (shell fallback if agentd is down) |
| `safety_panic` | Stop all services + rollback NixOS |
| `safety_restart` | Restart the AI gateway |
### Messaging Channels
Talk to your server from Telegram or WhatsApp:
```nix
services.osmoda.channels.telegram.enable = true;
services.osmoda.channels.telegram.botTokenFile = "/var/lib/osmoda/secrets/telegram-bot-token";
```
---
## API Reference
### agentd (`/run/osmoda/agentd.sock`)
```
GET /health System metrics (CPU, RAM, disk, load, uptime)
POST /system/query Run structured system queries
GET /system/discover Discover all running services, ports, systemd units
GET /events/log Hash-chained audit event log
POST /memory/ingest Store event in memory
POST /memory/recall FTS5 full-text search over system history (BM25-ranked)
POST /memory/store Store named memory with tags
GET /agent/card EIP-8004 Agent Card
POST /backup/create Create system backup
GET /backup/list List available backups
POST /incident/create Open incident workspace
POST /incident/{id}/step Add step to incident
GET /receipts Audit receipts
```
### osmoda-watch (`/run/osmoda/watch.sock`)
```
POST /switch/begin Start SafeSwitch deploy with TTL + health checks
GET /switch/list List all switch sessions (recent first)
POST /switch/commit/{id} Commit (health passed)
POST /switch/rollback/{id} Rollback (health failed or manual)
POST /watcher/add Add autopilot health watcher
```
### osmoda-routines (`/run/osmoda/routines.sock`)
```
POST /routine/add Add cron/interval/webhook routine
GET /routine/list All routines
POST /routine/trigger/{id} Manually trigger routine
GET /routine/history Execution history
```
### osmoda-mesh (`/run/osmoda/mesh.sock`)
```
POST /invite/create Generate invite code for peer
POST /invite/accept Accept invite, establish encrypted tunnel
GET /peers Connected peers
POST /peer/{id}/send Send encrypted message to peer
GET /identity Ed25519 + X25519 + ML-KEM-768 public keys
```
### osmoda-mcpd (`/run/osmoda/mcpd.sock`)
```
GET /health Server count, running count, per-server status
GET /servers All managed MCP servers with status and config
POST /server/{name}/start Start a stopped server
POST /server/{name}/stop Stop a running server
POST /server/{name}/restart Restart a server
POST /reload Re-read config, start new servers, stop removed ones
```
### osmoda-teachd (`/run/osmoda/teachd.sock`)
```
GET /health Observation/pattern/knowledge/skill counts, loop status
GET /observations System observations (?source=cpu&since=...&limit=50)
GET /patterns Detected patterns (?type=recurring&min_confidence=0.5)
GET /knowledge Knowledge documents (?category=reliability&tag=...)
POST /knowledge/create Manual knowledge doc {title, category, content, tags}
POST /teach Context-aware knowledge injection {context: str}
POST /optimize/suggest Generate optimization suggestions from knowledge
POST /optimize/apply/{id} Apply optimization via SafeSwitch
GET /optimizations List optimizations (?status=suggested&limit=20)
POST /observe/action Log agent tool execution for skill learning
GET /actions List logged actions (?tool, ?session_id, ?since)
GET /skills/candidates List auto-detected skill candidates (?status)
POST /skills/generate/{id} Generate SKILL.md from candidate
POST /skills/promote/{id} Promote skill to auto-activation
POST /skills/execution Record skill execution outcome
GET /skills/executions List execution history (?skill_name)
```
See [SKILL-LEARNING.md](docs/SKILL-LEARNING.md) for the full skill auto-teaching pipeline.
### osmoda-keyd (`/run/osmoda/keyd.sock`) — optional
```
POST /wallet/create { chain: "ethereum"|"solana", label } → { id, address }
GET /wallet/list All wallets
POST /wallet/sign Policy-gated payload signing
POST /wallet/send Build signed intent (no broadcast — see STATUS.md)
```
---
## Development
```bash
git clone https://github.com/bolivian-peru/os-moda.git && cd os-moda
cargo check --workspace # Type check all 10 crates
cargo test --workspace # 213 Rust tests (+ 34 gateway via `npm test` in packages/osmoda-gateway = 247)
# Run agentd standalone
cargo run -p agentd -- --socket /tmp/agentd.sock --state-dir /tmp/osmoda
# Dev VM with Sway desktop (requires Nix)
nix build .#nixosConfigurations.osmoda-dev.config.system.build.vm
./result/bin/run-osmoda-dev-vm -m 4096 -smp 4
# Build installer ISO
nix build .#nixosConfigurations.osmoda-iso.config.system.build.isoImage
```
### Repo Structure
```
crates/agentd/ System bridge daemon (API + ledger + memory)
crates/agentctl/ CLI (events, verify-ledger)
crates/osmoda-watch/ SafeSwitch + autopilot watchers
crates/osmoda-routines/ Background automation engine
crates/osmoda-teachd/ System learning + self-optimization
crates/osmoda-mesh/ P2P mesh (Noise_XX + ML-KEM-768)
crates/osmoda-voice/ Local voice (whisper.cpp + piper)
crates/osmoda-mcpd/ MCP server lifecycle manager
crates/osmoda-egress/ Domain-filtered egress proxy
crates/osmoda-keyd/ Crypto wallet daemon (ETH + SOL, AES-256-GCM)
packages/osmoda-gateway/ Modular gateway (drivers + agents.json + credentials, HTTP+WS+Telegram)
└── src/drivers/ { claude-code, openclaw, managed-agent } — pluggable runtime drivers
packages/osmoda-mcp-bridge/ MCP server (92 tools over stdio protocol)
packages/osmoda-bridge/ OpenClaw plugin (92 tools, used by openclaw driver)
packages/osmoda-client/ First-party TypeScript SDK for the spawn.os.moda v1 API
nix/modules/osmoda.nix NixOS module (single source of truth)
nix/hosts/ VM, server, ISO configs
templates/ Agent identity + tools + heartbeat
skills/ 19 system skill definitions
```
### Tech Stack
- **Rust** (axum, tokio, rusqlite, serde, k256, ed25519-dalek, aes-gcm, sha3, snow, ml-kem)
- **NixOS** (flakes, crane, systemd, nftables, bubblewrap)
- **TypeScript** (osmoda-bridge gateway plugin)
## Status
> **v1.3.0 — stable core, honest about the rest.** osModa is a working operating system with 247 tests (213 Rust + gateway) and a self-run pentest behind it — but it's an ambitious solo project with months of work, *not* externally-audited, battle-tested infrastructure. The architecture, the agentd contracts, the event/streaming contract, and **Claude Code as the main runtime** are stable and you can build on them. Still maturing: the tier-0 tool gate (built, wire-tested, on-box verification pending), fleet-wide trust, an external security review, and the company-integration layer — tracked per component in [STATUS.md](docs/STATUS.md). **Treat it as research-grade: run it on a fresh/disposable box, not production you care about.** It's a real, fast-moving 1.x.
**The numbers:**
- 10 Rust crates (10 daemons + 1 CLI)
- 247 tests (213 Rust workspace + 34 gateway; gateway suite green via `npm test`, Rust CI-gated)
- 92 bridge tools registered
- 20 system skills
- Stress tested: 700/700 concurrent health checks, 50 concurrent queries, hash chain verified across 300+ events with zero broken links
**What works today:** Structured system access, hash-chained audit ledger, persistent named chats (multiple distinct conversations per server, each with its own session + transcript + auto-compaction) with cross-chat and cross-channel awareness, token-streaming chat across both default drivers, FTS5 full-text memory search, pre-indexed code knowledge graph (CodeGraph — `codegraph_search/context/impact/callers/callees/…`, auto-indexed across the OS source + workspaces + deployed apps), SafeSwitch deploys with auto-rollback, background automation, P2P encrypted mesh with hybrid post-quantum crypto (Noise_XX + ML-KEM-768), local voice (whisper.cpp + piper), MCP server management, system learning and self-optimization with auto-generated skills, fleet coordination with quorum voting, approval gates for destructive *structured-tool* ops (native-tool gating in progress — see [Safety Model](#safety-model)), sandboxed execution, service discovery, emergency safety commands, Cloudflare Tunnel + Tailscale remote access, app process management, ETH + SOL crypto wallets, one-command cloud deployment via [spawn.os.moda](https://spawn.os.moda).
**What's next:** Semantic memory engine (usearch + fastembed), external security audit of mesh crypto, end-to-end integration tests, WebRTC browser-to-server connections.
See [ROADMAP.md](docs/ROADMAP.md) for the full plan and [STATUS.md](docs/STATUS.md) for honest maturity levels per component.
## One-Click Cloud Deploy
Don't want to self-host? [**spawn.os.moda**](https://spawn.os.moda) provisions a fully configured osModa server on Hetzner Cloud in ~10 minutes. Pick a plan, pay with card or USDC, and start chatting with your server from the browser or Telegram.
The dashboard shows real orchestration data from your server's daemons: active routines and watchers, audit event feed, learned system patterns, and running tool servers — all from live heartbeat data, not mocks. Manage agents directly from the dashboard: create new agents with model and channel routing, edit existing agents, or remove them — changes apply immediately on the server.
### Programmatic API (agents spawning agents)
Spawn osModa servers from code or from other AI agents via the v1 API with x402 payment:
```bash
# Discover capabilities (A2A/ERC-8004 Agent Card)
curl https://spawn.os.moda/.well-known/agent-card.json
# List plans with pricing
curl https://spawn.os.moda/api/v1/plans
# Spawn a server (x402 USDC payment required)
curl -X POST https://spawn.os.moda/api/v1/spawn/test \
-H "Content-Type: application/json" \
-d '{"region": "eu-central", "ssh_key": "ssh-ed25519 ..."}'
# → { order_id, api_token: "osk_...", server_ip, status_url, chat_url }
# Check status
curl https://spawn.os.moda/api/v1/status/{orderId} \
-H "Authorization: Bearer osk_..."
# Chat with the server's AI via WebSocket
wscat -c "wss://spawn.os.moda/api/v1/chat/{orderId}?token=osk_..."
# Full agent skill doc (plain text, for agents to read)
curl https://spawn.os.moda/SKILL.md
```
Plans: `test` (Solo $14.99), `starter` (Pro $34.99), `developer` (Team $62.99), `production` (Scale $125.99).
Payment via Coinbase x402 protocol (USDC on Base or Solana). Full API docs at [`/api/v1/docs`](https://spawn.os.moda/api/v1/docs). Agent skill doc at [`/SKILL.md`](https://spawn.os.moda/SKILL.md).
## In the wild
- **[spawn.os.moda](https://spawn.os.moda)** — hosted provisioning. Public x402-payable API, live ERC-8004 agent card, v1.3 modular runtime + persistent named chats, **github/spec-kit baked into every spawn**.
- **Spec-driven dev support** — every new spawn comes with `uv` + `specify-cli` + the 9 `speckit-*` skills. Run `specify init` and you're in the github/spec-kit ecosystem (92K stars). See `skills/spec-driven-development/SKILL.md` and the [`SPEC-KIT-INTEGRATION`](docs/planning/SPEC-KIT-INTEGRATION.md) deep dive.
- *Your deployment here →* open a PR adding a one-line description + link.
## Contributing
v1.3.0, actively developed. Feedback, bug reports, and PRs welcome.
- **Good first issues** — see the [good-first-issue label](https://github.com/bolivian-peru/os-moda/labels/good%20first%20issue) for scoped 30-90 min tasks
- **Bug reports** — open an issue, include logs (`journalctl -u osmoda-gateway --since '10 min ago'`)
- **New skills** — add `skills/<name>/SKILL.md`, open a PR
- **New runtime driver** — add a single file under `packages/osmoda-gateway/src/drivers/` implementing `RuntimeDriver`; Codex, Bedrock, Vertex all welcome
- **NixOS module** — `nix/modules/osmoda.nix` is the core
- **MCP tools** — `packages/osmoda-mcp-bridge/`
- **Rust daemons** — each daemon is a standalone crate in `crates/`
**Community:** [Telegram](https://t.me/osmodasystems) · [Discord](https://discord.gg/G7bwet8B)
## License
Apache 2.0. See [LICENSE](LICENSE).
---
<div align="center">
**osModa** — the first operating system built for AI agents.
[Website](https://os.moda) · [Deploy](https://spawn.os.moda) · [Telegram](https://t.me/osmodasystems) · [Discord](https://discord.gg/G7bwet8B)
</div>
