AppVM lifecycle API

AppVM member operations use the /api/appvm/vms/{id} resource prefix. These routes reject classic VM ids with 404 NOT_FOUND.

Lifecycle actions

The following endpoints require a readwrite API key and no request body:

Method	Path	Success	Behavior
POST	/api/appvm/vms/{id}/boot	204 No Content	Start a created or stopped AppVM.
POST	/api/appvm/vms/{id}/shutdown	204 No Content	Stop the AppVM and tear down its host runtime.
POST	/api/appvm/vms/{id}/reboot	204 No Content	Stop and boot the AppVM.
POST	/api/appvm/vms/{id}/pause	204 No Content	Pause its vCPUs.
POST	/api/appvm/vms/{id}/resume	204 No Content	Resume a paused AppVM.
POST	/api/appvm/vms/{id}/power-button	204 No Content	Request a graceful guest shutdown with forced-stop timeout.
DELETE	/api/appvm/vms/{id}	204 No Content	Delete the AppVM and agent-owned resources.

Example:

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

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

Read GET /api/appvm/vms/{id} after an action to confirm the resulting state and display_state.

Workload logs

GET /api/appvm/vms/{id}/logs requires a read API key and returns the tail of the AppVM workload stdout and stderr log:

{
  "log": "workload output\n"
}

The response is capped at 256 KiB.

Metrics history

GET /api/appvm/vms/{id}/metrics/history requires a read API key. Supply range= with one of 1h, 24h, 7d, 30d, or 1y; it defaults to 1h, and any other value is rejected with 400. An optional from and to pair of Unix timestamps selects an exact window instead, overriding range; sending only one of the pair is rejected with 400.

curl "${baseUrl}/api/appvm/vms/${id}/metrics/history?range=1h" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

The response shape, including the interval_secs the host chose for the window, is documented under GET /api/vms/{id}/metrics/history.

Errors

Status	Code	Description
400	BAD_REQUEST	Query parameters or the requested operation are invalid.
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	The key is read-only for a mutation, or the endpoint is outside the key allowlist.
404	NOT_FOUND	The AppVM id does not exist or belongs to a classic VM.
409	INVALID_STATE	The AppVM state does not allow the lifecycle action.