███╗   ██╗ ██████╗ ██╗   ██╗ █████╗      ██████╗ ███████╗
 ████╗  ██║██╔═══██╗██║   ██║██╔══██╗    ██╔═══██╗██╔════╝
 ██╔██╗ ██║██║   ██║██║   ██║███████║    ██║   ██║███████╗
 ██║╚██╗██║██║   ██║╚██╗ ██╔╝██╔══██║    ██║   ██║╚════██║
 ██║ ╚████║╚██████╔╝ ╚████╔╝ ██║  ██║    ╚██████╔╝███████║
 ╚═╝  ╚═══╝ ╚═════╝   ╚═══╝  ╚═╝  ╚═╝     ╚═════╝ ╚══════╝

The missing layer in your AI stack.

---

What is Nova OS?

Nova sits between your AI agents and the real world.

Every action an agent wants to execute passes through Nova first. Nova evaluates it in under 5ms, logs it to an immutable ledger, and either approves, blocks, or escalates — before anything reaches production.

agent wants to act  →  Nova evaluates (<5ms)  →  APPROVED / BLOCKED / ESCALATED  →  world

Not another agent. Not another chatbot. Infrastructure.

---

The problem

AI agents execute actions without control. They hallucinate endpoints, send duplicate emails, write to wrong databases, run destructive commands — and nothing stops them.

When something goes wrong: no trace. No brake. No rollback.

Nova fixes that.

---

Install

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/sxrubyo/nova/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/sxrubyo/nova/main/install.ps1 | iex

npm:

npm install -g nova-os
nova

Termux (Android, no root):

pkg install python git openssl
curl -fsSL https://raw.githubusercontent.com/sxrubyo/nova/main/install.sh | bash

Docker:

cp .env.example .env
docker-compose up -d --build

---

Quickstart — 2 commands

# one command. every agent on your machine gets governed.
nova guard

# add a rule instantly in plain language
nova rule "never delete files from /prod"

That's it. Nova auto-discovers your agents, injects governance rules, and starts watching.

---

How it works

Score ≥ 70   →  ✓  APPROVED   — executes immediately
Score 40-70  →  ⚠  ESCALATED  — pauses, waits for your decision
Score < 40   →  ✗  BLOCKED    — stopped, logged, explained

Every decision is written to the Intent Ledger. Cryptographic. Auditable. Permanent.

---

Core commands

Command	What it does
nova init	13-step guided setup — agents, rules, policy, model
nova guard	Auto-discover and protect all agents in one command
nova boot	Start Nova Core + connect all agents
nova run "<cmd>"	Wrap any CLI command with risk classification
nova shield	HTTP proxy — intercept and validate every request
nova protect	Attach to a live HTTP agent (fire-and-forget)
nova rule "<text>"	Add a governance rule in plain language — active instantly
nova validate	Manually validate any action through the pipeline
nova validate batch	Validate up to 20 actions in parallel
nova simulate	Test policy without creating tokens or ledger entries
nova watch	Live-stream every decision as it happens
nova ledger	Browse the full immutable action history
nova verify	Check cryptographic chain integrity
nova audit	Generate a full audit report
nova stats	Analytics dashboard — risk profiles, anomalies, heatmaps
nova memory	Store and search agent context semantically
nova scout	Security scan — detect misconfigurations
nova anomalies	View detected behavioral anomalies
nova benchmark	Measure validation latency and throughput
nova mcp export	Export config as MCP-compatible manifest
nova commands	Full command reference

---

nova init — 13-step guided setup

Step 1   Welcome and orientation
Step 2   How Nova works — score system explained
Step 3   Auto-discovery — finds your agents automatically
Step 4   Pre-flight warnings — what Nova can and cannot do
Step 5   First rule — plain language, active immediately
Step 6   Identity — name and organization
Step 7   API key — generate, import, or use saved
Step 8   Server — local or custom URL
Step 9   Connection — cryptographic handshake
Step 10  Intelligence — choose your AI model
Step 11  Governance policy — strict / balanced / permissive / custom
Step 12  Escalation channel — CLI / email / webhook
Step 13  Skills — connect Gmail, Slack, GitHub and more

Supported models: Claude · GPT-4 · Gemini · Groq · Mistral · DeepSeek · Cohere · OpenRouter · Ollama (local)

---

nova guard — one command, all agents

nova guard

Nova scans your environment, detects every AI agent running, and puts all of them under governance. No config files. No manual setup per agent.

nova guard --path .env      # protect a specific path from ALL agents
nova guard --path /prod     # nothing in /prod can be touched

---

nova run — wrap any command

nova run "pm2 restart melissa"
nova run "rm -rf /tmp/old-logs"
nova run "git push origin main --force"

Nova classifies the risk, shows you the verdict, and either executes or blocks. Every run is logged.

---

nova shield — HTTP proxy

nova shield

Starts a proxy on 127.0.0.1:7755. Every HTTP request from your agents passes through it. Nova validates the action before forwarding. Nothing reaches your services unexamined.

---

Agent auto-discovery

Nova detects agents running on your machine automatically:

OpenClaw          100% confidence  ● live
Melissa           100% confidence
n8n               100% confidence  ● live
Claude Code       100% confidence
OpenAI Codex CLI  100% confidence
Gemini CLI         50% confidence
GitHub Copilot     45% confidence
Custom OpenAI      35% confidence  ● live

---

Governance flow

1. DISCOVER    →  auto-detect agents on your machine
2. CONNECT     →  attach rules: cannot_do, must_confirm, rate_limits
3. INTERCEPT   →  every action passes through Nova before execution
4. EVALUATE    →  deterministic rules + optional LLM validation in <5ms
5. DECIDE      →  APPROVED / BLOCKED / ESCALATED / DUPLICATE
6. LEDGER      →  cryptographic, immutable, permanent record

---

Architecture

nova.py              CLI entrypoint + local server launcher
nova/                core: API, kernel, ledger, discovery, storage
frontend/            React dashboard at localhost:9800
n8n-nodes-nova/      n8n native integration
legacy/              compatibility layer — being cleaned up
docs/                deployment, API reference, architecture
tests/               platform, API, discovery, runtime tests

Core design decisions:

• Fail-open — Nova never blocks your work if it goes down
• LLM-optional — 90% of validations run without any AI call
• Hot-reload rules — update governance policies without restart
• Immutable ledger — cryptographic chain, nothing can be deleted
• Transparent proxy — wraps agents from outside, zero modification to agent code
• Offline mode — actions queue locally and sync when server returns
• Bilingual — ES/EN native, no config required

---

Platform support

Platform	Status
Linux	✅ Full support
macOS	✅ Full support
Windows	✅ PowerShell installer
Termux (Android)	✅ No root required
Docker	✅ Compose stack included

---

Configuration

cp .env.example .env

Minimum for production:

SECRET_KEY=your-secret-key
WORKSPACE_ADMIN_TOKEN=your-token

PostgreSQL optional. SQLite by default. Never commit .env files.

---

Contributing

Nova OS is early and open. Issues, PRs and feedback welcome.

If you are building something on top of it — reach out.

---

Built by sxrubyo · Black & Boss · MIT License