CorvinOS

Overview · Architecture · Audit & Compliance · A2A Network · Engine Layer · Security · EU AI Act · Learning Objectives

One install. Seven bridges. 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, and Signal — through a single pip package.

# 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

• 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 five AI engines.
• Compliance by architecture — EU AI Act 2026 (disclosure, consent, house-rules) and GDPR (audit chain, data residency, erasure) are load-bearing code, not policy documents. None can be disabled by a flag.
• Multi-tenant — one instance, multiple users, personas, and teams, all isolated.
• Self-hostable anywhere — Linux, macOS, Windows; Docker-ready; single pip install.

CorvinOS enforces the EU AI Act in code, not in documentation.

Every compliance requirement — disclosure, consent, audit integrity, data residency, egress control, GDPR erasure — is a structural constraint that cannot be disabled by a flag, env var, or config override. Regulated deployments get verifiable guarantees, not policy promises.

Quick Start

See INSTALLATION.md for the complete setup guide.

Recommended — one line, every platform, zero prerequisites:

# macOS / Linux
curl -fsSL https://corvin-labs.com/install.sh | sh

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

The bootstrap installer brings its own Python (via uv),
so you need no system Python, no pip, and no package manager installed first. It
puts corvinos-serve on your PATH, and it also sets up Hermes — installs Ollama
and pulls a local model (qwen3:8b, or qwen3:1.7b on <6 GB RAM) — so CorvinOS runs
fully offline with --engine hermes from the first start. The Windows one-liner uses
irm | iex (no &&), so it works in both PowerShell 5.1 and 7.

Only want cloud engines (Claude/GPT)? Skip the local model with --no-hermes
(sh -s -- --no-hermes) or CORVIN_SKIP_HERMES=1.

Already have Python 3.10+? A plain pip install works identically on all three OSes:

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

python -m corvinOS is PATH-independent: it starts the console on the first
try on every OS — including Microsoft Store / system Python, where pip install
falls back to a per-user scripts directory that is not on PATH (the usual reason
corvin-serve is "not found" on Windows). On Windows you can also use py -m corvinOS.

Want the short corvin-serve command on your PATH? Install with
pipx — it isolates the app and wires up PATH
automatically, on every platform:

pipx install corvinos
corvin-serve              # web console at http://localhost:8765

corvin-serve from a plain pip install only works once its scripts directory
is on PATH. Running python -m corvinOS once adds that directory to your PATH,
so corvin-serve then works in a new terminal — but pipx (or python -m corvinOS) is the reliable cross-platform path.

The base install is pure-Python and cross-platform — it brings the web console
all the way up to setup on Linux, macOS, and Windows, with cloud/edge voice
(OpenAI + Microsoft Edge TTS) working out of the box. For local, offline
speech models add the optional extra:

pip install "corvinos[voice]"   # local Piper TTS + faster-whisper STT

The voice extra is opt-in because its local-model dependencies (piper-tts,
faster-whisper) lack Windows wheels for some Python versions; keeping them
out of the base install means pip install corvinos reaches setup reliably on
every supported platform.

Requirements: Python 3.10+ · Linux, macOS 12+, or Windows 10/11 · Node.js 20+ required only for bridges

Default engine: Claude Code (Claude Pro or Max subscription required).
For fully local, zero-egress deployment: --engine hermes (Ollama, no API key).

Alternative package managers:

# macOS / Linux — Homebrew
brew tap CorvinLabs/corvinos && brew install corvinos

# Windows — Scoop
scoop bucket add corvinos https://github.com/CorvinLabs/scoop-corvinos && scoop install corvinos

# conda / mamba (pending review)
conda install -c conda-forge corvinos

# Developer install from source
git clone https://github.com/CorvinLabs/CorvinOS.git && cd CorvinOS
pip install -e ".[all]" && corvin-install

Full documentation: docs/overview.md

Uninstall

One command removes everything — services, config, data directories, and the package:

corvin-uninstall --purge   # removes all files without prompting
pip uninstall corvinos -y  # removes the Python package

Without --purge the uninstaller asks before deleting data directories (audit logs, API keys, session history). Use --purge for a fully non-interactive wipe.

What gets removed:

After pip uninstall corvinos -y the only thing left is the cloned repo directory (source installs) — delete it with rm -rf <repo> if you no longer need it.

EU AI Act 2026 + GDPR: Structural Enforcement

CorvinOS implements EU AI Act 2026 and GDPR as structural design constraints. Every feature must answer: does this weaken a compliance guarantee?

Absolute constraints — no env var, flag, or config can disable these:
disclosure is structurally locked · consent gate has no bypass · every audit event traverses the hash chain before any response · L34 blocks non-compliant engine spawns · L38 audit write failure blocks the A2A request · L44 house-rules gate has no kill-flag.

voice-audit verify              # walk the full hash chain; exits 1 on any break
bridge.sh doctor                # boot self-test with audit chain verification
python -m corvin_compliance_reports.cli generate processing-records   # GDPR Art. 30

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

Core Features

Swap the LLM Without Touching the Compliance Stack

CorvinOS decouples the AI backend from the compliance runtime via the WorkerEngine protocol (L22). Every engine shares path-gate, audit chain, and artifact registration through the Tool Execution Broker — swap providers without changing your compliance setup.

Multi-Agent Mesh — CorvinOS Instances Talk to Each Other

Multiple CorvinOS instances form a decentralized agent network. Every cross-instance call carries a cryptographic signature, bidirectional attestation, nonce replay protection, and binary attachment verification. Audit-first invariant: the envelope is written to the hash chain before any response is sent.

39-Layer Security Stack

Path-gate (write-protection) · secret vault with bwrap env-injection · sandboxed Forge tool generation · SkillForge with fail-closed linter · multi-tenant session isolation · conversation recall with PII-redaction · session artifact memory · external data sources with k-anonymised sampling.

Data Never Leaves Without Your Explicit Permission

Three-layer defence: per-tenant engine allowlist → data classification matrix (PUBLIC / INTERNAL / CONFIDENTIAL / SECRET) → egress host allowlist. EU_PRODUCTION presets ship out of the box. Raw data rows never enter the LLM context — only schema + aggregate stats + anonymised sample.

Web Console — Manage Everything From the Browser

Control plane at http://localhost:8765. Manage sessions, personas, bridges, forge tools, and audit logs from a single dashboard. Five-scope tenant model: one instance handles multiple users, projects, and teams in full isolation. Full REST API at /v1/console/.

bridge.sh console     # start web console
bridge.sh doctor      # health check + audit verify

Architecture

Seven bridge daemons (WhatsApp, Telegram, Discord, Slack, Email, Teams, Signal) funnel messages into a shared inbox. The Bridge Adapter enforces ACL, routes to the right persona, runs the TTS pipeline, and grades skills — per-chat-sequential, cross-chat-parallel. The WorkerEngine abstraction swaps the LLM backend without touching the compliance stack.

Full layer breakdown: docs/layer-model.md · Architecture 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. Tests run hermetically — Claude stubbed via ADAPTER_FAKE_CLAUDE=1, real bwrap where namespace isolation is the subject 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 of CorvinOS under a different license — including source-available licenses (Business Source License, Functional Source License, Elastic License v2) or a commercial license — without requiring further consent from contributors. This right is granted by every contributor as a condition of the CLA.md. Already-published Apache-2.0 releases are not affected; they remain Apache-2.0 forever. See CLA.md § 3 for the full terms.

"CorvinOS" and "Corvin" are project identifiers per Apache § 6 — the license does not grant trademark rights.