Skip to content

Architecture

Susant Sahani edited this page Oct 18, 2026 · 1 revision

Architecture

Shape

One Rust crate (zorvia) builds the main binary (CLI, TUI, API server and embedded console serving) plus two feature-gated helper binaries:

  • rescue-agent (feature rescue-agent): runs in a privileged Job pod for offline guest-disk operations via GuestKit.
  • backup-agent (feature backup-agent): runs in a Job pod to stream VM disks to S3-compatible storage (checksummed, optionally encrypted, Object Lock aware).

The web console source lives in web/ (built into the release image, ZORVIA_WEB_DIR). Kubernetes access uses kube-rs and KubeVirt objects.

Data flow

flowchart LR
  CLI[zorvia CLI] --> API
  TUI[Interactive TUI] --> API
  WEB[Web console] --> API
  MCP[MCP clients] --> API
  API[Fabric API<br/>auth, RBAC, audit] --> K8S[Kubernetes + KubeVirt]
  API --> DB[(SQLite or PostgreSQL)]
  API -.optional.-> KRY[Kryton]
  API -.optional.-> ATL[Atlas]
  API -.Jobs.-> H2[h2kvm import]
  API -.Jobs.-> BK[backup-agent to S3]
Loading

Per the README, CLI, TUI and web all use one API, and every call ends in real cluster objects. MCP tool calls are replayed through the REST API with the caller's token, so no extra permissions exist.

State

SQLite is the default store; PostgreSQL (ZORVIA_DATABASE_URL) holds users, operations, audit, schedules and shared lockout, and enables the two-replica HA profile (Beta). Long operations are durable and survive restarts.

Access control

Admin, user and viewer roles, per-user namespace allow-lists, console/VNC/SSH WebSockets that are permission-checked, origin-checked and audited, opt-in OIDC, persistent audit with JSONL export.

Deployment

The Helm chart provides Deployment, Service, RBAC, optional Ingress, Gateway/HTTPRoute (Envoy Gateway), NetworkPolicy, PDB and PVC templates.

See docs/whats-inside.md and DEVELOPMENT.md for the authoritative diagrams. Module-level detail beyond this was not reviewed for this wiki.

Clone this wiki locally