🌟 Overview
Most homelabs end up running a container manager, an uptime monitor and a status page side by side. Corvus does all of it in one container, with an embedded SQLite database and no external services.
| 🐳 Docker | 📈 Uptime & SSL | 🌐 Status Page | 🛰️ Multi-Node |
|---|
| Start, stop, logs, web terminal, Compose editor and 1-click deployments with rollback | HTTP/TCP/ping checks, SSL expiry, alerts to Discord, Telegram, Slack, email, ntfy and webhooks | Public, unauthenticated status page with incidents and maintenance notes | Outbound-only edge agent (<10 MB RAM) brings remote VPS nodes into the same panel |
How light is it? In production, next to 17 other containers, docker stats reports ~26 MB for Corvus. That comes from Native AOT compilation (no JIT, no runtime VM), a ~45 MB image and aggressive GC/malloc_trim tuning, explained below.
⚡ 10-Second Quick Start
Get Corvus up and running on your Docker host with a single command:
Option A: Single Docker Command (Corvus Hub)
docker run -d \
--name corvus \
--restart unless-stopped \
-p 8090:8090 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v corvus-data:/data \
ghcr.io/brhnshn/corvus:latest
Option B: Docker Compose (compose.yaml)
services:
corvus:
image: ghcr.io/brhnshn/corvus:latest
container_name: corvus
restart: unless-stopped
ports:
- "8090:8090"
environment:
- CORVUS_PORT=8090
- CORVUS_DATA_DIR=/data
- DOCKER_SOCKET=/var/run/docker.sock
- CORVUS_AUTH_ENABLED=true
- CORVUS_AUTH_USER=admin
- CORVUS_AUTH_PASS=corvus123
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- corvus-data:/data
volumes:
corvus-data:
docker compose up -d
Optional: socket proxy (tecnativa/docker-socket-proxy). Mounting docker.sock read-write is effectively root access to the host. Instead, Corvus can reach Docker over plain TCP (DOCKER_HOST=tcp://socket-proxy:2375, which takes precedence over DOCKER_SOCKET; TLS-enabled TCP is not supported). A commented example is included in docker-compose.yml. unix:// prefixes are also accepted.
Option C: Corvus Edge Agent (For Remote / Monitored Nodes)
Deploy the ultra-lightweight (<10 MB RAM) edge agent to monitor additional VPS nodes without opening inbound ports:
docker run -d \
--name corvus-agent \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v /proc:/host/proc:ro \
-v /sys:/host/sys:ro \
-e CORVUS_HUB_URL=wss://corvus.yourdomain.com \
-e CORVUS_SYSTEM_TOKEN=crv_live_... \
ghcr.io/brhnshn/corvus-agent:latest
Open your browser at http://localhost:8090 (or public status page at http://localhost:8090/status).
🎯 Architectural Scope & Philosophy
| Architectural Aspect | Corvus Design Approach | Traditional Heavy Stacks |
|---|
| Container Footprint | Single All-in-One Container (~45 MB image) | Multi-container setups (App + Database + Cache) |
| Idle Memory (RAM) | <30 MB RAM for all features combined (Workstation GC + malloc_trim) | One process per tool, each with its own memory budget |
| Database Dependency | Zero External DB (Embedded SQLite WAL, single .db file) | Some tools require a dedicated PostgreSQL or MongoDB |
| Docker Integration | Socket (:ro for monitoring only) or least-privilege socket proxy | Direct root-equivalent socket access |
| Combined Scope | Container Lifecycle + Extended Uptime & SSL + Public Status Page | Fragmented across 2-3 separate tools |
| Backup / Portability | Single-file copy or VACUUM INTO snapshot download | Database dumps (pg_dump, mongodump, volume exports) |
🔬 The Native AOT Engineering Advantage
Corvus is built from the ground up to challenge the misconception that modern enterprise frameworks require heavy containers:
- Zero CLR Virtual Machine Overhead: Compiled ahead-of-time (
PublishAot=true) directly to an optimized Linux x64/ARM64 ELF executable. There is no JIT compilation, dynamic IL generation, or heavy runtime metadata bundled in the image.
- Minimal Base Image: Operates on top of
mcr.microsoft.com/dotnet/runtime-deps:9.0 (chiseled minimal glibc), keeping the base OS layer at only ~13 MB.
- Aggressive Low-Memory Tuning:
- Non-concurrent workstation GC (
ServerGarbageCollection=false, DOTNET_gcConcurrent=0).
- Conservative allocation policy (
DOTNET_GCConserveMemory=9).
- Glibc arena constraints (
MALLOC_ARENA_MAX=2).
- Built-in
MemoryTrimmerBackgroundService that flushes SQLite connection pools and invokes native malloc_trim(0) every 3 minutes.
- Embedded SQLite with Write-Ahead Logging (WAL): Sub-millisecond reads/writes with automated rolling data retention cleanups (
RetentionCleanupService), ensuring database files never suffer from unmonitored disk bloat.
✨ Key Features
🏗️ Architecture
Corvus Architecture:
┌────────────────────────────────────────────────────────┐
│ Corvus Web Dashboard │
│ (React 19 + TypeScript + Tailwind v4 + Recharts) │
│ [Routes: Dashboard, Services, Containers, Uptime, │
│ Metrics, Settings, Public Status (/status)] │
└───────────────────────────┬────────────────────────────┘
│ REST API + SSE Stream (/api/stream/events)
┌───────────────────────────▼────────────────────────────┐
│ Corvus Core Engine │
│ ASP.NET Core Minimal API (.NET 9 Native AOT) │
├───────────────────────────┬────────────────────────────┤
│ Docker REST API Client │ SQLite + Dapper.AOT │
│ (SocketsHttpHandler) │ (DbUp Migrations 001-006) │
├───────────────────────────┴────────────────────────────┤
│ Core Services: │
│ - DockerLogDemuxer (Zero-alloc multiplexed demuxer) │
│ - NotificationService (Discord, Telegram, Ntfy, Web) │
│ - EventBroadcaster (Channel<ServerEventDto> for SSE) │
│ - AuthService (Zero-Trust SSO + Session Cookies) │
├────────────────────────────────────────────────────────┤
│ Background Services: │
│ - ContainerDiscoveryService (10s) │
│ - SystemMetricsCollector (15s) │
│ - UptimeCheckerService (TCP Ping, SSL, Snitch - 60s) │
│ - RetentionCleanupService (24h) │
└────────────────────────────────────────────────────────┘
🏷️ Docker Container Labels
Enhance your containers with Corvus metadata labels in your compose files:
labels:
- "corvus.name=Nextcloud Hub"
- "corvus.category=Cloud Storage"
- "corvus.description=Personal file sync and share"
- "corvus.url=https://cloud.example.com"
- "corvus.healthcheck=https://cloud.example.com/status.php"
- "corvus.icon=cloud"
- "corvus.ignore=false"
📡 API Endpoints Overview
| Method & Path | Description |
|---|
GET /api/dashboard/summary | Consolidated KPI overview |
GET /api/services | Service catalogue with ordering and SSL info |
PUT /api/services/reorder | Update visual service ordering |
GET /api/status-page | Public unauthenticated system status summary (services, 30-check sparklines & incidents) |
GET /api/incidents | List active and historical system incidents & maintenance notices |
POST /api/incidents | Create a new system incident or maintenance notice |
PUT /api/incidents/{id} | Update incident details, severity, or message |
POST /api/incidents/{id}/resolve | Mark an incident as resolved |
DELETE /api/incidents/{id} | Remove an incident record |
GET /api/uptime/{id}/daily-stats | 365-day daily uptime rollup statistics |
GET /api/containers | Docker containers list with state and ports |
GET /api/containers/{id}/stats | Live container CPU%, RAM, Net I/O |
GET /api/containers/{id}/logs | Snapshot container logs |
GET /api/containers/{id}/logs/stream | Real-time SSE container log stream |
POST /api/containers/{id}/start | Start container |
POST /api/containers/{id}/stop | Stop container |
POST /api/containers/{id}/pause | Pause container |
POST /api/containers/{id}/unpause | Unpause container |
POST /api/containers/{id}/restart | Restart container |
GET /api/push-monitors | List Dead Man's Snitch periodic push monitors |
POST /api/push-monitors | Create new Dead Man's Snitch monitor |
POST /api/push/{token} |
🛠️ Development & Building from Source
Prerequisites
Building the Project
- Frontend:
cd src/Corvus.Web
npm install
npm run build
- Backend:
cd ../Corvus.Api
dotnet run
- Running Automated Tests (441 Total):
# Backend Tests (375 passing xUnit tests)
dotnet test tests/Corvus.Api.Tests
# Frontend Tests (66 passing Vitest tests)
cd src/Corvus.Web && npm test
💡 Inspirations & Credits
Corvus is inspired by the architectural philosophies of pioneering open-source homelab, container management, and observability tools, re-imagined from the ground up as a single, ultra-lightweight .NET 9 Native AOT command center:
- Uptime Kuma — Health monitoring philosophy and status page concepts
- Beszel — Compact telemetry and system resource metrics approach
- Portainer — Container lifecycle management vision
- Coolify — Self-hosted deployment and developer experience philosophy
- Watchtower — Automated container update and image polling concepts
- Checkmate — Incident tracking and modern observability aesthetics
📄 License
This project is licensed under the MIT License.
