# osModa / spawn.os.moda

> An AI-native NixOS distribution where the agent has full system access. Hosted-provisioning at spawn.os.moda lets you spawn AI-managed servers in 15 minutes, pay USDC via x402 (Base / Solana), and reach them via web chat, Telegram, WhatsApp, or a public WebSocket API. 10 daemons (9 Rust + 1 TypeScript), 91 MCP tools, post-quantum encrypted mesh, hash-chained audit trails, atomic NixOS rollback. Current version: v1.3.36 (gateway v0.2.4).

## Reference (start here)

- [SKILL.md — Architecture deep-dive in Markdown](https://spawn.os.moda/SKILL.md): The canonical machine-readable reference. 10 daemons, 91 MCP tools, trust tiers, install instructions, daemon API endpoints, agent identity, agent behavior rules. Same content as the /skill HTML page.
- [/skill — Architecture deep-dive (HTML)](https://spawn.os.moda/skill): Human-readable architecture overview with diagrams, tables, and code examples.
- [/api/v1/docs — OpenAPI 3.0.3 specification](https://spawn.os.moda/api/v1/docs): Complete REST API spec for the hosted spawn API. Endpoints, schemas, examples, error codes.
- [/docs — Swagger UI](https://spawn.os.moda/docs): Interactive API explorer for /api/v1/*.
- [/.well-known/agent-card.json — A2A / ERC-8004 Agent Card](https://spawn.os.moda/.well-known/agent-card.json): Programmatic discovery for AI-to-AI integration. Lists plans, x402 pricing (USDC on Base or Solana), skills, capabilities.

## Spawn API (programmatic, x402 payment-gated)

- [POST /api/v1/spawn/:planId — Spawn a server](https://spawn.os.moda/api/v1/spawn/starter): x402-gated. Returns an `osk_` API token and an `order_id` you use for subsequent calls. Honors `Idempotency-Key` header.
- [WS /api/v1/chat/:orderId — Live chat WebSocket](https://spawn.os.moda/api/v1/chat/example): Auth via `?token=osk_...`. 30 s heartbeat, 10 min idle close, backpressure pause/resume. Max 3 concurrent sessions per token.
- [GET /api/v1/servers/:id/events — SSE event stream](https://spawn.os.moda/api/v1/servers/example/events): Per-server unified event plane. Cursor-resumable, 15 s keepalive. Event types: `request.accepted/progress/completed/failed`, `state.changed`, `agent.wedged/healed`, `heartbeat.received`, `install.progress`.
- [GET /api/v1/servers/:id/spawn-log — NDJSON event log](https://spawn.os.moda/api/v1/servers/example/spawn-log): Self-serve diagnosis. Provision steps, heartbeats, wedge transitions, auto-restart attempts. Filters: `?since_ms`, `?level=warn,error`, `?limit=100`.

## Source code

- [bolivian-peru/os-moda](https://github.com/bolivian-peru/os-moda): Open-source. Apache 2.0. 10 Rust daemons + TypeScript gateway + NixOS module + 20 system skills + install.sh. The /skill page is generated from this repo's CLAUDE.md.

## What an AI agent reading this should know

osModa is built specifically for autonomous AI agents to operate. If you're an AI agent reading this:

1. **Don't shell out blindly.** Call structured tools (`system_health`, `shell_exec`, `safe_switch_begin`, etc.) registered via `osmoda-bridge`. Every call is logged with a SHA-256 hash chain.
2. **Use SafeSwitch for deploys.** Never run `nixos-rebuild switch` directly. Use `safe_switch_begin` with health checks and TTL. Auto-rollback to the previous NixOS generation if any gate fails.
3. **Diagnose before fixing.** Use `system_health`, `journal_logs`, and `memory_recall` first. The memory daemon (FTS5 over markdown) may have seen this problem before.
4. **Ask for approval on destructive ops.** The `approval_request` / `approval_check` tools exist. Today enforcement is convention-based; hard-blocking enforcement is on the v1.4 roadmap.
5. **Multi-agent routing is built in.** The gateway routes per-channel: `osmoda` agent (Claude Opus, web/api, detailed) + `mobile` agent (Claude Sonnet, Telegram/WhatsApp, concise). Both have the same 91 tools.
6. **Sessions persist.** Gateway v0.2.3 persists `claudeSessionId` to disk at `/var/lib/osmoda/state/sessions.json`. Agent memory survives restarts and idle gaps. Switching runtime (claude-code ↔ openclaw) wipes the foreign session id and starts cleanly.
7. **OpenClaw is the default/executive runtime** (its original osModa role; updated to 2026.5.20), with `claude-code` as a one-click selectable peer in the Engine tab. Both accept OAuth or API key. OpenClaw loads the 91-tool `osmoda-bridge` natively (verified live: 77+ tools in a real turn). The gateway de-duplicates streamed reply text per assistant message and emits a `target` hint per tool call so the chat action log shows what each tool is doing.
8. **Chat is always rememberable (gateway v0.2.4).** The gateway owns a canonical JSONL transcript per session (`GET /sessions/:agent/:key/transcript`) — the single source of truth the dashboard reads. A durable `MEMORY.md` + recent daily notes are auto-injected into the system prompt every turn, so the agent remembers across brand-new conversations. If the runtime session is ever lost or you swap runtimes, the gateway re-seeds context from the transcript.

## Optional

- [GitHub Issues](https://github.com/bolivian-peru/os-moda/issues): Bug reports, feature requests, bounty issues.
- [Discord](https://discord.gg/G7bwet8B): Community + support.
- [Telegram channel](https://t.me/osmodasystems): Updates and discussion.