Corvus

---

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

1. 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.
2. 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.
3. 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.
4. 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.

---

This is the beginning of the README. Read the rest at the original. Read the full README ↗