Virtainer API

Virtainer Lite exposes an HTTP API for host-local automation. Use this section as the API reference: each endpoint page documents the accepted parameters, success status, response fields, and common errors.

This section documents the API key surface. Browser session endpoints, first-run setup, host power controls, console, exec, factory reset, network changes, image ingestion, and template mutation are intentionally outside this surface.

Note

API keys are for trusted automation on networks you control. Do not expose a Lite host directly to the public internet.

Get an API key

1. Open your Virtainer Lite web UI.
2. Go to API Keys.
3. Create a key with one of these scopes:
   • read: read-only calls in the allowlist.
   • readwrite: read-only calls plus VM and AppVM lifecycle mutations.
4. Copy the secret when it is shown. It is only displayed once.

Use the key as a bearer token. The examples use ${baseUrl} as a placeholder for your Lite host URL:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

curl "${baseUrl}/api/vms" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Read endpoints

• GET /api/capacity
• GET /api/vms
• GET /api/vms/{id}
• GET /api/vms/{id}/metrics/history
• GET /api/appvm/vms
• GET /api/appvm/vms/{id}
• GET /api/appvm/vms/{id}/logs and metrics/history
• GET /api/appvm/images
• GET /api/images
• GET /api/networks
• GET /api/registry/images
• GET /api/registry/images/{id}

Mutation endpoints

These require a readwrite API key.

• POST /api/vms
• DELETE /api/vms/{id}
• POST /api/vms/{id}/boot
• POST /api/vms/{id}/shutdown
• POST /api/vms/{id}/reboot
• POST /api/vms/{id}/pause
• POST /api/vms/{id}/resume
• POST /api/vms/{id}/power-button
• POST /api/appvm/vms
• AppVM lifecycle actions and DELETE /api/appvm/vms/{id}

Reference

• Error codes and retry rules
• Install Virtainer Lite

Not available through API keys

These surfaces require a logged-in web session or an operator action, and are intentionally not reachable with API keys:

• First-run setup: /api/setup/*
• API key management: /api/api-keys*
• Host reboot and shutdown: /api/system/reboot, /api/system/shutdown
• Factory reset: /api/factory-reset
• Host settings, SSH settings, diagnostics bundle, and bootc image switching
• Network create, update, delete, or default-network mutation
• Image upload, image prefetch, image delete, registry download
• AppVM image import, build, rebuild, or delete
• Template create, update, delete, or read through API keys
• Console and exec WebSockets
• VM reinstall, VM config patch, VM network patch, volume attach/detach, and redeploy