GET /api/appvm/vms

List the AppVMs known to this Lite host. Classic VMs are exposed by GET /api/vms, not by this collection.

The response is a pagination envelope (items + page metadata), and the collection accepts query parameters for paging and filtering. Items are ordered newest-first (created_at descending, id as tiebreaker) so pages are stable.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/appvm/vms

read

List AppVM instances and workload status.

Use your host URL and API key as shell variables:

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

cURL template

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

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.
Query	page	integer	no	1-based page number. Defaults to 1; a page past the end returns an empty items.
Query	per_page	integer	no	Items per page. Defaults to 50, clamped to 1–200.
Query	state	string	no	Comma-separated states to include, e.g. running,stopped. Matches either the display state or the underlying lifecycle state, so running also returns AppVMs still booting.
Query	q	string	no	Case-insensitive substring match over id, discovered IPv4, hostname, and image id.
Query	network_id	string	no	Only AppVMs attached to this VM network id.
Query	image_id	string	no	Only AppVMs built from this image id.

Response

Returns a pagination envelope whose items are AppVM VmView objects. Common VM fields describe the microVM runtime; the appvm object describes its OCI-derived workload.

Field	Type	Description
items	VmView[]	The AppVMs on this page (see schema below).
page	integer	Echoed 1-based page number.
per_page	integer	Effective page size after clamping.
total	integer	Total AppVMs matching the filters, across all pages.
total_pages	integer	Number of pages at this per_page (0 when total is 0).

Fields marked optional are omitted from the JSON object when they have no value. Fields marked nullable are always present and use null when they do not apply.

VmView

Field	Type	Presence	Description
id	string	always	AppVM id.
state	string	always	Stored lifecycle state: created, running, paused, stopped, or failed.
display_state	string	always	User-facing state. In addition to lifecycle states, classic VM provisioning can report booting, downloading, creating, or provision_failed.
vcpus	integer	always	Assigned vCPU count.
memory_mb	integer	always	Assigned memory in MiB.
kernel_path	string or null	nullable	PVH kernel path when direct kernel boot is used.
firmware_path	string or null	nullable	Firmware path when firmware boot is used.
disk_path	string	always	Root disk path on the Lite host. An in-progress classic provision returns an empty string until the disk exists.
volumes	array of VmVolume	always	Attached data volumes, in disk order. The item shape is documented below.
seed_disk	SeedDisk	optional	The host-generated cloud-init seed disk. Present only on a VM with cloud_init. It is not a data volume and cannot be detached, but it does occupy a guest device letter.
cmdline	string	always	Kernel command line.
console_socket_path	string	always	Host serial-console socket path. An in-progress classic provision returns an empty string.
failure_reason	FailureReason	optional	Human-readable and machine-readable failure details.
pid	integer	optional	Cloud Hypervisor process id when known.
nets	array of VmNetwork	always	Network interfaces in order: index 0 is the guest's eth0. Empty array when the AppVM has no interface.
platform	VmPlatform	optional	SMBIOS platform values.
disk	VmDisk	optional	Agent-managed root disk metadata.
image	VmImage	optional	Classic VM source image identity.
cloud_init	CloudInitView	optional	Classic VM cloud-init view. API-key responses omit cloud_init.password.
io_limit	DiskIoLimit	optional	Root-disk throughput ceiling. Omitted when the disk is unthrottled.
nested	boolean	optional	Whether the guest may itself run KVM. Omitted when never set explicitly, which means the hypervisor default applies.
cpu_affinity	array of integers	optional	Host logical CPUs the vCPUs are pinned to. Omitted when unpinned.
cpu_topology	CpuTopology	optional	Guest-visible CPU topology. Omitted when the hypervisor default applies.
pci_devices	array of strings	always	Passed-through host PCI devices, as full BDF strings such as 0000:07:00.0. Empty array when nothing is passed through.
balloon_mb	integer	optional	Memory reclaim target in MiB. Omitted when no memory is being reclaimed.
created_at	RFC 3339 string	optional	Creation timestamp.
discovered_ipv4	string	optional	Observed guest IPv4 address.
guest_panicked_at	RFC 3339 string	optional	When a guest kernel panic was observed over pvpanic. state stays running: the hypervisor is alive and the guest is not.
shutting_down	boolean	optional	Present as true while ACPI shutdown is pending; omitted when false.
mode	string	always	Always appvm on this endpoint.
appvm	AppvmView	always	AppVM image, network, workload, health, restart, mount, and redeploy state.

volumes[] (VmVolume)

Field	Type	Presence	Description
id	string	always	Stable per-VM volume id, such as data0.
path	string	always	Volume file path on the Lite host.
virtual_size_bytes	integer	always	Virtual size visible to the guest, in bytes.
fmt	string	always	Volume image format. Currently qcow2.
readonly	boolean	always	Whether the volume is attached read-only.
owned	boolean	always	Whether the agent owns and manages the volume file. true means deleting the VM erases it.
volume_id	string	optional	Id of the matching first-class volume, whose lifetime is independent of this VM. Omitted for a VM-owned disk.
device	string	always	Guest block device, such as /dev/vdc. Derived from disk order, so detaching an earlier disk shifts this one down a letter. Mount by UUID or label in the guest, never by device letter.
disk_bytes	integer	optional	Bytes the volume file actually occupies, which is smaller than virtual_size_bytes for a sparse image. Only the single-VM read fills this in; list responses omit it rather than pay a stat per row.

seed_disk (SeedDisk)

Field	Type	Presence	Description
device	string	always	Guest block device holding the cloud-init seed. It sits directly after the root disk, so data volumes on a cloud-init VM start one letter later than on a VM without one.
size_bytes	integer	always	Size the guest sees. Fixed, and small: the seed holds only the rendered cloud-init files.

io_limit (DiskIoLimit)

Field	Type	Presence	Description
bps_total	integer	optional	Combined read and write ceiling in bytes per second. Omitted when unlimited.
iops_total	integer	optional	Combined read and write ceiling in IO operations per second. Omitted when unlimited.

cpu_topology (CpuTopology)

Field	Type	Presence	Description
sockets	integer	always	Guest-visible socket count.
cores	integer	always	Cores per socket.
threads	integer	always	Threads per core. sockets × cores × threads always equals vcpus.

failure_reason (FailureReason)

Field	Type	Presence	Description
detected_at	RFC 3339 string	always	Time the failure was detected.
summary	string	always	One-line operator-readable explanation.
detail	object	always	Tagged machine-readable detail. kind is one of socket_gone, socket_dead, ping_timeout, process_exit, process_signal, missing_pid, disk_missing, invalid_vm_id, boot_timeout, or provision_failed.
detail.kind	string	always	Failure-detail discriminator.
detail.code	integer	conditional	Process exit code when kind is process_exit.
detail.signum	integer	conditional	Signal number when kind is process_signal.
detail.path	string	conditional	Missing disk path when kind is disk_missing.
detail.id	string	conditional	Invalid VM id when kind is invalid_vm_id.
detail.seconds	integer	conditional	Timeout duration when kind is boot_timeout.
cause	string	always	Higher-level cause: operator_shutdown, guest_shutdown, ch_crash, vmm_hang, disk_missing, boot_timeout, provision_failed, record_invalid, or unknown.

nets[] (VmNetwork)

Field	Type	Presence	Description
mode	string	always	Network mode. Currently bridge.
bridge	string	always	Host bridge interface.
tap_name	string	always	Agent-created tap interface.
mac	string	always	Guest MAC address.
network_id	string	optional	Host network id.
vlan_tag	integer	optional	802.1Q VLAN tag.
ipv4	VmNetworkIpConfig	optional	IPv4 assignment metadata.
ipv6	VmNetworkIpConfig	optional	IPv6 assignment metadata.
mtu	integer	optional	Interface MTU.
isolated	boolean	optional	Per-VM bridge port-isolation override.
spoof_guard	boolean	optional	Per-VM anti-spoof override.
rate_limit_mbps	integer	optional	Symmetric network rate limit in Mbps.
allowed_ips	array of strings	optional	Extra source addresses or CIDRs anti-spoof lets through, beyond the interface's own address. Omitted when empty.
dhcp_snooped_ipv4	string	optional	Guest IPv4 learned from the upstream DHCP ACK. Authoritative, and the preferred source for discovered_ipv4. Only set on an interface with no static ipv4.
last_observed_ipv4	string	optional	Last IPv4 seen for this MAC in the host neighbor table. Guest-asserted, so it is a display fallback only, and it survives ARP expiry.

nets[].ipv4 / nets[].ipv6 (VmNetworkIpConfig)

Field	Type	Presence	Description
address	string	always	CIDR address.
gateway	string	optional	Gateway address without a CIDR suffix.
dns_servers	array of strings	optional	DNS server addresses.

platform (VmPlatform)

Field	Type	Presence	Description
serial_number	string	optional	SMBIOS serial number.

disk (VmDisk)

Field	Type	Presence	Description
mode	string	always	Root disk mode. Currently copy.
base_path	string	always	Canonical source image path.
virtual_size_bytes	integer	always	Virtual size visible to the guest, in bytes.
owned	boolean	always	Whether the agent owns and manages the root disk file.
image_fmt	string	optional	Root disk image format. Currently qcow2.
qsd_pid	integer	optional	Storage process id.
qsd_start_time	integer	optional	Storage process start time in boot-relative clock ticks.
qsd_blk_socket	string	optional	Root-disk block socket path.
qsd_qmp_socket	string	optional	Storage control socket path.
runtime	VolumeRef	optional	Backend-independent runtime identity.

disk.runtime (VolumeRef)

Field	Type	Presence	Description
backend	string	always	Storage backend. Currently qsd.
pid	integer	always	Storage process id.
start_time	integer	always	Storage process start time in boot-relative clock ticks.
blk_socket	string	always	Root-disk block socket path.
qmp_socket	string	always	Storage control socket path.

image (VmImage)

Field	Type	Presence	Description
image_id	string	always	Source image id.
distro	string	optional	Distribution name.
version	string	optional	Distribution version.

cloud_init (CloudInitView)

Field	Type	Presence	Description
hostname	string	always	Guest hostname.
user	string	always	Guest account configured by cloud-init.
ssh_authorized_keys	array of strings	always	SSH public keys.
password	string	optional	Guest password. This field is always omitted from API-key responses.
network	CloudInitNetwork	optional	Rendered static guest network input.
instance_id	string	always	NoCloud instance identity.
console_autologin	boolean	always	Whether serial-console auto-login is enabled.
sudo	boolean	always	Whether a non-root cloud-init user receives sudo access.

cloud_init.network (CloudInitNetwork)

Field	Type	Presence	Description
ipv4	CloudInitIpConfig	always	Static IPv4 configuration.
ipv6	CloudInitIpConfig	optional	Static IPv6 configuration.

cloud_init.network.ipv4 / ipv6

Field	Type	Presence	Description
address	string	always	CIDR address.
gateway	string	optional	Gateway address without a CIDR suffix.
dns	array of strings	optional	DNS server addresses. This field is named dns, not dns_servers.

appvm (AppvmView)

Field	Type	Presence	Description
image_id	string	always	Source AppVM image id.
hostname	string	optional	Configured guest hostname. For DHCP-derived hostnames, use lease.hostname.
network_mode	string	always	static or dhcp.
ip	string	optional	Configured IPv4 address in static mode.
prefix	integer	optional	Configured IPv4 prefix length in static mode.
gateway	string	optional	Configured gateway in static mode.
dns	array of strings	optional	Configured DNS servers in static mode; omitted when empty.
lease	AppvmLease	optional	Latest guest-reported DHCP lease.
args	array of strings	optional	Effective workload argument vector; omitted when empty.
cwd	string	optional	Workload working directory; omitted when it is /.
user	string	optional	Account the workload runs as; omitted when empty.
env	array of AppvmEnvVar	optional	Effective environment. Secret values are never returned.
workload_exit_code	integer	optional	Last workload exit code.
workload_exit_signal	integer	optional	Last terminating signal number.
workload_fatal	string	optional	Guest-side startup failure.
spec_pending	boolean	optional	Present as true when the stored spec has edits that only take effect on the next boot; omitted when false.
spec	AppvmSpecView	always	The stored workload spec the AppVM boots from.
health	string	optional	starting, healthy, or unhealthy.
health_failing_streak	integer	optional	Consecutive failed health checks; omitted when zero.
healthcheck	object	optional	Effective health-check definition; omitted when the workload has none.
extra_hosts	array of objects	optional	Additional /etc/hosts entries injected into the guest; omitted when empty.
injected_files	array of InjectedFile	optional	Config and secret files written into the guest. Secret contents are never returned. Omitted when empty.
tmpfs_mounts	array of objects	optional	tmpfs mounts created inside the guest; omitted when empty.
last_heartbeat_at	RFC 3339 string	optional	When the guest agent last checked in over vsock. Omitted before the first heartbeat.
heartbeat_stale	boolean	optional	Present as true when heartbeats stopped arriving while the AppVM is still running, which means the guest side is unreachable even though the hypervisor is alive. Omitted when false.
log_stream_detached	boolean	optional	Present as true when workload log and exit-code collection detached after an agent restart.
restart_policy	string	always	no, on-failure, or always.
restart_count	integer	optional	Consecutive automatic restart count; omitted when zero.
last_restart_at	RFC 3339 string	optional	Latest automatic restart timestamp.
data_mounts	array of DataMount	optional	Guest device-to-mountpoint mappings; omitted when empty.
build_digest	string	optional	Short digest of the build used by this AppVM.
update_available	boolean	optional	Present as true when the source image has a newer build.
redeploying	boolean	optional	Present as true while redeploy is in progress.
redeploy_error	string	optional	Last redeploy failure.

appvm.lease (AppvmLease)

Field	Type	Presence	Description
ip	string	always	Leased IPv4 address.
prefix	integer	always	IPv4 prefix length.
gateway	string	optional	Lease gateway.
dns	array of strings	optional	Lease DNS servers; omitted when empty.
search	array of strings	optional	DNS search domains; omitted when empty.
lease_secs	integer	optional	Lease duration in seconds; omitted for an indefinite or unknown duration.
hostname	string	optional	Effective guest hostname.
reported_at	RFC 3339 string	always	Time the agent received the lease report.

appvm.env[] (AppvmEnvVar)

Field	Type	Presence	Description
key	string	always	Environment variable name.
value	string	optional	Environment variable value. Omitted when secret is true.
secret	boolean	optional	Present as true for a secret variable; omitted when false.

appvm.injected_files[] (InjectedFile)

Field	Type	Presence	Description
path	string	always	Absolute path the file is written to inside the guest.
mode	integer	always	File permission bits.
secret	boolean	always	Whether the file holds a secret. Contents are never returned either way; this says why.

appvm.spec (AppvmSpecView)

Field	Type	Presence	Description
keepalive	boolean	always	Whether the guest stays up after the workload exits.
command	array of strings	always	Workload argument vector. Empty means the image entrypoint applies.
env	array of strings	always	Non-secret environment entries in KEY=value form.
secret_env_keys	array of strings	always	Names of secret environment variables. Values are never returned.
workdir	string	optional	Working directory override.
user	string	optional	Account override.
no_healthcheck	boolean	always	Whether the image's health check is explicitly disabled.
healthcheck	object	optional	Health-check override.
extra_hosts	array of objects	always	Additional /etc/hosts entries.
config_files	array of objects	always	Non-secret files injected into the guest, with contents.
secret_files	array of InjectedFile	always	Secret files injected into the guest. Contents are never returned.
tmpfs_mounts	array of objects	always	tmpfs mounts created inside the guest.
restart_policy	string	always	no, on-failure, or always.
stop_grace_secs	integer	optional	Seconds the guest gets to stop before it is forced.

appvm.data_mounts[] (DataMount)

Field	Type	Presence	Description
device	string	always	Guest block-device path.
mountpoint	string	always	Absolute mount path inside the workload root filesystem.
read_only	boolean	always	Whether the guest mounts it read-only.

Examples

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

curl "${baseUrl}/api/appvm/vms?page=1&per_page=50" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

{
  "items": [
  {
    "id": "demo-api-appvm",
    "state": "running",
    "display_state": "running",
    "vcpus": 2,
    "memory_mb": 2048,
    "kernel_path": null,
    "firmware_path": null,
    "disk_path": "/var/lib/virtainer/vms/demo-api-appvm/root.qcow2",
    "volumes": [
      {
        "id": "data0",
        "path": "/var/lib/virtainer/vms/demo-api-appvm.data0.qcow2",
        "virtual_size_bytes": 10737418240,
        "fmt": "qcow2",
        "readonly": false,
        "owned": true
      }
    ],
    "cmdline": "console=hvc0",
    "console_socket_path": "/run/virtainer/demo-api-appvm/console.sock",
    "pid": 4243,
    "nets": [
      {
        "mode": "bridge",
        "bridge": "vmbr0",
        "tap_name": "vtdemoapp0",
        "mac": "02:00:00:65:43:21",
        "network_id": "default"
      }
    ],
    "pci_devices": [],
    "created_at": "2026-07-03T10:05:00Z",
    "discovered_ipv4": "10.77.23.21",
    "mode": "appvm",
    "appvm": {
      "image_id": "nginx_latest",
      "hostname": "demo-api-appvm",
      "network_mode": "dhcp",
      "lease": {
        "ip": "10.77.23.21",
        "prefix": 24,
        "gateway": "10.77.23.1",
        "dns": ["10.77.23.1"],
        "search": ["example.internal"],
        "lease_secs": 3600,
        "hostname": "demo-api-appvm",
        "reported_at": "2026-07-03T10:05:08Z"
      },
      "args": ["nginx", "-g", "daemon off;"],
      "env": [
        {"key": "PORT", "value": "8080"},
        {"key": "APP_SECRET", "secret": true}
      ],
      "health": "healthy",
      "restart_policy": "on-failure",
      "data_mounts": [
        {"device": "/dev/vdb", "mountpoint": "/var/lib/app"}
      ],
      "build_digest": "6d3e8a9f12bc"
    }
  }
  ],
  "page": 1,
  "per_page": 50,
  "total": 1,
  "total_pages": 1
}

Errors

Status	Code	Description
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.