Skip to main content

Getting Started with Corral

This guide walks you through your first VM with Corral — from build to boot to SSH — using the local QEMU/KVM backend. No Kubernetes cluster required.

Prerequisites​

  • A Linux machine; Go is needed only when building from source
  • qemu-system-x86_64 and kvm (apt install qemu-system-x86 qemu-utils or equivalent)
  • A Tailscale account (optional but recommended)
  • sudo access for /dev/kvm

Step 1: Build Corral​

git clone https://github.com/tuna-os/corral.git
cd corral
go build -o corral .

Verify it works:

./corral --help

Step 2: Create Your First VM​

Corral can create VMs on your local machine (QEMU/KVM backend) or on a Kubernetes cluster (KubeVirt backend). Let's start locally:

# Create a Fedora 42 VM named "devbox"
./corral create devbox --backend qemu --container-disk quay.io/containerdisks/fedora:42

This will:

  1. Pull the Fedora 42 container disk
  2. Create a QEMU VM with 2 CPUs and 4 GB RAM
  3. Inject your SSH public key (~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub)
  4. Start the VM automatically

Customizing resources​

./corral create devbox \
  --backend qemu \
  --cpus 4 \
  --memory 8 \
  --disk 40 \
  --container-disk quay.io/containerdisks/fedora:42

Step 3: SSH Into the VM​

# SSH using Corral's smart tunnel
./corral ssh devbox

Corral automatically picks the right connection path:

  • Local QEMU VMs: connects via a Tailscale-bound port-forward
  • KubeVirt VMs: tunnels through the Kubernetes API

If you haven't set up Tailscale yet, Corral falls back to a local port-forward:

# To see the SSH command and port used
./corral ssh devbox -v

Step 4: Connect VMs to Your Tailnet​

To make your VM appear as a real machine on your Tailscale tailnet, set an auth key:

# Set your Tailscale pre-auth key
export TS_AUTHKEY="tskey-auth-xxxxxxxx"

# Create a VM that joins the tailnet automatically
./corral create web \
  --backend qemu \
  --container-disk quay.io/containerdisks/fedora:42

The VM will show up in your Tailscale admin console with a MagicDNS name like web-vm.tailnet-name.ts.net. You can SSH from any device on your tailnet:

# From your phone or laptop
ssh fedora@web-vm.tailnet-name.ts.net

Step 5: Use the TUI​

Run Corral without any command to launch the Bubble Tea terminal UI:

./corral

The TUI shows all your VMs in a table with actions:

  • Start / Stop — power management
  • SSH — one-key SSH into any VM
  • VNC — graphical console access
  • Delete — remove a VM
  • Port publishing — toggle which ports are reachable via the tailnet

Navigate with arrow keys and press <Enter> to select actions.

Step 6: Launch the Web UI​

Start the Proxmox-style web dashboard:

./corral web

Open http://127.0.0.1:8006 in your browser. You'll see:

  • Datacenter view — all nodes and VMs in a tree
  • Live status — CPU/memory/disk usage per VM
  • VM wizard — create new VMs from the browser
  • VNC console — in-browser graphical access
  • Live migration — move VMs between nodes

To expose the web UI on your tailnet:

./corral web --addr "$(tailscale ip -4):8006"

Add remote backends​

corral context add homelab --backend kubevirt --context homelab-admin
corral context add lab-incus --backend incus --context lab
corral context add hypervisor --backend libvirt --context qemu+ssh://admin@hypervisor/system
corral context use homelab
corral list

Incus uses the authentication of its existing named remote. Libvirt's SSH URI uses OpenSSH. See Backends, contexts, and peers for the complete model.

Next Steps​

  • Try the KubeVirt backend: ./corral create web --backend kubevirt --container-disk ...
  • Follow the TUI and Web UI walkthrough
  • Install the bootc plugin: ./corral plugin install bootc then ./corral bootc create dev --image ghcr.io/tuna-os/yellowfin:gnome
  • Browse the plugin marketplace: ./corral plugin search
  • Read the full specification

Troubleshooting​

ProblemFix
/dev/kvm: Permission deniedAdd your user to the kvm group: sudo usermod -aG kvm $USER && logout & back in
qemu-system-x86_64: command not foundInstall QEMU: brew install qemu or sudo dnf install @virtualization
VM shows "no bootable device"Ensure the --container-disk image is a valid bootable disk image
Tailscale: TS_AUTHKEY not setObtain an auth key from Tailscale admin console