Skip to main content

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:

FieldTypeRequiredNotes
namestringyes[a-z0-9][a-z0-9-]*
namespacestringnodefaults to corral-vms (CORRAL_NAMESPACE)
cpuintnodefault 2
memstringnoe.g. 4G, default 4G
diskstringnoe.g. 20G, default 20G
containerDiskstringsourceOCI containerdisk URI
imagestringsourcecatalog entry name (see /api/images)
importstringsourceqcow2/raw URL (CDI import)
isostringsourceISO URL (CDI import)
bootcstringsourcebootc image URI (needs bootc plugin)
pvcstringsourceexisting PVC name
sshKeystringbootc onlySSH public key baked into the disk
nodestringnoschedule on a specific node
cloudInitstringnocloud-init user-data YAML
instancetypestringnocluster instancetype name
preferencestringnocluster 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:

ActionMeaning
startPower on
stopGraceful shutdown
restartRestart
pauseFreeze (kubevirt only)
unpauseResume (kubevirt only)
migrateLive-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.

RouteResult
GET /api/vdi/poolsServed pools: id, kind, namespace, name, mode, members, claimed, free.
POST /api/vdi/pools/{kind}/{ns}/{pool}/claimThe 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}/startStarts it (holder or admin).
POST /api/vdi/desktops/{kind}/{ns}/{member}/release202 {"task": "...", "desktop": "..."}; poll GET /api/tasks/{id}.
GET /api/vdi/desktops/{kind}/{ns}/{member}/connectThe 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
}
FieldMeaning
storageClassDefault StorageClass for new VM disks
canExpandWhether allowVolumeExpansion: true exists
canSnapshotWhether a VolumeSnapshotClass is available
bootcWhether 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.

QueryEffect
(default)Shows the screen at 1:1 scale.
?scale=fitScales the screen to the window.
?context=<name>Sends the backend context to the websocket.

The page sets these hooks:

  • <body data-connected> has the value true while the console has a connection, and false at other times. #vnc-screen has the same attribute.
  • <body> has data-vm, data-namespace, and data-scale.
  • #vnc-canvas is 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: the scale value is not one or fit.
  • 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.

QueryFormatContent-Type
(default)gzipped raw (name.img.gz)application/gzip
?format=qcow2compressed 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.

MethodRouteNotes
GET/api/foldersTree 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.

MethodRouteNotes
GET/api/move/destinationsWhich backends can receive, and why the others cannot
POST/api/move/preflightReturns the plan. Touches nothing — safe to call on every drag
POST/api/moveCommits, 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​

MethodRouteNotes
GET/healthzLiveness probe endpoint. Returns 200 OK (ok\n) when HTTP server is responding
GET/readyzReadiness probe endpoint. Returns 200 OK ({"status":"ready"}) if the registry store is initialized; returns 503 Service Unavailable if unready

Metrics​

MethodRouteNotes
GET/metricsPrometheus 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:

RouteFile
/index.html
/style.cssstyle.css
/app.jsapp.js (the entry module)
/<module>.jsthe other ES modules, such as state.js, api.js and tree.js
/content/*.js, /ui/*.jsthe screen modules and the UI primitives
/icons.jsicons.js

All other paths fall through to the Go 1.22 http.ServeMux 404.