CorvinOS
A self-hosted AI workflow OS that routes models, learns from outcomes, and records auditable decisions.
- Source repo
- CorvinLabs/CorvinOS
- Stars
- ★ 11
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 67/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Development teams using Claude Code, Codex, or Hermes Agent that want self-hosted workflows reachable through Discord, Telegram, WhatsApp, Slack, or email.
- Not a fit if
- Teams requiring independently verified compliance certification or cost guarantees
- Users unwilling to run a local service and retain audit state
- Teams that only need a simple chatbot without a learning loop
- Source review
- 67/100 · Some gaps
What does this agent do, and when should you use it?
CorvinOS is a self-hosted system for AI workflows that can connect Claude Code, Codex, or Hermes Agent and expose a local browser console. Its four-layer control plane consists of DataHub, Creator 2.0, the Learning Daemon, and the Dashboard, covering ingestion, skill generation, feedback learning, and operational visibility. Requests are routed among Haiku, Sonnet, and Opus, after which outcomes feed a six-dimensional loss assessment and weight-update cycle. Versioned Python skills are its execution units; they run deterministically, may call an LLM, and produce quality measurements, routing updates, and hash-chained audit events. Installers for macOS, Linux, Windows, and WSL create an isolated Python environment, add offline voice models, and start the console on 127.0.0.1. The repository presents the architecture as GDPR- and EU AI Act-compliant, although the supplied material contains no independent certification or audit.
DataHub ingests memory, files, RAG, and MCP sources, performs quality scoring and security scanning, and emits scored data manifests. Creator 2.0 generates skills through 12 structured phases while tracking loss at each phase; skills execute as Python programs, can optionally invoke an LLM, and compose through DAG-validated imports. The Smart Router assigns requests to Claude Haiku, Sonnet, or Opus, while each execution emits loss components for data quality, generation quality, user satisfaction, efficiency, learning-loop health, and system health. The Learning Daemon processes feedback, attributes outcomes to data sources, and updates weights and the routing map with a documented learning rate of 0.01. The Dashboard displays skill lifecycles, learning metrics, token allocation, and the audit chain, and produces GDPR-oriented reports. The described audit path stores metadata rather than prompts and includes consent gates, PII flagging, secret redaction, and cascading erasure with proof logging.
- Development teams using Claude Code, Codex, or Hermes Agent that want self-hosted workflows reachable through Discord, Telegram, WhatsApp, Slack, or email.
- Organizations making many Claude calls that want workload-specific allocation across Haiku, Sonnet, and Opus.
- Regulated teams that need records of model decisions, source attribution, consent, and erasure actions for audit preparation.
- Platform engineers who want repeatable AI workflows packaged as versioned, composable, DAG-validated Python skills.
- Teams needing local voice interaction in one of the documented Piper languages, with speech recognition that requires no per-language download.
- Maintainers who want a fail-closed pull, console-build, critical-E2E-test, and push cycle before updating main.
How do you install or deploy this agent?
The quick start creates a fresh Python environment, so the source explicitly says that system Python is unnecessary. Installation requires network access to download the repository, packages, and voice models. The supplied material does not specify API keys or other credentials required for the first model invocation.
On macOS, Linux, or WSL:
curl -fsSL https://raw.githubusercontent.com/CorvinLabs/CorvinOS/main/install.sh | shOn Windows PowerShell:
irm https://raw.githubusercontent.com/CorvinLabs/CorvinOS/main/install.ps1 | iexTo install from a local checkout:
git clone https://github.com/CorvinLabs/CorvinOS.git
cd CorvinOS
./install.shFor a local checkout on Windows:
install.ps1 -Editable .\To prevent automatic Claude Code installation:
bash install.sh --no-claude-codeFor the lightweight console-only preset:
bash install.sh --preset minimalHow do you use this agent?
The installer starts the local service, verifies that the application shell returns HTTP 200, checks that local login issues a session cookie, and then opens:
http://127.0.0.1:8765/console/To permit pairing over the LAN, select that mode during installation:
bash install.sh --lanTo refresh an existing installation, rebuild, restart, and verify it:
sh update.shTo rebuild and restart without downloading new code:
sh update.sh --rebuild-onlyThe Windows update command is:
powershell -ExecutionPolicy Bypass -File update.ps1Preview uninstall targets first with:
bash uninstall.sh --dry-runA normal uninstall stops services, archives non-downloadable state such as secrets, bridge pairings, the audit chain, sessions, and voice models, and then scans for leftovers:
bash uninstall.shWhat are this agent's strengths and limitations?
- Combines DataHub, the 12-phase Creator 2.0, the Learning Daemon, and the Dashboard into an ingestion-to-feedback control plane.
- The updater verifies the new console and API and automatically rolls back failures; developer checkouts preserve and reapply local changes.
- The documented audit design covers hash-chained events, source attribution, secret redaction, PII flagging, consent gates, and proof-logged deletion.
- Installers cover macOS, Linux, Windows, and WSL, create their own Python environment, and verify the console and login before declaring success.
- Downloadable Piper voices enable offline speech output for a documented set of languages.
- The routing examples and cost model focus on Claude Haiku, Sonnet, and Opus; equivalent routing configuration for other model providers is not documented.
- The stated 60–80% savings, 2–5% quality gains per cycle, two-to-three-week convergence, and 99.9% SLA are project claims without independent benchmarks in the supplied material.
- The complete learning model requires ongoing outcomes and user feedback plus persistent weights, audit-chain data, sessions, and other local state.
- Installation and updates download code, dependencies, and models and start local services, so security-sensitive organizations should review the remote scripts before execution.
- The material does not provide concrete first-time configuration steps for model credentials, messaging bridges, or email, leaving integration effort uncertain.
How does this agent compare with similar options?
Compared with sending every request to one expensive model, CorvinOS routes work among Haiku, Sonnet, and Opus and adjusts its weights from feedback; the tradeoff is operating a learning daemon, retaining audit state, and accumulating enough samples. The source also contrasts all-Opus and all-Haiku strategies: the former is presented as high-quality but expensive, while the latter is inexpensive but lower-quality in its example. CorvinOS aims to learn a cost-quality point between them. These cost and quality figures are repository examples rather than independent evaluations.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| CorvinOS This agent | 67 · Some gaps | CLIFree + model costs | ★ 11 | today | Python | Codex · Claude Code |
| PenguinHarness | 52 · Major gaps | Desktop appFree + model costs | ★ 2.4k | 3d ago | TypeScript | OpenAI API · Claude API |
| Entroly | 68 · Some gaps | CLIFree + model costs | ★ 469 | 2d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| OMA Open Multi-Agent Runtime | 55 · Major gaps | CLIFree + model costs | ★ 7k | 1d ago | TypeScript | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
least_privilege=2: The console defaults to 127.0.0.1, third-party entry points are not imported without opt-in, and CI permissions are scoped; however, full runtime privileges, bridge permissions, and outbound-network scope are not shown. user_confirmation=2: Uninstall prompts once, extensions require opt-in, and the README asserts fail-closed consent gates; per-action confirmation for autonomous routing, learning, and outbound messaging is not evidenced in code. data_flow_transparency=2: DataHub ingestion, model routing, feedback, auditing, and some online voice flows are described; destinations, processors, retention, and handling for Discord, Telegram, WhatsApp, Slack, email, and telemetry remain incomplete. sensitive_data_handling=2: Secret redaction, PII flagging, metadata-only auditing, deletion proofs, mode-600 backups, and test audit isolation are described; most controls are assertions, with no supplied implementation for secret storage, encryption, or erasure. dependency_security=1: Dependencies are extensively justified and packaging exclusions reduce accidental disclosure, but most versions have only lower bounds, Actions are not commit-pinned, installers execute mutable main through shell pipelines, and no lockfile, vulnerability scan, or artifact verification is shown. external_effects=2: Installation, startup, update, deletion, maintainer push effects, and several exit codes are explicit; approval and scoping for connector, browser, and uploader actions are not shown. rollback=3: Failed updates automatically restore prior code/build, preserve old HEAD and local changes, while uninstall backs up non-downloadable state with restoration instructions and distinguishes rollback failure; the evidence is unusually concrete. source_attribution=2: License, author, repository, and ADR reference paths are identified, and data-source attribution is claimed; the external ADR contents are absent, publisher identity remains unknown, and third-party attribution is incomplete.
self_consistency=1: Installation, update, and audit narratives are detailed, but the README says production-ready, guaranteed convergence, and 99.9% SLA while package metadata says Beta; numerous proven/measured/guaranteed statements lack accompanying results. dependency_availability=2: Supported Python versions, platforms, required versus optional dependencies, online/offline fallbacks, and previously missing dependencies are documented concretely; broad ranges, the external ffprobe requirement, external ADRs, and online services still permit drift. failure_messages=3: Install, update, uninstall, unconfigured YouTube, and CI paths describe diagnostics, exit codes, or explicit errors, and workflows provide actionable PR failure guidance; no material gap is evident in the supplied files.
audience_and_scenarios=3: The developer/self-hosted-builder audience is explicit, with console, headless, messaging, voice, browser, workflow, compliance-report, and maintainer scenarios plus layered reading paths. capability_boundaries=2: Base versus optional capabilities, end-user versus maintainer updates, online versus offline voice, and credential-dependent YouTube support are distinguished; boundaries around autonomous learning, model decisions, and connector actions remain vague. trigger_precision=2: Extension entry points are enumerated but not imported absent explicit per-name or global opt-in, and CI path triggers are precise; end-user agent triggers, channel authorization, and false-trigger prevention are not evidenced. environment_fit=3: macOS, Linux, Windows/WSL, Python 3.10–3.13, loopback defaults, LAN mode, OS trust stores, platform dependencies, and installation presets are handled in substantial detail.
information_architecture=3: The README clearly separates quick start, lifecycle operations, architecture, scenarios, technology, and document navigation; packaging, entry points, and CI responsibilities are also well organized. install_notes=3: Remote and checkout installs, Windows usage, options, verification, updates, uninstall, backup, restoration, managed source trees, and PyPI/main differences are covered. naming_stability=2: corvin/corvinos compatibility aliases, explicit entry points, and version 2.0.0 aid stability; CorvinOS, CorvinVS, Forge 2.0, and multiple legacy directory names indicate migration debt. examples_and_faq=2: Commands, architecture flows, cost examples, and a question index are present, but complete agent conversations, bridge setup examples, and representative end-to-end outputs are absent. known_limitations=1: PyPI lag, online voice, ffprobe, OAuth, and optional-dependency constraints appear piecemeal; there is no consolidated limitations section, and strong production/compliance claims obscure Beta status and unverified assumptions. license=3: The full Apache-2.0 text and copyright statement are present and agree with package metadata and the sample package manifest. versioning_changelog=2: Version 2.0.0, a CHANGELOG link, dependency bounds, and update procedures exist; the changelog content was not supplied, and default installation from mutable main weakens revision stability. maintenance_responsibility=2: An author email, security contact, issue repository, and maintainer release workflow are provided; publisher identity is unverified, and team structure, support commitments, and response targets are unspecified.
output_usability=2: Console, CLI, headless operation, reports, audit artifacts, and multiple delivery bridges provide concrete output channels, but no real agent output or implementation evidence establishes everyday result quality. marginal_value=2: The combination of self-hosting, multichannel access, routing, auditability, offline voice, and rollback offers plausible added value; differentiation from existing orchestrators is supported mainly by the project's own narrative. cost_benefit=1: Pricing assumptions, routing proportions, and ROI examples are supplied, but the claimed 60–80% savings, 2–5% quality gains, two-to-three-week convergence, and instant payback lack datasets, methods, or result artifacts and omit operational costs.
claim_traceability=1: Named verification scripts, ADR identifiers, test paths, and technical-document paths offer leads for some claims; decisive compliance, SLA, cost, quality, and convergence claims lack underlying measurements or complete implementation evidence. cross_source_corroboration=2: pyproject, LICENSE, SECURITY, CI workflows, and the test fixture partly corroborate cross-platform, dependency, entry-point, audit, and licensing statements; learning effectiveness and regulatory compliance receive no substantive independent corroboration. fact_inference_separation=0: Architecture intentions, mathematical extrapolations, and marketing scenarios are repeatedly labeled proven, measured, guaranteed, or compliant without the corresponding evidence, so facts, forecasts, and inferences are not reliably separated.
- Do not treat the GDPR/EU AI Act, 99.9% SLA, convergence, cost, or quality claims as verified; obtain control implementations, legal mappings, measurement data, and independent audit evidence before deployment.
- Avoid executing curl|sh or irm|iex against mutable main; pin the reviewed revision, verify downloaded artifacts, and inspect installers in an isolated environment.
- Before connecting real Discord, Telegram, WhatsApp, Slack, email, browser, or upload accounts, verify permission scope, outbound confirmation, retention, deletion, telemetry, and third-party processing.
- Broad dependency ranges and CI Actions not pinned by commit permit supply-chain drift; production deployments should use locked dependencies, signed artifacts or an SBOM, and vulnerability scanning.