corvinos 0.10.63

CorvinOS — universal, self-contained, cross-platform AI assistant framework

Overview · 🧩 Plugin System · Architecture · Audit & Compliance · A2A Network · Engine Layer · Security · EU AI Act · For Organizations

---

One install. Any bridge. Any LLM.

CorvinOS is a self-hosted agentic OS that connects Claude Code, Codex, Hermes, Ollama and any OpenRouter model to Discord, Telegram, WhatsApp, Slack, Email, Teams, Signal and more — through a single pip package.

• Local-first — run 100 % offline with Ollama and --engine hermes. No API key needed.
• Agentic — generates sandboxed tools and new skills at runtime; delegates subtasks across any number of AI engines.
• Compliance by architecture — EU AI Act 2026 + GDPR enforced in code, not policy documents.
• Multi-tenant — one instance, multiple users, personas, and teams, all isolated.

▶ Watch the demo on YouTube

---

Quick Start

# macOS / Linux — no Python or package manager required
curl -fsSL https://corvin-labs.com/install.sh | sh

# Windows (PowerShell)
irm https://corvin-labs.com/install.ps1 | iex

The installer brings its own Python via uv — no prerequisites needed. It sets up Hermes (local Ollama model) so CorvinOS runs fully offline from the first start.

Already have Python 3.10+?

pip install corvinos
python -m corvinOS        # web console at http://localhost:8765

Offline-capable voice (Piper TTS + pywhispercpp/whisper.cpp STT) ships in the base install — no extra needed, on Linux, macOS, and Windows alike. STT self-heals on first use (pywhispercpp downloads its small model on demand even without running the installer), but Piper's offline TTS voice model is only fetched by corvin-install — running just pip install corvinos + python -m corvinOS gets you edge-tts (free, needs internet) for speech output until you run corvin-install once. The optional corvinos[voice] extra now only adds faster-whisper for power users who want its CTranslate2-accelerated STT and already have a working av install.

Full setup guide: INSTALLATION.md

---

---

Features

Messenger Bridges

Connect Discord, Telegram, WhatsApp, Slack, Email, Microsoft Teams, and Signal — all through one shared runtime. Each bridge shares the same session state, audit chain, and persona configuration. Add custom bridges via the plugin system.

Pluggable AI Engines

Claude Code, Codex CLI, OpenCode, Hermes (local Ollama), and GitHub Copilot plug in via the WorkerEngine protocol. Switch engines per chat or per tenant; the audit chain, path-gate, and skill system follow automatically. New engines can be registered without touching the compliance stack.

Web Console

Full control plane at http://localhost:8765 — manage sessions, personas, forge tools, skill library, RAG providers, and audit logs from a single dashboard. Built-in voice (STT/TTS), session workdir browser, browser automation panel, and full REST API at /v1/console/.

Voice — push-to-talk and always-on

Hold the mic key to speak; CorvinOS transcribes, replies, and reads the answer aloud. Works in the web console and all messenger bridges. Local Piper TTS + pywhispercpp (whisper.cpp) STT for zero-egress deployments on every platform, incl. Windows; Microsoft Edge TTS and OpenAI Whisper available as cloud alternatives.

Forge — runtime tool generation

The agent generates sandboxed, bwrap-isolated tools on demand and calls them immediately — without a deploy step. Tools are schema-validated, path-gated, and registered in the session artifact memory. New tools are available in the same turn they are generated.

SkillForge — runtime skill creation

New workflows and domain knowledge distilled into reusable skills at runtime. Skills are graded, promoted, and auto-injected into future sessions — the assistant learns your patterns without any manual configuration.

Plugin System — extend the runtime, keep the core stable

One lifecycle contract (on_load / on_unload / health_check) across eleven extension points: worker engines, compute engines, bridge channels, STT, data connectors, audit and user backends, notification, recall, summary and routing providers. Declare a plugin in tenant.corvin.yaml or install it from the Console; settings forms are generated from the plugin's own JSON Schema, so no plugin ships UI code. Extension is additive only — core writes its hash-chained audit trail first and hands a plugin a copy, a user_backend failure means deny, and boot tripwires abort startup if a mandatory mechanism is missing (a chain break that is purely historical is recorded and reported instead — refusing to boot on it would only end the trail). Every plugin gets a circuit breaker; optional health polling exports Prometheus metrics, and optional self-healing performs reversible actions (contain, soft-restart, degrade) under an audited, per-hour budget. Read the architecture for the load paths, the compliance boundary and the healing ladder.

Tiered Delegation Engine (TDE)

Adaptive engine routing reduces token consumption by 40-70% through intelligent task classification. Routes to Claude Code (simple, interactive), TDE (iterative, context-preserving), or ACS (parallel, big-data) based on 5-signal ensemble detection. Modeled by a deterministic simulation (11 synthetic tasks; projected savings, no measured token usage or significance claim — see the honesty notes in operator/benchmarking/). Read the comprehensive guide for architecture, mechanisms, and reproducible proofs. Or run the benchmarks yourself in 5 minutes.

Agentic Compute + Data

Large datasets (CSV, databases, external APIs) are handled by a sandboxed compute worker so raw data never enters the LLM context. The agent submits one job and retrieves one result; iteration, sampling, and aggregation run in the worker at zero token cost. Supports PostgreSQL, MySQL, SQLite, DuckDB, and CSV out of the box.

Workflows + AWPKG

CorvinFlow lets you build multi-step automations as declarative DAGs — chain AI calls, forge tools, RAG queries, and data transforms. Package and share workflows as .awpkg bundles (ZIP archives with tools, skills, personas, and workflow YAML) installable in one command. See also: Handbook: Workflows.

RAG / Knowledge Providers

Connect vector databases and document stores as RAG providers. The agent queries your knowledge base before answering, grounding responses in your own data. Supports Chroma, Qdrant, Weaviate, pgvector, and custom connectors via the RAG Hub.

Memory + Conversation Recall

Three persistent memory layers — user profile (skills, preferences, history), session artifacts, and pinned project knowledge — survive session resets and follow the user across bridges. PII is redacted before indexing; recall is scoped per tenant.

Browser Automation

The agent navigates websites, fills forms, and clicks UI elements via Playwright — with live step-by-step narration over voice and human-in-the-loop confirmation before any destructive action. Watch the driven browser live in the console and take over at any time.

Agent-to-Agent Network (A2A)

Multiple CorvinOS instances form a decentralised agent mesh. Every cross-instance call carries cryptographic attestation, nonce replay protection, and an audit-first envelope — the record is written before any response is sent.

Organizations + Multi-Tenant

One instance handles multiple users, teams, and projects in full isolation. Per-tenant engine allowlists, data residency rules, persona sets, and quota limits in a single tenant.corvin.yaml. See the organizational deployment guide for SSO, role management, and enterprise integration patterns.

Data Classification + Egress Control

Four-stage classification (PUBLIC / INTERNAL / CONFIDENTIAL / SECRET) gates every engine spawn. EU_PRODUCTION egress preset blocks all hosts not on the explicit allowlist. Raw data rows never enter the LLM context — only schema, aggregate stats, and anonymised samples.

GDPR Art. 17 Erasure

One command erases a user across sessions, audit records, recall DB, and all registered artifacts — cross-layer, pseudonymised, and audit-trailed. The hash chain is de-linked, not deleted.

Custom Layers + Extensions

Add new compliance layers, bridge connectors, and engine adapters via the Custom Layer System. Extensions are licensed (Tier-A/B/C) and gated — the core compliance stack cannot be overridden by an extension.

---

EU AI Act 2026 + GDPR

CorvinOS implements EU AI Act 2026 and GDPR as structural design constraints — not policy documents. Every compliance requirement is load-bearing code that cannot be disabled by a flag, env var, or config override.

Guarantee	What it means
Bot disclosure	One-time AI-nature statement per user; no bypass path (EU AI Act Art. 50)
Consent gate	Deny-by-default, TTL-capped, re-validated at every session consume (GDPR Art. 6 & 7)
Hash-chained audit	SHA-256 chain, offline-verifiable, daily auto-verify; chain write failure blocks the request (GDPR Art. 30 & 32)
Egress lockdown	Declarative allowed_hosts / EU_PRODUCTION preset; default_action=deny (EU AI Act Art. 14)
Erasure orchestrator	Cross-layer GDPR Art. 17 erasure — sessions, recall, artifacts, audit de-linked
House-rules gate	SHA-256-anchored acceptable-use policy; no kill-flag, no tenant override (EU AI Act Art. 5 & 50)

voice-audit verify              # walk the full hash chain; exits 1 on any break
bridge.sh doctor                # boot self-test with audit chain verification

Full reference: docs/eu-ai-act/README.md · docs/audit-and-compliance.md

---

Architecture

CorvinOS and the Worker Engines are two deliberately separate layers. Bridge daemons funnel messages from every channel into CorvinOS: the Bridge Adapter enforces ACL, routes to the right persona, runs the TTS pipeline, and grades skills — per-chat-sequential, cross-chat-parallel — alongside the MCP plugin stack (Forge, SkillForge, Recall, Compute). None of that changes based on which LLM answers the message.

Below the WorkerEngine protocol boundary sits a swappable set of Worker Engines — Claude Code, Codex CLI, OpenCode, Copilot CLI, and Hermes (the zero-config local default via Ollama) — each a thin adapter implementing the same interface. Compliance, audit, and the rest of the OS stay identical no matter which engine is plugged in; adding a new engine means implementing the protocol, not touching CorvinOS.

Full breakdown: docs/layer-model.md · Diagrams: docs/diagrams/ · Full documentation: docs/overview.md

---

Testing

bash operator/bridges/run-all-tests.sh

Tests span the Python adapter, Node daemon-boot smoke tests, cowork, forge, skill-forge, and all security layers. Claude is stubbed via ADAPTER_FAKE_CLAUDE=1; real bwrap is used where namespace isolation is under test.

---

Contributing

By opening a pull request you accept CLA.md. Every merged contribution requires a corresponding entry in CLA-SIGNATORIES.md. See CONTRIBUTING.md for the full workflow.

---

License

Licensed under the Apache License, Version 2.0.

Relicense right (CLA §3): The Maintainer retains the right to release future versions under a different license without requiring further contributor consent. Already-published Apache-2.0 releases are not affected. See CLA.md § 3 for full terms.