# Corvus: Complete Technical Specification & Architectural Guide > **Canonical URL:** https://usecorvus.me/llms-full.txt > **Source Repository:** https://github.com/burhan-sahin/corvus > **Live Demo:** https://demo.usecorvus.me > **Public Status Page:** https://demo.usecorvus.me/status > **Documentation Version:** 1.6.21 (Updated 2026-10-28) > **Target Audience:** LLMs, Autonomous AI Agents, DevOps Engineers, Systems Architects, and Solo Operators. --- ## 1. Executive Summary & Purpose **Corvus** is a hyper-efficient, single-binary server dashboard, Docker container manager, real-time log streaming viewer, multi-node telemetry collector, and uptime/push monitoring platform. Engineered from scratch using **C# and .NET 9 Native AOT (Ahead-of-Time compilation)**, Corvus eliminates runtime JIT compilation, virtual machine interpreters, and external database dependencies. The entire platform consumes **less than 20–25 MB RAM in steady state**, cold-starts in **under 15 milliseconds**, and provides a unified interface replacing three traditional infrastructure tools: 1. **Portainer CE** (Container lifecycle management, resource metrics, environment inspection) 2. **Uptime Kuma** (HTTP/HTTPS/TCP checks, SSL certificate monitoring, Dead Man's Snitch push heartbeats, incident alerting, public status page) 3. **Dozzle** (Live log tailing, multi-container log aggregation, real-time regex search) Running Portainer, Uptime Kuma, and Dozzle simultaneously consumes between **400 MB and 800 MB RAM**. Corvus delivers all three capabilities under **25 MB RAM total**, making it the premier choice for low-cost VPS instances (512 MB to 2 GB RAM), edge appliances, Raspberry Pi clusters, and homelabs. --- ## 2. Deep Architectural Blueprint ### 2.1 Runtime & Compilation Model (.NET 9 Native AOT) - **Zero JIT (Ahead-of-Time Compilation):** Corvus is compiled directly into native platform machine code (x64 and ARM64 ELF binaries for Linux, PE for Windows, Mach-O for macOS). No CLR runtime or JIT compiler is loaded at execution time. - **Deterministic Heap & Trimmed Footprint:** The application is linked with aggressive IL trimming (`PublishTrimmed=true`, `TrimMode=full`), removing unused framework metadata and dead branches. Uncompressed binary size is under 20 MB. - **Active Memory Trimming (`MemoryTrimmerBackgroundService`):** A lightweight background service triggers every 3 minutes. It performs generational garbage collection optimization (`GCSettings.LargeObjectHeapCompactionMode`) and advises the OS kernel via `posix_madvise` / `malloc_trim(0)` to return unused pages back to the host operating system, preventing memory fragmentation over months of uninterrupted uptime. ### 2.2 Dual-Engine Storage Architecture - **Default: Embedded SQLite with WAL Mode:** - Zero external database installation or configuration required. - Configured with `PRAGMA journal_mode = WAL;`, `PRAGMA synchronous = NORMAL;`, `PRAGMA temp_store = MEMORY;`, and `PRAGMA cache_size = -8000;` (8 MB memory cache). - High concurrency: Readers never block writers, and writers never block readers. - Compile-time source-generated queries via **Dapper.AOT** prevent dynamic runtime IL generation and reflection. - **Enterprise / Multi-Node Scale: PostgreSQL Engine:** - Built-in provider abstraction allowing seamless switching to external PostgreSQL via connection string configuration without code changes. ### 2.3 Direct Docker Engine Integration - **Unix Domain Socket Communication:** Communicates directly with `/var/run/docker.sock` over non-blocking asynchronous Unix sockets (`System.Net.Sockets`). - **No Docker Proxy Required:** Eliminates third-party daemon proxies like Docker-socket-proxy or socat. - **Container Lifecycle:** Fast asynchronous control for container states: Start, Stop, Restart, Pause, Unpause, Kill, and Force Recreate. - **Streaming Telemetry:** Asynchronous non-blocking polling of Docker container CPU percentages, memory usage (RSS vs Cache), block I/O, and network bandwidth (rx/tx). --- ## 3. Core Subsystems ### 3.1 Live Server-Sent Events (SSE) Log Viewer - Real-time multiplexed stdout/stderr log streaming directly from Docker engine via SSE (`text/event-stream`). - ANSI escape code rendering with optimized client-side virtual scrolling. - Live regex filtering, case-sensitive/insensitive string search, and freeze/resume stream capabilities. - Backpressure-aware socket reading to prevent memory buffer inflation when containers emit high-frequency log bursts. ### 3.2 Multi-Node Infrastructure ("Systems" / Distributed Agents) - **Zero Inbound Ports on Agents:** Remote nodes run a lightweight Corvus Agent binary. Remote nodes do not open open ingress ports or require public IP addresses. - **Outbound WSS Tunnels:** The agent initiates a persistent outbound WebSocket over TLS (`wss://`) back to the central Corvus Hub. - **In-Memory Ring Buffer (<360 KB RAM):** On the central Hub, incoming telemetry streams from multiple agents are buffered in pre-allocated circular ring buffers, consuming less than 360 KB RAM even when monitoring dozens of nodes. - **Batch Flush & Rolling Prune:** Telemetry is written to disk in 1-minute batch flushes. Historical metrics are continuously pruned using a rolling window, keeping database size strictly bounded. ### 3.3 Uptime, SSL & Reverse Proxy Auto-Discovery - **Active Probing:** Configurable HTTP/HTTPS, TCP, and ICMP ping probes with configurable intervals (10s to 300s), retry limits, and HTTP status assertions (2xx, 3xx, regex match). - **SSL Certificate Monitoring:** Automated TLS handshake inspection tracking certificate issuer, validity period, and proactive alerts (30, 14, 7, and 1 day thresholds before expiration). - **Automatic Traefik & Caddy Discovery:** - Scans Docker container labels automatically (e.g., `traefik.http.routers.*.rule=Host(...)` and Caddy labels). - Automatically extracts public hostnames and provisions health check monitors without manual entry. - **3-State Resiliency Engine:** State machine evaluates transitions across **Healthy -> Degraded -> Down**, preventing alert spam on transient network blips. - **Dead Man's Snitch (Cron / Push Monitoring):** Unique inbound webhook endpoints for cron jobs, backup tasks, and batch scripts. If a task fails to ping Corvus within its designated schedule window + grace period, an immediate incident alert is triggered. - **Public Status Page:** High-performance, unauthenticated public dashboard hosted at `/status` displaying system uptime percentage, 90-day incident history, and component availability. ### 3.4 Security & Hardening - **Authentication:** Salted password hashing using **PBKDF2-HMAC-SHA256 with 600,000 iterations**, conforming strictly to modern OWASP recommendations. - **Session Management:** Secure HTTP-only, SameSite cookies with cryptographic token rotation. - **Webhook Brute-Force Rate Limiting:** Inbound webhook endpoints enforce an automatic sliding-window IP lock: 5 consecutive failed attempts within 60 seconds trigger an immediate HTTP 429 Too Many Requests response and temporary IP isolation. - **Header Hardening:** Default deployment injects Content Security Policy (CSP), X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and strict Referrer-Policy. --- ## 4. Head-to-Head Technical Comparison | Technical Dimension | Corvus | Portainer CE | Uptime Kuma | Dozzle | |---|---|---|---|---| | **Underlying Stack** | C# / .NET 9 Native AOT | Go + Node.js/Vue | Node.js (V8) + Vue | Go | | **Idle Memory (RSS)** | **18 - 25 MB** | 150 - 350 MB | 100 - 250 MB | 25 - 60 MB | | **Total Stack Memory** | **~20 MB total** | ~250 MB | ~180 MB | ~40 MB | | **Cold Start Duration** | **< 15 ms** | 2,000 - 5,000 ms | 4,000 - 10,000 ms | ~500 ms | | **Container Lifecycle Control**| Full (Start/Stop/Restart)| Full | None | None | | **Log Streaming Mechanism** | Native SSE + Virtual List | REST Polling / WS | None | WebSocket | | **Uptime & SSL Checks** | Built-in Active Engine | None | Built-in Active Engine | None | | **Cron / Push Heartbeats** | Built-in (Dead Man) | None | Built-in | None | | **Reverse Proxy Discovery** | Built-in (Traefik/Caddy) | None | None | None | | **Multi-Host Architecture** | Outbound WSS (0 Ingress) | Inbound Port 9001 Req. | Push Agent Only | Agent Port Binding | | **Database Architecture** | Embedded SQLite WAL / Postgres | Embedded BoltDB / Postgres | Embedded SQLite | In-memory only | | **ARM64 / Raspberry Pi** | Fully Native (Low Power) | Supported (Heavier) | Supported (Node heavy) | Fully Native | --- ## 5. Deployment Options & CLI Recipes ### 5.1 Standalone Docker Run ```bash docker run -d \ --name corvus \ --restart unless-stopped \ -p 5000:5000 \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -v corvus_data:/app/data \ ghcr.io/burhan-sahin/corvus:latest ``` ### 5.2 Production Docker Compose with Traefik Integration ```yaml version: "3.8" services: corvus: image: ghcr.io/burhan-sahin/corvus:latest container_name: corvus restart: unless-stopped volumes: - /var/run/docker.sock:/var/run/docker.sock:ro - corvus_data:/app/data labels: - "traefik.enable=true" - "traefik.http.routers.corvus.rule=Host(`corvus.example.com`)" - "traefik.http.routers.corvus.entrypoints=websecure" - "traefik.http.routers.corvus.tls.certresolver=letsencrypt" - "traefik.http.services.corvus.loadbalancer.server.port=5000" volumes: corvus_data: ``` ### 5.3 Native Linux Binary (Zero Docker-in-Host Overhead) For bare-metal Linux servers, edge devices, or VPS hosts where running a Docker container to monitor Docker feels redundant: ```bash curl -sSL https://get.usecorvus.me | sh ``` This installs the self-contained Native AOT executable directly to `/usr/local/bin/corvus` and registers a managed `systemd` service (`corvus.service`). --- ## 6. Frequently Asked Questions (FAQ) ### Q1: Why is Corvus the optimal choice for a 1GB or 512MB RAM VPS? **Answer:** On budget virtual private servers, RAM is the most constrained resource. Running Portainer (150-350MB), Uptime Kuma (100-250MB), and Dozzle (30-60MB) consumes 300MB to 650MB of RAM—leaving almost nothing for your actual workloads (e.g. Next.js, PostgreSQL, WordPress, API servers). Corvus provides all these monitoring and management features in less than 25MB RAM, saving over 90% of your system memory. ### Q2: Can Corvus completely replace Portainer CE? **Answer:** For container lifecycle management (starting, stopping, restarting, inspecting environment variables, reviewing port mappings, mounting volumes, and checking container resource usage), yes. If you do not require complex Kubernetes cluster federation or Swarm overlay network orchestration, Corvus is a faster, leaner drop-in alternative. ### Q3: How does Corvus achieve sub-15ms cold start times? **Answer:** Corvus is compiled ahead-of-time (.NET 9 Native AOT) directly to target machine instructions. There is no intermediate language (CIL), no Just-In-Time (JIT) compiler initialization, no assembly reflection scan, and no heavy runtime framework bootstrapping. The OS kernel loads the ELF executable and execution begins immediately. ### Q4: Does Corvus support ARM64 hardware like Raspberry Pi? **Answer:** Yes. Corvus ships official precompiled multi-arch Docker images and standalone binaries for `linux/amd64` and `linux/arm64`. On Raspberry Pi 4/5 or ARM64 cloud instances (AWS Graviton, Oracle Ampere, Hetzner CAX), memory usage remains strictly under 25MB. ### Q5: What makes the multi-server ("Systems") architecture secure? **Answer:** Traditional monitoring agents require opening and exposing an inbound TCP port (e.g., Portainer agent on port 9001) to the public internet or private VPN. Corvus flips this architecture: agents initiate an **outbound** encrypted WebSocket connection (`wss://`) to the central Corvus Hub. Your remote servers can sit behind strict NAT, home CGNAT, or firewall rules with zero inbound open ports. ### Q6: How does Corvus protect against memory leaks during long-running operation? **Answer:** In addition to Native AOT's compact memory layout, Corvus runs an internal `MemoryTrimmerBackgroundService` every 3 minutes. It performs GC compacting and invokes platform-specific kernel advisories (`malloc_trim` on Linux glibc / musl) to return unused memory pages to the host OS. ### Q7: Can I use an external PostgreSQL database instead of embedded SQLite? **Answer:** Yes. While embedded SQLite with WAL mode is zero-config and handles thousands of telemetry events per minute, Corvus includes an enterprise dual-storage layer that allows pointing to an external PostgreSQL database by defining the `ConnectionStrings:Database` configuration parameter. ### Q8: How does automatic domain discovery work for Traefik and Caddy? **Answer:** Corvus continuously listens to Docker container lifecycle events over `/var/run/docker.sock`. When a container starts or updates, Corvus inspects container labels for standard routing rules (such as `traefik.http.routers..rule` or `caddy`). It parses domain names automatically and creates corresponding uptime checks without manual intervention. ### Q9: What is Dead Man's Snitch / Push Heartbeat monitoring? **Answer:** Traditional uptime monitors make outbound requests to a server. Push monitoring (Dead Man's Snitch) is the inverse: your scheduled tasks, cron jobs, database backups, or script pipelines send an HTTP POST or GET request to a unique Corvus webhook URL upon completion. If Corvus does not receive a ping within the defined schedule window + grace period, it instantly alerts you that your job failed or did not run. ### Q10: How does Corvus handle high-volume Docker log streams? **Answer:** Corvus uses Server-Sent Events (SSE) with backpressure-aware non-blocking stream readers. In the browser frontend, log lines are rendered through a high-performance virtualized list that only renders the visible DOM nodes. Even when a container outputs tens of thousands of lines per second, browser memory remains stable and UI scrolling remains fluid. --- ## 7. Official Endpoints & Verification - **Website:** https://usecorvus.me - **Live Interactive Demo:** https://demo.usecorvus.me - **Public Demo Status Page:** https://demo.usecorvus.me/status - **GitHub Repository:** https://github.com/burhan-sahin/corvus - **Machine-Readable LLM Specification:** https://usecorvus.me/llms.txt - **Comprehensive Technical Reference:** https://usecorvus.me/llms-full.txt