Orivus Edge OS

Orivus Edge OS v0.1.2 — Governed Local AI Runtime Technical Preview

AI can generate code. Orivus governs contribution.

Orivus Edge OS v0.1.2 is a governed local AI runtime with structural intelligence and deterministic mutation authorization. Agents propose changes; only the kernel may authorize, apply, audit, and observe real workspace mutation.

v0.1.2 focuses on governed local coding execution. The broader operator-kernel vision will expand through future agents and runtime capabilities.

Status: v0.1.2 Technical Preview — governance certified on the golden path; live local LLM may fail on constrained hardware. See release-checklist-v0.1.md.

Core law: Agents propose. The kernel governs. The runtime observes. Reality changes only through explicit governed authorization.

What Orivus is

• A governed local AI coding runtime
• Orivus Coding as the first certified agent module (@orivus-ai/coding-agent)
• Kernel-owned mutation authority — GovernedApplyService is the only legal disk write path for governed targets
• Local-first inference with governed structural memory (deterministic workspace context under .orivus/)
• Operational observability — runtime status, event log, mission console, replay

How Orivus is different

| Tool | Role | Orivus v0.1 | |------|------|-------------| | Cursor / Claude Code | Assistants that propose code in your editor | Governs mutation, human-approved apply, and audit — disk unchanged until --confirm | | LM Studio | Local model runtime and chat | Governs agent execution and kernel-owned apply for coding workflows | | LangChain | Application orchestration framework | Local governed execution kernel/runtime for agents — not an app framework |

Long-term vision: an AI Operator Kernel for local agents. v0.1 starts with governed local coding as the first high-risk workflow.

What Orivus is not

• Not a chatbot, copilot, or IDE autocomplete tool
• Not the “Linux of AI agents” or a complete AI OS yet
• Not a multi-agent platform yet (additional agents are install-at-your-own-risk)
• Not autonomous production mutation — confirm is mandatory
• Not multi-file governed apply in v0.1 (single-file golden path only)

Why governed AI matters

Uncontrolled AI coding tools blur proposal and mutation. Orivus makes the boundary explicit:

| Phase | Who | Disk | |-------|-----|------| | Analyze, plan, preview, review | Agent | Unchanged | | Apply without --confirm | Kernel gate | Blocked | | Apply with --confirm | Kernel (GovernedApplyService) | Changed + audited |

You see pending state, preview real diffs, and confirm before reality changes.

Architecture overview

flowchart LR
  User --> CLI[CLI]
  CLI --> Agent[Coding Agent]
  Agent --> Session[(Session)]
  CLI --> Seal[Pipeline Sealer]
  CLI --> Apply[GovernedApplyService]
  Apply --> Disk[(Workspace)]
  Apply --> Audit[(Audit)]
  Session --> Runtime[Operational Runtime]

| Layer | Responsibility | |-------|------------------| | Agent module | Semantic meaning: intent, plan, preview, review | | Kernel (Edge) | Sessions, attestation, governed apply, audit, capabilities | | Operational runtime | Health, events, mission replay (observe only) | | CLI | Human control plane; honest live vs offline labels |

Deep dive: docs/architecture.md · docs/governance.md

Distribution model (v0.1)

| Artifact | Visibility | |----------|------------| | GitHub orivus-edge | Public | | npm @orivus-ai/edge | Public | | GitHub orivus-coding-agent | Public (Apache-2.0 reference agent) | | npm @orivus-ai/coding-agent | Public (installed by orivus init) |

After npm publish, users do not need to clone the coding-agent repo. orivus init installs @orivus-ai/coding-agent automatically. Use --agent-path only for local development.

Golden path demo

Certified fixture: certification/fixtures/v1-golden-path

cd certification/fixtures/v1-golden-path
# After npm publish (recommended):
orivus init --yes
# Development only: use --agent-path <local-built-agent> when testing against a local checkout.
orivus index
orivus coding change --contract contracts/golden-path.orivus.yaml
# Normal mode: governed mission report → PREVIEW READY or BLOCKED SAFELY (see docs/cli.md)
git diff                                    # empty — disk unchanged
orivus coding apply                         # blocked
orivus coding apply --preview               # real diff — disk unchanged
orivus coding apply --confirm               # kernel write + audit
orivus runtime status
orivus console --replay mission_<sessionId>

Official walkthrough: docs/demo-release-v0.1.md

Manual npm publish (maintainers)

1. Build @orivus-ai/coding-agent locally (or set ORIVUS_AGENT_PATH to a built checkout).
2. Run pnpm run release:verify in this repo (removes "private": true only when all gates pass).
3. Publish Edge first: npm publish --provenance --access public
4. Publish @orivus-ai/coding-agent second on npm.
5. Until both packages are on npm, orivus init may require --agent-path for local agent development.

Edge is BUSL-1.1 (source-available, not fully open source until the Change Date). The reference coding agent is Apache-2.0.

Installation / setup

Requirements: Node.js ≥ 22

Recommended (after npm publish)

npm install -g @orivus-ai/edge
cd your-project
orivus init    # operating mode: Coding (stable) or Local Runtime (experimental)
orivus index          # structural memory — required before governed coding workflows
orivus coding change "describe your change" --file src/example.ts
orivus coding apply --preview

orivus index prepares governed structural memory so the runtime understands your repository layout and dependency relationships locally — it is not a vector index or IDE symbol dump.

Operating modes: Coding (stable) installs the governed coding agent. Local Runtime (experimental) prepares a read-only local runtime shell — use orivus chat only after indexing if you want workspace-aware exploration; it does not replace the governed coding workflow.

From source (contributors)

git clone https://github.com/orivus/orivus-edge.git
cd orivus-edge && pnpm install && pnpm run build

# Use the built CLI (or: pnpm link --global)
node dist/cli.js --help

Orivus Coding Agent is distributed separately as @orivus-ai/coding-agent on npm (Apache-2.0; public repo orivus/orivus-coding-agent). For local agent development, use orivus init --agent-path <local-built-agent>.

First orivus init may download local GGUF models to ~/.orivus/models.

Main commands

| Command | Status | |---------|--------| | orivus init | Stable | | orivus index | Stable — builds structural memory for governed local execution | | orivus doctor / doctor --product | Stable | | orivus coding change | Stable | | orivus coding apply / --preview / --confirm | Stable | | orivus runtime status / runtime watch | Stable | | orivus console / --replay / --governance | Stable | | orivus chat | Experimental — read-only local runtime shell | | orivus daemon start | Advanced |

Full manual: docs/cli.md

Certification

pnpm run certify:product
# or
orivus doctor --product

Writes certification/reports/product-report.json (local artifact). Expect GO when engineering and product gates pass.

Shipped guarantee (v0.1): governanceCertification: pass — deterministic golden-path apply, syntax gate, audit. Live LLM (liveLlmCertification) may fail on constrained hardware; that does not block governance certification. A deterministic seeded session fallback exists for certification; production use expects local models via orivus init.

Local-first runtime

Orivus does not mutate your project package manager. Agents install into ~/.orivus/agents/; workspace state stays under .orivus/.

| Scope | Path | |-------|------| | Global runtime | ~/.orivus/agents/, ~/.orivus/models/ | | Workspace | .orivus/ (session, audit, index, runtime) |

• Structural memory: .orivus/index/ (deterministic workspace context for agents and runtime)
• Optional daemon for live SSE; CLI tails events.ndjson when offline

Known limitations

• Single-file governed mutation
• First-run model download
• Trusted agent binary (no VM sandbox)
• No transactional rollback in v0.1 (rollbackFromBackup is unsupported) — use Git
• Structural topology only
• One certified agent: coding

Details: docs/known-limitations-v0.1.md

Roadmap

| Version | Focus | |---------|--------| | v0.1 | Governed coding golden path (this release) | | v0.2 | Multi-file governed mutation + rollback | | v0.3 | Editor / MCP integration + stronger topology | | Future | Multi-agent governed runtime |

Contributing

docs/contributing.md — setup, boundaries, tests, certification.

AI assistants: docs/ai-agent-rules.md · docs/for-ai/PROJECT_CONTEXT.md

Documentation

| Document | Purpose | |----------|---------| | architecture.md | System design | | governance.md | Mutation authority & threat model | | cli.md | Command reference | | demo-release-v0.1.md | Official demo script | | known-limitations-v0.1.md | Honest scope | | release-checklist-v0.1.md | Release gates | | contributing.md | Contributor guide | | glossary.md | Term definitions | | architecture-decision-records/ | ADRs | | for-ai/ | AI agent context & rules | | npm @orivus-ai/coding-agent | Apache-2.0 reference agent (public repo orivus-coding-agent) |

Licensing

Orivus Edge OS is source-available under BUSL-1.1 — not “fully open source” until the Change Date.

| Topic | Summary | |-------|---------| | What you can do | Personal, academic, evaluation, open-source development, and internal use below USD $2M annual gross revenue (see Additional Use Grant) | | What needs a commercial license | Hosted/managed services to third parties, OEM/embedded commercial redistribution, competing product redistribution, and organizations ≥ USD $2M annual gross revenue | | Change Date | 2030-05-01 → converts to Apache 2.0 for that version | | Reference agent | @orivus-ai/coding-agent is Apache-2.0; agents propose, kernel governs apply |

Full guide: docs/licensing.md · Commercial: orivus.ai/licensing or [email protected]

License / status

Orivus Edge OS v0.1.2 — Business Source License 1.1 (BUSL-1.1)

Engineering gates:

pnpm run release:verify   # full publish gate (then manual npm publish)
pnpm run lint && pnpm run typecheck && pnpm run arch:check && pnpm run build && pnpm run test