architecture
Full project docs: README.md, SPEC.md, API reference, test plan, setup guide
Package map
cmd/ Cobra CLI (root, subcommands, TUI)
├── root.go entrypoint, plugin dispatch, post-quit actions
├── commands.go list, start, stop, ssh (TCP/vsock), viewer, logs, info, restart, pause, migrate, scale, adddisk, rmdisk, snapshot
├── create.go corral create flags and CLI/TUI options adapter
├── clone.go corral clone (kubevirt VM disk + config clone)
├── ct.go corral ct (create/list/start/stop/delete/console — Containers, pkg/ct)
├── images.go corral images (list catalog + imported datavolumes)
├── config.go corral config (show, get/set default backend)
├── web.go corral web (--addr, serve embedded SPA)
├── console.go corral console (one VM's console page on a free local port, URL printed for scripts)
├── tui.go Bubble Tea TUI root model (state, Update loop, list/doctor/detail views, context filter)
├── tui_items.go TUI list items (VMs, CTs, actions) and which actions apply to each
├── tui_actions.go TUI action dispatch (run selected action, SSH/viewer/export/clone)
├── tui_delegates.go TUI list delegates (VM rows, action menu rows)
├── tui_edit.go TUI port-toggle edit model and port helpers
├── tui_hwedit.go TUI hardware (CPU/RAM) edit model
├── tui_modes.go TUI screen modes and the legal transitions between them
├── tui_screens.go TUI screens: one key handler and one view per mode
├── tui_ops.go TUI backend work run as tea.Cmds off the Update loop, and their result messages
├── tui_views.go TUI views at parity with the web UI (snapshots via pkg/snapshot, events, template mark, CT scaling)
├── plugin.go corral plugin (search, install, list, remove)
├── doctor.go corral doctor (cluster diagnostics)
├── helpers.go shared CLI helpers (flags, namespace resolution)
├── corral-backup/ plugin: on-demand + scheduled (in-cluster CronJob) S3/R2 backups (built with -tags bootc-free, separate binary)
├── corral-windows/ plugin: UEFI/TPM/virtio-tuned Windows VMs
├── corral-vdi/ plugin: desktop pools (RFC-0001 phase 1) — pkg/vdi
└── corral-bootc/ plugin binary (built with -tags bootc, separate from core)
pkg/ Library code (importable)
├── create/ request-based create orchestration, backend dispatch, bootc and post-create lifecycle
├── lima/ Lima YAML parsing, source translation and provisioning cloud-init
├── catalog/ curated OS image catalog (containerdisks)
├── config/ ~/.config/corral/config.yaml reader
├── cronops/ shared CronJob/RBAC manifest builders for scheduled-op plugins (backup, snapsched, schedule)
├── backend/ the parity matrix + conformance tests; see docs/backend-parity.md
├── ct/ Containers (CT) — pet pods, not KubeVirt VMs; see docs/adr/0005
│ └── ct.go Create/Start/Stop/Delete/List/Exists, distrobox-style persistent-rootfs bootstrap for privileged CTs
├── proxmoxbe/ Proxmox VE as a backend — HTTPS API + token; see docs/adr/0009
│ (pkg/proxmox is the compat server — the other direction)
├── doctor/ cluster diagnostics + auto-fix (namespace, CDI, KubeVirt, GPU/PCI passthrough, StorageClass perf, etc.)
├── kubevirt/ KubeVirt backend (the heavy lifter)
│ ├── client.go VM CRUD, SSH via virtctl, cloud-init, registry
│ ├── client_test.go integration tests (need kubectl context)
│ ├── features.go scale, volumes, snapshots, clone, export, guest-info, metrics, capabilities, templates
│ ├── options.go boot options (run strategy, firmware, machine type, boot order) — read-modify-apply
│ ├── upload.go ISO/template upload via virtctl image-upload
│ ├── bootc_core.go bootc interface seam (always compiled — nil when tag absent)
│ └── bootc.go bootc implementation (//go:build bootc — Job + kernel-boot VM)
├── plugin/ extension system (krew-style, marketplace fetch, install/remove)
├── qemu/ QEMU backend (local VMs via systemd user service)
├── registry/ ~/.local/share/corral/registry.json — VM name → backend/namespace/password
├── vdi/ desktop pools (RFC-0001 phase 1) — clone-based pool create, label-based assignment
├── types/ shared types (VM, CreateOpts, RegistryEntry)
└── web/ Proxmox-style web UI
├── server.go Serve: startup, embedded static assets, registry store
├── routes.go route table (routes/newMux), cluster-only guard, console websockets, themed index
├── middleware.go request pipeline (peer token → admin gate → activity → peer gate) and host allowlist
├── respond.go JSON response and error-status helpers
├── tasks.go async task tracker (asyncTask, taskTracker) behind GET /api/tasks/{id}
├── tasklog.go task log ring (GET /api/tasklog) and task status handler
├── inventory.go VM list across backends and peers, /api/v1/inventory, /api/v1/meta
├── health.go /healthz and /readyz probes
├── create.go POST /api/vms: dispatch to the bootc/Windows/generic/local/backend create strategies
├── createtarget.go create-target resolution over the configured contexts, /api/contexts
├── vms.go VM info, power actions, delete
├── migrate.go live migration as a tracked task
├── export.go disk export (raw.gz, qcow2)
├── nodes.go node list, with this host as a synthetic node
├── console.go VNC and TTY websocket bridges (VM VNC/serial + CT exec)
├── ct.go CT list/create/start-stop/delete HTTP handlers
├── features.go capabilities, scale, volumes, expand, snapshots, clone, guest-info, events, metrics, templates,
│ doctor, plugins, NADs, NICs, images, instancetypes, datavolumes, boot options, ISO upload
└── static/
├── index.html dark SPA shell, create dialog (6 source types), CT create dialog, build dialog
├── app.js entry module: boot and lifecycle wiring
├── refresh.js fleet loading, failure recovery and render coordination
├── refresh-state.js shared render fingerprint and refresh status
├── poll.js single-flight schedule and DOM-free render policy
├── router.js selection, deep links and registered screen dispatch
├── state.js shared state store and event bus (select, inventory, tasks)
├── api.js fetch wrapper, VM/CT API URLs and selection keys
├── tree.js sidebar tree (Server/Namespace/Pool views, VMs+CTs merged), filter, multi-select
├── menus.js context menu items per inventory object
├── tags.js VM tag chips
├── console.js noVNC, serial terminal and IronRDP consoles, console tabs
├── create.js create VM/CT dialogs, OS wizard, bootc build streaming
├── dock.js task panel (Alpine.js island)
├── content/ one module per screen: datacenter, node, namespace, vm, vm-table, ct,
│ multiview, hostpower, doctor, extensions, settings
├── ui/ primitives: dom.js (query, toast, escape), menu.js (context menu)
├── icons.js inline Heroicon SVGs
└── style.css dark theme, responsive, dialog/modals, cards, tables
marketplace/ Plugin registry (hosted at tuna-os/corral)
└── index.json plugin entries (name, description, version, platform download URLs)
deploy/ On-cluster manifests
├── corral-web.yaml production namespace, RBAC, in-cluster kubeconfig, web Deployment, Service, Tailscale Ingress
├── corral-web-tailscale-proxy.yaml tailscale pod serving corral.<tailnet>.ts.net when the operator is absent
├── corral-web-e2e.yaml isolated web Deployment for live end-to-end tests
├── corral-web-servicemonitor.yaml optional Prometheus Operator scrape config
├── corral-web-alerts.yaml optional PrometheusRule alerts for collection health
├── registry-cache.yaml optional pull-through cache for bootc image pulls
├── multus/ pinned Multus DaemonSet and test NetworkAttachmentDefinition
└── grafana/corral-dashboard.json Grafana fleet-health dashboard
docs/ Documentation
├── api.md REST API reference
├── architecture.md This file
├── adr/ Architecture Decision Records (0001-0013)
├── deployment-modes.md web reachability, authentication, and supervision modes
├── backend-*.md backend support, parity, and setup guides
├── testing.md, troubleshooting.md, user-guide.md
├── rfc/, runbooks/, releases/, blog/, research/
└── kubevirt-proxmox-setup.md From-scratch cluster setup guide
scripts/ CI and Docker helper scripts
Containerfile Alpine + corral binary + kubectl + virtctl (for on-cluster deployment)
main.go Entrypoint: cmd.Execute()
Design decisions
No client-go — shell-out to kubectl/virtctl
Corral never imports client-go. Every cluster interaction shells out to
kubectl or virtctl. This keeps the binary under ~12 MB, avoids a
~60 MB SDK dependency, and respects whatever kubeconfig the operator already
has. The trade-off: slower per-call latency (process spawn). For a
single-operator tool this is fine; for a multi-tenant API server it would be
unacceptable.
Single binary, three UIs
corral is one Go binary that serves three interfaces:
- CLI — Cobra subcommands (
corral create,corral ssh, etc.) - TUI — interactive terminal UI in Bubble Tea (bare
corral) - Web — Embedded SPA served at
corral web --addr :8006
All three share the same pkg/kubevirt backend and
~/.local/share/corral/registry.json. A VM created in the browser is
immediately corral ssh-able and vice versa.
Embedded SPA — no JS build step
The web UI is native ES modules and CSS embedded via //go:embed. There is
no Node, no bundler, no build step. Corral vendors the console libraries
(xterm.js, noVNC, iron-remote-desktop, gridstack and uPlot) under
pkg/web/static/vendor with their provenance. Corral does not fetch them from
a CDN. Therefore a host with no outbound network still serves a console that
works. Heroicons are inline SVGs.
For a new screen, dock panel, widget, tree view or resizable edge, see the extension points for the web UI. That page also gives the rules for DOM that holds a live connection.
Backend transparency
After corral create, the registry stores backend: "kubevirt" or
backend: "qemu". Every subsequent command (start, ssh, viewer, etc.)
reads the registry to determine the backend. If the registry entry is missing,
it falls back to a live probe. The user never specifies --kubevirt again.
Bootc as a plugin
Bootc (which builds a container image into a VM disk on-cluster) is an optional
plugin compiled behind a //go:build bootc tag. The core binary's
bootc_core.go defines the interface seam with nil implementations; the
tagged bootc.go replaces them via init(). This keeps the core binary
lean for users who only need containerdisks and ISOs, while the full
pipeline is available via corral plugin install bootc or a build with
-tags bootc.
The web UI checks GET /api/capabilities → bootc: true/false and
shows/hides the bootc source option to match.
KubeVirt LiveUpdate strategy
Corral creates VMs with cpu.maxSockets + memory.maxGuest headroom and
masquerade networking so they can hotplug/migrate. It gates live operations
on real viability:
- Live migration / hotplug: needs
vmRolloutStrategy: LiveUpdate, masquerade networking, and migratable storage (RWX). It also needs a target node with the same CPU vendor (you cannot live-migrate Intel→AMD). - Disk hotplug: needs the
HotplugVolumesfeature gate. - Snapshots: need a
VolumeSnapshotClass(Longhorn CSI). - Online expand: needs
allowVolumeExpansion: true.
The UI queries GET /api/capabilities and greys out controls the cluster
can't support, so the user does not see a failure at submit time.
Secrets stay local
- Corral generates a cloud-init password for each VM and stores it in
~/.local/share/corral/registry.json(mode 0600). - A guest never receives a Tailscale auth key. Cluster VMs join the tailnet through the Tailscale operator's per-VM proxy, which holds its own credentials.
- SSH public keys are read from
~/.ssh/id_ed25519.pub(fallbacks:id_rsa.pub,id_ecdsa.pub). - No secrets in git, no secrets in cluster state. The on-cluster deployment has no registry. It reads everything from cluster objects.
Namespace conventions
- Default namespace:
corral-vms(overridable with--namespace/-nor theCORRAL_NAMESPACEenvironment variable). - VM names must match
[a-z0-9][a-z0-9-]*(Kubernetes DNS label). - On-disk state lives in
~/.local/share/corral/and~/.config/corral/. Corral does not read the legacy Pythontailvmdirectories.
Data flow
VM create (containerdisk)
corral create web --kubevirt --image fedora
│
├─ catalog.Find("fedora") → containerDisk URI
├─ kubevirt.NewClient(ns).CreateVM(opts) → kubectl apply VM manifest
│ ├─ cloud-init: SSH key + password
│ └─ containerDisk registry URL
└─ registry.Set("web", {backend, namespace, password})
VM create (bootc)
corral bootc create dev --image quay.io/centos-bootc/...
│
├─ kubevirt.BootcBuildDisk() → block PVC + short-lived builder VM
│ ├─ builder VM: bootc install to-disk (composefs/ostree auto-detected)
│ ├─ optional account provision script runs inside installed root
│ └─ Progress streams to stderr / task log
├─ kubevirt.GenerateBootcVM() → VM manifest (UEFI-boots the disk)
├─ kubevirt.Apply(vm) → kubectl apply
└─ registry.Set("dev", {backend, namespace})
Same flow for the web UI, but the build runs as a background task polled at
GET /api/tasks/{id} with a live log displayed in the browser.
Web UI SSH
Browser: click SSH in VM detail panel
│
├─ GET /api/vms/{ns}/{name} → get VM info
├─ spawn: virtctl ssh {user}@{ns}/{name}
│ └─ xterm.js + WebSocket terminal in browser
└─ (or copy the virtctl ssh command to clipboard)
The web SSH delegates to the browser's ability to open terminal URLs — it doesn't proxy SSH through the server.
Web UI console
Browser: Console tab → VNC or Serial
│
├─ VNC: WebSocket → /api/vnc/{ns}/{name}
│ ├─ server: virtctl vnc --proxy-only → WS bridge
│ └─ browser: noVNC canvas
└─ Serial: WebSocket → /api/tty/{ns}/{name}
├─ server: virtctl console → WS bridge
└─ browser: xterm.js terminal
Build & CI
CONTRIBUTING.md and Justfile are
authoritative for local validation. This gate checks format, vet, build, race
tests, and lint for both plain and bootc tag sets. A separate target runs
checks on browser modules. Containerfile packages the CLI with kubectl and
virtctl for cluster deployment.
For web reachability, authentication, probes, and operation modes, see deployment modes. The deployment manifests listed above are the source of truth for the cluster shape.
On-cluster deployment
The deploy/corral-web.yaml manifest:
- Creates the
corralnamespace (privileged pod-security); VMs go tocorral-vms(CORRAL_NAMESPACE) - ServiceAccount + scoped ClusterRole (VM lifecycle, subresources, snapshots, CDI, PVCs, nodes, events, metrics, instancetypes, etc.)
- Deployment (ghcr.io/tuna-os/corral:latest, port 8006)
- ClusterIP Service (port 80 → 8006)
- Tailscale Ingress (
ingressClassName: tailscale) → TLS atcorral.<tailnet>.ts.net
Tailnet membership is the authentication — never bind a public interface.
Authorization is an adminGate middleware: CORRAL_ADMINS (tailnet logins)
gates requests that change state, with everyone else read-only (see
ADR-0003). Unset = single-user/open.
Plugin system
Plugins are standalone executables named corral-<name>, discovered in
~/.local/share/corral/plugins (and $PATH). When you run corral <name>,
the root command checks if <name> is a known subcommand; if not, it
dispatches to the plugin. The root command exports CORRAL_PLUGIN=<name>, so
each plugin knows the name that invoked it.
The marketplace is the marketplace/index.json file in the repo, fetched
from GitHub raw at runtime. Each entry has a name, description, version, and
platform-specific download URLs. Installation downloads the binary, sets the
executable bit, and places it in the plugin dir.