CorvinOS Installation Guide

Quick Start

System Requirements

Python	not required up front — the installer bootstraps its own via uv (3.10+ if you install manually)
OS	Linux (Ubuntu 22.04+ recommended), macOS 12+ (Monterey), Windows 10 build 19041+ or Windows 11
Disk	2–7 GB (the local Hermes model is 1.4–5.2 GB; plus the Whisper STT + Piper TTS voice models)
RAM	4 GB minimum. The installer picks the local model by available RAM — under ~6 GB it installs the lighter qwen3:1.7b, 6–12 GB gets the mid-size qwen3:4b, and ≥12 GB gets qwen3:8b; the running engine automatically uses whichever model is actually installed.

Bridges only (Discord, WhatsApp, Telegram, Slack, Email) additionally require Node.js 20+ and systemd (Linux) or launchd (macOS). On Windows, bridges require WSL2.

Install

Linux / macOS — one-liner (recommended):

curl -fsSL https://corvin-labs.com/install.sh | bash

Windows — PowerShell one-liner:

irm https://corvin-labs.com/install.ps1 | iex

DNS error? If PowerShell reports irm : The remote name could not be resolved: 'corvin-labs.com', the domain itself is up — this is a local DNS resolution issue on your machine (a stale negative-cache entry, VPN/corporate DNS, or a flaky resolver). Try, in order:

1. Flush the local DNS cache and retry: ipconfig /flushdns
2. If it still fails, use the GitHub-hosted copy of the same script instead (identical content, different domain):

   irm https://raw.githubusercontent.com/CorvinLabs/CorvinOS/main/install.ps1 | iex
   

3. Still failing? Your resolver may be blocking/mis-resolving both domains — temporarily switch your network adapter's DNS to 1.1.1.1 (Cloudflare) or 8.8.8.8 (Google) and retry.

Both one-liners bootstrap the uv runtime (which brings its own Python — no system Python, pip, or package manager needed), then uv tool install corvinos into an isolated tool environment and add it to your PATH. They also provision the local Hermes model and the voice (STT + TTS) models so the install is voice-ready out of the box. Equivalent to doing it manually if you already have uv:

uv tool install corvinos
corvinos-serve          # opens http://localhost:8765

(With a system Python + pip you can also pip install corvinos, but the uv path above is what the one-liners use and needs no pre-installed Python.)

Hermes (local AI, no cloud required) is automatically detected. If Ollama is not yet installed, the console's Settings → Engine page has a one-click bootstrap button.

---

Installation Methods

Method 1: From PyPI (Recommended)

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

Note: corvinos-serve (web console + Hermes auto-detect) works fully from the pip wheel. The full corvin-install flow — which registers messaging-bridge daemons (Discord/WhatsApp/…) and their system services — requires a git checkout (see Method 3).

Method 2: With Hermes (fully local, no API key required)

# Install Ollama first
curl -fsSL https://ollama.com/install.sh | sh   # Linux
brew install ollama                              # macOS
# Windows: winget install Ollama.Ollama

# Then install CorvinOS and start
pip install corvinos
corvinos-serve
# The console auto-detects Ollama and selects the right model for your RAM.
# Or use the one-click bootstrap: Settings → Engine → Bootstrap Hermes

Method 3: From Source (required for bridges)

git clone https://github.com/CorvinLabs/CorvinOS.git
cd CorvinOS
pip install -e .
corvin-install

---

Installation Modes

Interactive Installation

corvin-install

Step-by-step flow:

1. Platform detection (auto)
2. Bridge selection:
   • Choose to set up a bridge now or skip for later
   • If now: pick from a numbered list (1–5) or select all
   • If skip: configure bridges anytime via Settings → Bridges in the web console
3. Enter credentials for selected bridges (bot tokens, API keys)
4. Confirm and register services

Bridge selection options:

• Skip (answer n): configure bridges later via web UI
• Select one (answer y, then 1–5): Discord, WhatsApp, Telegram, Slack, or Email
• Select all (answer y, then a): all five bridges at once

Non-Interactive Installation

corvin-install --yes

Installs all bridges without prompts. Requires pre-configured credentials in ~/.config/corvin-voice/.

Restore

corvin-restore

Force-rebuilds the web console from scratch (npm install && npm run build) and restarts every service. Use after pulling UI changes or when the console shows a 503.

Uninstall

corvin-uninstall

Prompts whether to keep data files (~/.corvin/).

---

Platform-Specific Details

Linux

Tested on: Ubuntu 22.04 LTS and 24.04 LTS. Expected to work on Debian 11+, Fedora 38+, and other systemd-based distributions. Non-systemd systems (Alpine, NixOS, etc.) are not currently supported by the service manager.

Package manager support: apt (Ubuntu/Debian), dnf (Fedora/RHEL), pacman (Arch). If none is detected, the installer prints a manual install hint.

Requirements:

• systemd user session (systemctl --user)
• No sudo required

What gets installed:

~/.config/systemd/user/
├── corvin-adapter.service
├── corvin-bridge-discord.service
├── corvin-bridge-whatsapp.service
└── ...

Check installation:

systemctl --user status corvin-*
journalctl --user -u corvin-adapter -f

Restart services:

systemctl --user restart corvin-adapter

macOS

Tested on: macOS 13 (Ventura) and 14 (Sonoma). Minimum supported version: macOS 12 (Monterey), which is the floor for current Homebrew and Python 3.10 wheel builds on both Intel and Apple Silicon.

Requirements:

• Homebrew (brew) for dependency installation
• No elevation required

What gets installed:

~/Library/LaunchAgents/
├── com.corvin.adapter.plist
├── com.corvin.bridge-discord.plist
└── ...

Check installation:

launchctl list | grep corvin
log stream --predicate 'process == "python"'

Restart services:

launchctl stop com.corvin.adapter
launchctl start com.corvin.adapter

Windows

Supported: Windows 10 build 19041 (May 2020 Update) and Windows 11.

What works natively (pip install, no WSL2):

Feature	Status
pip install corvinos	✅ Supported
corvinos-serve (web console)	✅ Opens browser at http://localhost:8765
Hermes / Ollama	✅ winget install Ollama.Ollama
Bridges (Discord / WhatsApp / Telegram / …)	⚠️ Requires WSL2 — see below

Quick start (native):

pip install corvinos
corvinos-serve
# Console opens at http://localhost:8765

PATH note: With a system-wide Python install, pip places corvin* scripts in the user Scripts folder (%APPDATA%\Python\Python3xx\Scripts), which is not on PATH by default. Either add it to PATH, or use the fallback:

py -m ops.launcher.corvin.serve_entry --no-browser

The one-liner installer (irm https://corvin-labs.com/install.ps1 | iex) handles PATH setup automatically.

Hermes (local AI, no API key required):

winget install Ollama.Ollama
pip install corvinos
corvinos-serve
# Or: Settings → Engine → Bootstrap Hermes in the browser

Bridges on Windows → WSL2:

Bridges require bash and systemd, which are not available on native Windows. Install them via WSL2 + Ubuntu:

# One-time setup (Admin PowerShell):
wsl --install
# Then inside Ubuntu:
pip install corvinos
corvin-install

Health check:

curl http://localhost:8765/healthz   # Is the console running?
ollama list                          # Is Ollama running?

---

Directory Structure

After installation:

~/.corvin/                                 # Corvin home
├── bridges/
│   ├── discord/
│   │   ├── venv/                          # Isolated Python env
│   │   ├── settings.json                  # Discord bot token
│   │   └── ...
│   └── whatsapp/
│       └── ...
├── tenants/_default/
│   ├── global/
│   ├── sessions/
│   └── voice/
├── logs/
└── audit.jsonl                            # Hash-chained audit log

~/.config/corvin-voice/
├── installer.json                         # Installation config
├── config.json                            # User preferences
└── secrets.json                           # Encrypted credentials

~/.config/systemd/user/                    # Linux only
└── corvin-*.service

~/Library/LaunchAgents/                    # macOS only
└── com.corvin.*.plist

---

Configuration

Bridge Credentials

Option 1: Web Console (recommended)

1. Open http://localhost:8765
2. Go to Settings → Bridges
3. Select a bridge, enter credentials, save and test

Option 2: Manual

vim ~/.corvin/bridges/discord/settings.json

Example settings.json:

{
  "bot_token": "YOUR_DISCORD_BOT_TOKEN",
  "guild_id": "YOUR_GUILD_ID",
  "channel_id": "YOUR_CHANNEL_ID"
}

After editing, restart the bridge:

systemctl --user restart corvin-bridge-discord   # Linux
launchctl stop com.corvin.bridge-discord         # macOS
schtasks /run /tn "CorvinOS\bridge-discord"      # Windows (WSL2)

Environment Variables

Variable	Purpose	Default
CORVIN_HOME	Override Corvin home path	~/.corvin/
CORVIN_TENANT_ID	Select tenant	_default

---

Verification

Check Services

Linux:

systemctl --user status corvin-adapter

macOS:

launchctl list | grep corvin

Windows:

schtasks /query /tn "CorvinOS\adapter" /v

Check Logs

journalctl --user -u corvin-adapter -n 50 -f   # Linux
log stream --level debug                        # macOS
eventvwr.msc                                    # Windows → Application log

---

Troubleshooting

Python not found or wrong version

python --version    # must be 3.10+
python3 --version

If missing: download from https://www.python.org/downloads/ (check "Add to PATH" on Windows).

pip install fails

pip install --upgrade pip
pip install corvinos --force-reinstall

Services not starting

Linux:

systemctl --user status corvin-adapter
journalctl --user -u corvin-adapter -n 20

macOS:

plutil -lint ~/Library/LaunchAgents/com.corvin.adapter.plist
log stream --predicate 'process == "python"'

Windows:

schtasks /query /tn "CorvinOS\adapter" /v
eventvwr   # Application log

Node.js not found

Node.js 20+ is only required for bridges (Discord, WhatsApp, etc.), not for corvinos-serve.

brew install node          # macOS
sudo apt install nodejs    # Ubuntu/Debian (then verify version ≥ 20)
winget install OpenJS.NodeJS.LTS   # Windows

Or use nvm (Linux/macOS): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash && nvm install --lts

Audit chain verification failed

voice-audit verify

This is a CRITICAL security event. Consult docs/audit-and-compliance.md.

---

Restore

Force-rebuild the web console and restart all services:

corvin-restore

Useful after pulling source changes that include frontend updates, or when the console returns 503.

---

Uninstalling

corvin-uninstall   # removes services; prompts whether to keep ~/.corvin/ data

To reinstall later with existing data:

pip install corvinos
corvin-install     # detects existing data automatically

---

Multi-Tenant Setup

# Default tenant (created automatically)
corvin-install

# Additional tenant
export CORVIN_TENANT_ID=production
corvin-install
# Creates: ~/.corvin/tenants/production/

---

Next Steps

1. Configure bridges → Settings → Bridges in the web console, or edit ~/.corvin/bridges/<bridge>/settings.json
2. Test connections → send a test message to each bridge
3. Check logs → journalctl --user -u corvin-adapter -f (Linux) or the console Logs page
4. Backup → back up ~/.corvin/ periodically
5. Updates → pip install --upgrade corvinOS

---

Support & Issues

• GitHub Issues: https://github.com/CorvinLabs/CorvinOS/issues
• Discussions: https://github.com/CorvinLabs/CorvinOS/discussions
• Documentation: docs/

---

Related Documentation

• INSTALL-UNIVERSAL.md — Detailed platform guide
• OLLAMA-RELEASE.md — Release & publishing
• audit-and-compliance.md — GDPR & compliance