GET /api/appvm/images

List OCI images already imported into this Lite host.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/appvm/images

read

List OCI images already imported into this Lite host.

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/images" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.

Response

Returns an object with ready images and in-flight imports.

Object	Field	Type	Presence	Description
Response	images	array of objects	always	Ready AppVM templates on disk.
	imports	array of objects	always	In-flight or failed imports. This list is memory-backed and can be empty after agent restart.
images[]	id	string	always	AppVM image id. Use this as image_id in POST /api/appvm/vms.
	reference	string	always	OCI reference used to import or build the image.
	digest	string	always	Source manifest digest.
	tags	array of strings	always	Tags observed at import time that pointed to the same digest.
	fs_bytes	integer	always	Template filesystem virtual size in bytes.
	process	object	always	Effective OCI process defaults. Nested fields are documented in the images[].process rows below.
	healthcheck	object	optional	Docker-style healthcheck when present. Omitted when the image has no healthcheck.
	created_at	string	always	Template creation timestamp.
	build	object	optional	Build source metadata for Dockerfile or git-built images.
	disk_bytes	integer	always	Host disk usage of the template qcow2.
images[].process	args	array of strings	always	Default command arguments from the OCI image.
	env	array of strings	always	Default environment entries in KEY=VALUE form.
	cwd	string	always	Default working directory.
	user	string	always	Default user from the OCI image.
images[].healthcheck	test	array of strings	always when healthcheck exists	Executable healthcheck command. Docker CMD-SHELL checks are normalized to /bin/sh -c ….
	interval_secs	integer	always when healthcheck exists	Interval between healthcheck runs, in seconds.
	timeout_secs	integer	always when healthcheck exists	Healthcheck timeout, in seconds.
	retries	integer	always when healthcheck exists	Consecutive failed checks required before the workload is unhealthy.
	start_period_secs	integer	always when healthcheck exists	Startup grace period before failures count.
images[].build	dockerfile	string	always when build exists	Inline Dockerfile source for local builds. Empty for git-sourced builds.
	context_sha256	string	optional	SHA-256 digest of the persisted build context tar.
	git	object	optional	Git build source. Nested fields are documented in the images[].build.git rows below.
images[].build.git	url	string	always when git exists	Public git repository URL.
	git_ref	string	optional	Branch, tag, or commit. Omitted means the repository default branch.
	subdir	string	optional	Build context subdirectory. Omitted means repository root.
	dockerfile	string	optional	Dockerfile path inside the repository context. Omitted means Dockerfile.
imports[]	id	string	always	Image id being imported.
	reference	string	always	OCI reference being imported.
	status	string	always	importing or failed.
	error	string	failed imports only	Import failure message.

Examples

Call example

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

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

Response example

{
  "images": [
    {
      "id": "nginx_latest",
      "reference": "docker.io/library/nginx:latest",
      "digest": "sha256:0123456789abcdef",
      "tags": ["latest"],
      "fs_bytes": 2147483648,
      "process": {
        "args": ["nginx", "-g", "daemon off;"],
        "env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"],
        "cwd": "/",
        "user": "0"
      },
      "created_at": "2026-07-03T10:00:00Z",
      "disk_bytes": 536870912
    }
  ],
  "imports": []
}

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.
500	STORAGE_ERROR	The host could not read AppVM image metadata.