Overview · 🚀 TDE: Token Efficiency Engine · 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.
# 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 | iexThe 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:8765Offline-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
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.
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.
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/.
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.
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.
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.
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. Backed by scientific benchmarking: 11 deterministic tasks, 3 trials each, p=0.01 statistical significance. Read the comprehensive guide for architecture, mechanisms, and reproducible proofs. Or run the benchmarks yourself in 5 minutes.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 verificationFull reference: docs/eu-ai-act/README.md · docs/audit-and-compliance.md
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
bash operator/bridges/run-all-tests.shTests 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.
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.
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.