api
Full project docs: README.md, SPEC.md, architecture, setup guide
The web UI of Corral serves a REST API at port 8006 (corral web), plus
WebSocket bridges for VNC and serial consoles. All responses are JSON unless
noted otherwise.
The same API is available from the on-cluster deployment at
https://corral.<tailnet>.ts.net.
Errors
Every error response has shape {"error": "<message>"} with a 4xx or 5xx
status code. 5xx means the server couldn't reach the cluster (kubectl failed);
4xx means invalid input.
Request IDs
Each response has an X-Request-ID header. When the request has an
X-Request-ID header of 1 to 64 characters from A-Z, a-z, 0-9, .,
_ and -, Corral uses that value. If not, Corral makes a new ID.
Corral writes the ID in each log record of the request. These records include the backend commands, the Proxmox API calls, the requests to peers, and the tasks that the request starts. Corral also sends the ID to its peers. Give the ID in a bug report. See Collect evidence.
VM lifecycle
GET /api/vms
List all VMs across all namespaces. Merges live VMI data (IP, node) for VMs that run.
Response (array):
[
{
"name": "web",
"namespace": "corral-vms",
"status": "Running",
"ready": true,
"running": true,
"cpu": 2,
"mem": "4Gi",
"disk": "20Gi",
"ip": "10.42.0.15",
"node": "bihar"
}
]
POST /api/vms
Create a VM.
Request fields:
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | [a-z0-9][a-z0-9-]* |
namespace | string | no | defaults to corral-vms (CORRAL_NAMESPACE) |
cpu | int | no | default 2 |
mem | string | no | e.g. 4G, default 4G |
disk | string | no | e.g. 20G, default 20G |
containerDisk | string | source | OCI containerdisk URI |
image | string | source | catalog entry name (see /api/images) |
import | string | source | qcow2/raw URL (CDI import) |
iso | string | source | ISO URL (CDI import) |
bootc | string | source | bootc image URI (needs bootc plugin) |
pvc | string | source | existing PVC name |
sshKey | string | bootc only | SSH public key baked into the disk |
node | string | no | schedule on a specific node |
cloudInit | string | no | cloud-init user-data YAML |
instancetype | string | no | cluster instancetype name |
preference | string | no | cluster preference name |
Exactly one source field must be set.
Response (201 Created):
{"name": "web", "namespace": "corral-vms"}
Bootc response (202 Accepted, build is async):
{"task": "bootc-web-1712345678"}
Poll the task ID at GET /api/tasks/{id}.
GET /api/vms/{ns}/{name}
Get the raw JSON of the VM manifest (the kubevirt VirtualMachine object).
POST /api/vms/{ns}/{name}/{action}
Execute an action on a VM. Valid actions:
| Action | Meaning |
|---|---|
start | Power on |
stop | Graceful shutdown |
restart | Restart |
pause | Freeze (kubevirt only) |
unpause | Resume (kubevirt only) |
migrate | Live-migrate (kubevirt only) — prefer the dedicated endpoint below |
Response: {"status": "ok"}
POST /api/vms/{ns}/{name}/migrate
Live-migrate as a tracked background task with progress in the activity panel. The trigger runs synchronously (so "not migratable / cross-vendor" errors come back immediately); then the server watches the migration to completion.
Body: {"targetNode": "bihar"} (optional — empty lets the scheduler choose,
from among same-CPU-vendor nodes).
Response: 202 {"task": "migrate-…"} — poll GET /api/tasks/{id}.
POST /api/vms/{ns}/{name}/tags
Add or remove a tag, persisted as a corral.dev/tag.<name> VM label (so tags
survive round-trips and are kubectl get vm -l-selectable). GET /api/vms
shows the tags on every VM.
Body: {"tag": "prod", "on": true}
Response: {"tag": "prod", "on": true}
DELETE /api/vms/{ns}/{name}
Delete a VM, its PVCs, DataVolumes, hotplug disks, snapshots, proxy resources, and registry entry.
Response: {"status": "deleted"}
Containers (CT)
Proxmox-style pet pods — plain Kubernetes pods, not KubeVirt VMs. See
docs/adr/0005-containers-as-pet-pods.md for the design.
GET /api/cts
List all Containers across every namespace.
Response: 200
[{"name": "devbox", "namespace": "corral-vms", "node": "karnataka",
"phase": "Running", "ready": true, "image": "debian:bookworm",
"cpu": 2, "mem": "2Gi", "privileged": true}]
phase is the pod phase, or "Stopped" when no pod exists (the CT's
durable identity is its data PVC, which survives Stop). node is empty
when stopped/unscheduled.
POST /api/cts
Create a Container.
Body:
{"name": "devbox", "namespace": "corral-vms", "image": "docker.io/library/debian:bookworm",
"cpu": 2, "mem": "2Gi", "disk": "10Gi", "storageClass": "", "privileged": true}
privileged: true seeds a persistent, mutable root filesystem onto the
data volume and chroots into it (distrobox-style — package installs and
dotfiles survive Stop/Start). false (default) mounts the volume at
/data only.
Response: 201 {"name": "devbox", "namespace": "corral-vms"}
POST /api/cts/{ns}/{name}/{action}
action is start or stop. Stop deletes the pod but keeps the data
volume; Start recreates the pod from the spec recorded on the volume's
annotation.
Response: {"status": "ok"}
DELETE /api/cts/{ns}/{name}
Delete a Container: its pod, Service (if it has a tailnet proxy), and data volume.
Response: {"status": "deleted"}
Hardware operations
POST /api/vms/{ns}/{name}/scale
Change CPU count and/or memory. Body: {"cpu": 4, "mem": "8G"}. Live-hotplugs
when the VM is live-migratable; otherwise does a stop→patch→start.
Response: {"status": "ok"}
POST /api/vms/{ns}/{name}/volumes
Hotplug a new disk. Body: {"size": "10Gi"}.
Response: {"pvc": "web-disk-2"}
DELETE /api/vms/{ns}/{name}/volumes/{vol}
Detach a hotplugged disk. {vol} is the PVC name.
Response: {"status": "removed"}
POST /api/vms/{ns}/{name}/expand
Expand an existing PVC. Body: {"pvc": "web-disk-1", "size": "40Gi"}. Needs a
StorageClass with allowVolumeExpansion: true.
Response: {"status": "ok"}
POST /api/vms/{ns}/{name}/nics
Add a secondary NIC. Body: {"nad": "lan", "iface": "eth1"}. Needs Multus + a
NetworkAttachmentDefinition in the VM's namespace.
Response: {"status": "ok"}
Snapshots
GET /api/vms/{ns}/{name}/snapshots
List snapshots for a VM. Needs the Snapshot feature gate.
Response: array of {name, phase, creationTime}
POST /api/vms/{ns}/{name}/snapshots
Create a snapshot. Body: {"name": "before-upgrade"} (optional; auto-named).
Response: {"name": "before-upgrade"}
POST /api/vms/{ns}/{name}/snapshots/{snap}/restore
Restore a VM to a snapshot. The VM is shut down during restore.
Response: {"status": "restoring"}
DELETE /api/vms/{ns}/{name}/snapshots/{snap}
Delete a snapshot.
Response: {"status": "deleted"}
Clone & template
POST /api/vms/{ns}/{name}/clone
Clone a VM (definition and disks). Stop the VM first. Body:
{"target": "web-clone"}. Needs the Snapshot feature gate + a
VolumeSnapshotClass.
Response: {"target": "web-clone"}
POST /api/vms/{ns}/{name}/template
Mark or unmark a VM as a template. Body: {"on": true}.
Response: {"isTemplate": true}
Image library & catalog
GET /api/images
The built-in catalog of OS images — curated, ready-to-boot containerdisks.
Response (array):
[
{
"name": "fedora",
"description": "Fedora 42 cloud",
"containerDisk": "quay.io/containerdisks/fedora:42",
"defaultUser": "fedora"
}
]
The response then adds the user-defined custom sources, each with the flag "custom": true.
GET /api/sources
The user-defined custom sources only (for management UI). Same entry shape as
/api/images, all "custom": true. Persisted in the corral-sources
ConfigMap so they survive web-pod restarts.
POST /api/sources
Add or replace a custom source (idempotent by name).
{"name": "my-image", "kind": "containerDisk", "uri": "ghcr.io/me/img:tag", "description": "optional"}
kind is one of containerDisk (boots directly), url (qcow2/raw, CDI
import), or iso (installer ISO). Response: {"status": "ok", "name": "my-image"}.
DELETE /api/sources/{name}
Remove a custom source. Response: {"status": "removed"}.
GET /api/datavolumes
List imported images (CDI DataVolumes). These are ISO/qcow2/raw images imported from URLs.
Response: array of {name, namespace, size, phase, progress, source}
POST /api/datavolumes
Start a CDI import. Body:
{"name": "jammy", "namespace": "corral-vms", "url": "https://.../jammy.qcow2", "size": "10Gi"}
Response: {"name": "jammy"}
DELETE /api/datavolumes/{ns}/{name}
Delete an imported image (DataVolume).
Response: {"status": "deleted"}
Bootc builds
GET /api/tasks/{id}
Poll a bootc build task. Returns live build log.
Response:
{"status": "running", "log": "Pulling image...\nInstalling...", "error": ""}
Statuses: "running" → "done" (success) or "error" (failure).
VDI self-service
These routes exist only when CORRAL_VDI_BROKER=1; otherwise they answer
404. Any authenticated user may call them, also a user outside
CORRAL_ADMINS. The broker checks that the caller holds the desktop, and it
takes the caller only from the identity headers. See
docs/vdi.md and
ADR-0013.
| Route | Result |
|---|---|
GET /api/vdi/pools | Served pools: id, kind, namespace, name, mode, members, claimed, free. |
POST /api/vdi/pools/{kind}/{ns}/{pool}/claim | The caller's desktop (below). 409 when no member is free. |
GET /api/vdi/desktops[?all=1] | The caller's desktops; all=1 lists every user's (admin only). |
GET /api/vdi/desktops/{kind}/{ns}/{member} | One desktop (holder or admin). |
POST /api/vdi/desktops/{kind}/{ns}/{member}/start | Starts it (holder or admin). |
POST /api/vdi/desktops/{kind}/{ns}/{member}/release | 202 {"task": "...", "desktop": "..."}; poll GET /api/tasks/{id}. |
GET /api/vdi/desktops/{kind}/{ns}/{member}/connect | The console to open (holder or admin), below. 409 for a stopped desktop or an expired claim. |
A desktop:
{"id": "vm/corral-vms/devpool-1", "sessionId": "5f0c2a9e41b7d388",
"poolId": "vm/corral-vms/devpool", "kind": "vm", "namespace": "corral-vms",
"pool": "devpool", "member": "devpool-1", "owner": "alice@example.com",
"claimedAt": "2026-10-15T09:00:00Z", "phase": "Running", "running": true}
startError is set when the claim succeeded and the start failed.
claimExpired is set when the Lease expired. The session fields come from
the reclaim policy (#228): connected (the user has a console open), disconnectedAt,
and reclaimAt with reclaimReason (disconnect-grace or max-duration). Status codes: 401 without an
identity, 403 for another user's desktop or a peer service identity, 404 for
an unknown or unclaimed desktop.
A connect target names the protocol (rdp, vnc, or terminal) and the
console route to open. direct is the guest address that answered the RDP
probe. fallbacks are the other protocols in order, and skipped says why a
protocol is missing:
{"protocol": "rdp", "path": "/api/rdp/corral-vms/devpool-1?rdcleanpath=1",
"direct": "10.244.1.17:3389",
"fallbacks": [{"protocol": "vnc", "path": "/api/vnc/corral-vms/devpool-1"},
{"protocol": "terminal", "path": "/api/tty/corral-vms/devpool-1"}],
"desktop": {"id": "vm/corral-vms/devpool-1", "owner": "alice@example.com", "...": "..."}}
When the broker is on, the console websockets (/api/vnc, /api/tty,
/api/rdp) of a claimed desktop accept only its holder and admins.
Guest info
GET /api/vms/{ns}/{name}/guestinfo
Guest-agent info (OS, hostname, users, filesystems). Returns 503 if the
agent isn't reachable.
GET /api/vms/{ns}/{name}/events
Recent K8s events for the VM (Proxmox-style task log).
GET /api/vms/{ns}/{name}/metrics
Live CPU/memory/disk metrics. Returns null values if the metrics-server isn't available.
GET /api/vms/{ns}/{name}/metrics/history
Retained usage samples for the Summary-panel charts. The server samples every
live VM every ~15s into a bounded in-memory ring buffer (~1h). Returns
[{"t": <epoch-ms>, "cpu": <millicores>, "mem": <bytes>}, …] — an empty array
when metrics-server is absent. The mem field is absent when metrics-server
gives no memory value.
GET /api/metrics/history
The same samples, added up over all VMs that run now. The Datacenter dashboard charts show them.
GET /api/nodes/{name}/metrics/history
The same samples, added up over the VMs that run now on one node. The node dashboard charts show them.
GET /api/metrics/top
The newest sample of each VM that runs now, busiest first. The "top VMs" dashboard widgets use it.
Query: by=cpu (default) or by=mem sets the sort order. node=<name>
keeps only the VMs on that node. limit=<n> keeps the first n rows.
Response (array):
[{"namespace": "corral-vms", "name": "db-prod", "node": "corral-2", "cpu": 900, "mem": 4294967296}]
Infrastructure
GET /api/whoami
The caller's tailnet identity and privilege, for the UI to show the logged-in
user and switch to read-only for non-admins. Identity comes from the Tailscale
ingress headers; CORRAL_ADMINS controls admin (see
ADR-0003).
Response: {"login": "alice@github", "name": "Alice", "admin": true, "enforced": false}
When an allowlist exists, the server rejects requests that change state
(non-GET) from non-admins with 403.
GET /api/nodes
List cluster nodes with readiness, roles, kubelet version, and architecture.
Response (array):
[{"name": "bihar", "ready": true, "roles": "control-plane,master", "kubelet": "v1.36.1", "arch": "amd64"}]
GET /api/capabilities
Cluster capability flags — the UI gates controls on these.
Response:
{
"storageClass": "longhorn",
"canExpand": true,
"canSnapshot": true,
"bootc": false
}
| Field | Meaning |
|---|---|
storageClass | Default StorageClass for new VM disks |
canExpand | Whether allowVolumeExpansion: true exists |
canSnapshot | Whether a VolumeSnapshotClass is available |
bootc | Whether the bootc plugin is compiled in |
GET /api/instancetypes
Cluster instancetypes and preferences for the create wizard.
Response:
{"instancetypes": ["u1.medium", "u1.large"], "preferences": ["fedora", "ubuntu"]}
GET /api/nads
Multus NetworkAttachmentDefinitions available for secondary NICs.
GET /api/doctor
Run all Corral cluster diagnostics. Returns a list of checks (name, status, message).
POST /api/doctor/fix
Run the fixable diagnostics (e.g. create missing namespaces).
Response: {"fixed": ["created namespace tailvm"]}
Extensions (plugins)
GET /api/plugins
Marketplace entries merged with locally-installed state.
Response (array):
[{"name": "bootc", "description": "...", "version": "0.1.0", "installed": false, "inStore": true}]
POST /api/plugins/{name}/install
Install a plugin from the marketplace.
Response: {"installed": "bootc"}
DELETE /api/plugins/{name}
Remove an installed plugin.
Response: {"status": "removed"}
GET /api/plugins/ui
The widgets and screens that installed plugins add to the web UI. The response
does not include commands. errors names each plugin with a declaration that
corral refused.
Response:
{"plugins": [{"name": "aws-cost",
"widgets": [{"id": "spend", "title": "AWS spend", "refresh_ms": 60000}],
"sections": [{"id": "hosts", "title": "AWS hosts", "icon": "server"}]}],
"errors": {"broken": "ui widget id \"Bad\" must be lower case letters, digits and dashes"}}
GET /api/plugins/{plugin}/ui/{id}
Runs the item's command and returns the checked document. All callers share the document for 15 seconds.
Response: {"document": {"kind": "rows", "rows": [...]}}
Errors:
404: no plugin declares the item.502: the plugin failed, or its document breaks the contract.504: the plugin did not answer within 10 seconds.
Console & export (WebSocket)
GET /api/vnc/{ns}/{name} (WebSocket)
Upgrade to WebSocket → bridges virtctl vnc --proxy-only. Use with noVNC in
the browser.
GET /api/tty/{ns}/{name} (WebSocket)
Upgrade to WebSocket → bridges virtctl console. Use with xterm.js in the
browser.
GET /console/{ns}/{name}
An HTML page that shows only the VNC console of one VM. Scripts and browser automation use it. The page connects through /api/vnc/{ns}/{name}, so the same origin, identity, and VDI checks apply.
| Query | Effect |
|---|---|
| (default) | Shows the screen at 1:1 scale. |
?scale=fit | Scales the screen to the window. |
?context=<name> | Sends the backend context to the websocket. |
The page sets these hooks:
<body data-connected>has the valuetruewhile the console has a connection, andfalseat other times.#vnc-screenhas the same attribute.<body>hasdata-vm,data-namespace, anddata-scale.#vnc-canvasis the noVNC canvas. It gets keyboard focus at each connect.
After a disconnect, the page connects again. The wait starts at 1 second and increases to 5 seconds.
400: thescalevalue is notoneorfit.404: the namespace or the name is not 1–253 letters, digits,.,_, or-that start with a letter or a digit.
GET /api/vms/{ns}/{name}/export
Download a VM disk backup. Stop the VM first (the RWO disk is busy while
the VM runs). Triggers virtctl vmexport and streams the result.
| Query | Format | Content-Type |
|---|---|---|
| (default) | gzipped raw (name.img.gz) | application/gzip |
?format=qcow2 | compressed qcow2 (name.qcow2) | application/octet-stream |
qcow2 needs qemu-img on the server (it converts the raw export); if absent the
request returns 501 and the default raw.gz still works.
Pools and cross-backend move
Pools are the user-defined folders of ADR-0008. Paths travel in the body or the query string, never in the route, because a nested path contains slashes.
| Method | Route | Notes |
|---|---|---|
GET | /api/folders | Tree with members resolved against the live fleet, plus unfoldered |
POST | /api/folders | {path} — nesting with /, max depth 8 |
DELETE | /api/folders?path=… | Members are unfoldered, never deleted |
POST | /api/folders/move | {from, to} — re-parent a pool |
POST | /api/folders/members | {path, ref} — what a drag-and-drop lands on |
DELETE | /api/folders/members?ref=… | |
POST | /api/folders/action | {path, action} — fans out with per-member results |
Moving an instance between backends (ADR-0010) is two endpoints, because the
decision and the doing are separate. A move stops the guest — it is not a
live migration, and corral migrate remains the live, same-backend operation.
| Method | Route | Notes |
|---|---|---|
GET | /api/move/destinations | Which backends can receive, and why the others cannot |
POST | /api/move/preflight | Returns the plan. Touches nothing — safe to call on every drag |
POST | /api/move | Commits, after re-running the preflight server-side |
Body for both: {ref, toBackend, toContext?, toNamespace?, name?, scratch?, deleteSource?}.
A refused preflight is a 200 — the refusals are the answer. An error
status would make a UI show "request failed" where it should show three reasons.
A refused commit is a 409 with the same list. The move stops the source and
keeps it unless deleteSource is set.
Health and readiness
| Method | Route | Notes |
|---|---|---|
GET | /healthz | Liveness probe endpoint. Returns 200 OK (ok\n) when HTTP server is responding |
GET | /readyz | Readiness probe endpoint. Returns 200 OK ({"status":"ready"}) if the registry store is initialized; returns 503 Service Unavailable if unready |
Metrics
| Method | Route | Notes |
|---|---|---|
GET | /metrics | Prometheus text exposition. Requires corral web --metrics |
Served from a cached snapshot refreshed on a background timer, so a scrape never
fans out to the backends. Corral publishes corral_collection_age_seconds for that
reason: without it, a frozen collector is indistinguishable from a stable fleet.
The context label is the configured context's name, so the instance series
and corral_backend_up join. The pool label is the one that spans backends —
sum by (pool) (corral_instance_running) answers "is my application stack up"
across a KubeVirt cluster and a Proxmox host at once. See ADR-0011 for the full
series list and label rationale.
Without --metrics the endpoint still answers 200 with
corral_collection_success 0. A scraper that receives a 503 records nothing,
and "up but no collection" is the state that deserves an alert.
The endpoint always includes corral_last_activity_timestamp_seconds. This
gauge is the Unix time of the last request from a user or a peer Corral. Use it
to find an idle host and stop it. Probes, /healthz, /readyz, /metrics, and
the timed polls of a peer's --metrics collector do not count. Requests that the
auth gate rejects do not count. At process start, the gauge shows the start time.
Static assets
The server serves the embedded SPA at the root:
| Route | File |
|---|---|
/ | index.html |
/style.css | style.css |
/app.js | app.js (the entry module) |
/<module>.js | the other ES modules, such as state.js, api.js and tree.js |
/content/*.js, /ui/*.js | the screen modules and the UI primitives |
/icons.js | icons.js |
All other paths fall through to the Go 1.22 http.ServeMux 404.