# CorvinOS – self-hosted agentic OS where EU AI Act and GDPR compliance by design

> Source: <https://github.com/CorvinLabs/CorvinOS>
> Published: 2026-07-01 16:02:43+00:00

[Overview](/CorvinLabs/CorvinOS/blob/main/docs/overview.md) ·
[Architecture](/CorvinLabs/CorvinOS/blob/main/docs/architecture.md) ·
[Audit & Compliance](/CorvinLabs/CorvinOS/blob/main/docs/audit-and-compliance.md) ·
[A2A Network](/CorvinLabs/CorvinOS/blob/main/docs/agent-communication.md) ·
[Engine Layer](/CorvinLabs/CorvinOS/blob/main/docs/engine-layer.md) ·
[Security](/CorvinLabs/CorvinOS/blob/main/docs/security.md) ·
[EU AI Act](/CorvinLabs/CorvinOS/blob/main/docs/eu-ai-act/README.md) ·
[Learning Objectives](/CorvinLabs/CorvinOS/blob/main/docs/ulo-learning-objectives.md)

**One install. Seven bridges. Any LLM.**

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

```
pip install corvinos && python -m corvinOS
```

**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.

See [INSTALLATION.md](/CorvinLabs/CorvinOS/blob/main/INSTALLATION.md) for the complete setup guide.

**Recommended — works identically on Linux, macOS, and Windows:**

```
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](https://pipx.pypa.io)— 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](/CorvinLabs/CorvinOS/blob/main/docs/overview.md)

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:**

| What | Where |
|---|---|
systemd services (`corvin-webui` , voice bridge, watchdog) |
`~/.config/systemd/user/` |
| Claude Code plugins + cache | `~/.claude/plugins/` |
| Voice config, API keys, service.env | `~/.config/corvin-voice/` |
| Audit logs, sessions, forge tools | `~/.corvin/` |
| Bridge virtual environments | `~/.corvin/bridges/*/venv/` |
| Web console build artifacts (source install only) | `<repo>/core/console/.../web-next/dist/` |

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.

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

| Mechanism | Layer | Regulation | Enforcement property |
|---|---|---|---|
Bot Disclosure |
L19 | EU AI Act Art. 50 | One-time per uid · structurally fail-closed · no bypass path |
Consent Gate |
L16 | GDPR Art. 6 & 7 | Deny-by-default · TTL-capped · re-validated at every consume |
Hash-Chained Audit |
L16 | GDPR Art. 30 & 32 | SHA-256 chain · offline-verifiable · daily auto-verify · chain write failure blocks request |
Audit-at-Rest Encryption |
L37 | GDPR Art. 32 | Segment rotation · `age` /`gpg` sealing · RFC 3161 TSA timestamping (opt-in) · 7-year retention |
Data Classification + Flow Guard |
L34 | EU AI Act Art. 14 | 4-stage matrix (PUBLIC/INTERNAL/CONFIDENTIAL/SECRET) · fail-closed at every engine-spawn callsite |
Egress Lockdown |
L35 | EU AI Act Art. 14 | Declarative `allowed_hosts` / `forbidden_hosts` · `default_action=deny` EU production preset |
GDPR Art. 17 Erasure |
L36 | GDPR Art. 17 | Cross-layer erasure orchestrator · pseudonymous subject IDs · audit trail de-linked, not deleted |
Acceptable-Use Gate |
L44 | EU AI Act Art. 5 & 50 | SHA-256-anchored house-rules policy · no disable switch · no tenant override |
Compliance-Zone Routing |
ADR-0007 | EU AI Act Art. 14 | `allowed_engines` / `forbid_engines` per tenant · `data_residency` in `tenant.corvin.yaml` |

**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](/CorvinLabs/CorvinOS/blob/main/docs/eu-ai-act/README.md) · [docs/audit-and-compliance.md](/CorvinLabs/CorvinOS/blob/main/docs/audit-and-compliance.md)

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.

| Engine | Provider | Key property |
|---|---|---|
Claude Code |
Anthropic Claude (Pro/Max) | Full feature set — hooks, skills, MCP, mid-stream inject |
Codex CLI |
OpenAI | MCP + stream JSON |
OpenCode |
Ollama, OpenRouter, Google | Provider-agnostic |
Hermes |
NousResearch via local Ollama | Zero network egress · L34 CONFIDENTIAL-capable · no API key |
Copilot CLI |
GitHub Copilot Business/Enterprise | Zero incremental cost · worker/delegation only |

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.

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.

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.

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
```

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](/CorvinLabs/CorvinOS/blob/main/docs/layer-model.md) · Architecture diagrams: [docs/diagrams/](/CorvinLabs/CorvinOS/blob/main/docs/diagrams) · Full documentation: [docs/overview.md](/CorvinLabs/CorvinOS/blob/main/docs/overview.md)

```
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.

By opening a pull request you accept [ CLA.md](/CorvinLabs/CorvinOS/blob/main/CLA.md). Every merged contribution requires a corresponding entry in

[. See](/CorvinLabs/CorvinOS/blob/main/CLA-SIGNATORIES.md)

`CLA-SIGNATORIES.md`

[for the full workflow.](/CorvinLabs/CorvinOS/blob/main/CONTRIBUTING.md)

`CONTRIBUTING.md`

Licensed under the [Apache License, Version 2.0](/CorvinLabs/CorvinOS/blob/main/LICENSE).

**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](/CorvinLabs/CorvinOS/blob/main/CLA.md). Already-published Apache-2.0 releases are not affected; they remain Apache-2.0 forever. See

[for the full terms.](/CorvinLabs/CorvinOS/blob/main/CLA.md#3-relicense-right-the-load-bearing-clause)

`CLA.md § 3`

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