Key Points
- Control VM power states through REST API endpoints
- Support for graceful and forced power operations
- Monitor VM power state and runtime status
- Understand VM key vs Machine key for different status checks
This guide covers managing virtual machine power states in VergeOS, including starting, stopping, rebooting, and monitoring VMs. The VergeOS API provides comprehensive power management capabilities with both graceful and forced operations.
Stage: VM Power Management (2 of 4)
Input: VM key (42) from creation, power operation type
Output: Power state changes, runtime status
Previous: VM created → VM-Creation-API.md
Common Next Steps:
- Configure VM settings → VM-Configuration.md
- Advanced operations → VM-Advanced-Operations.md
- "How to start/stop VMs via API"
- "Checking VM power status"
- "Graceful vs forced VM shutdown"
- "VM reboot and reset operations"
- "Monitoring VM power state"
- "Power management automation"
- "VM startup troubleshooting"
- "Scheduled power operations"
- "Resource optimization through power control"
- Power Actions:
POST /api/v4/vm_actions
- VM Status:
GET /api/v4/vms/{id}
- Power State:
GET /api/v4/machine_status/{machine_id}
poweron: Start VMpoweroff: Graceful shutdown (ACPI)kill: Force power offreset: Reboot VM
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
VM must be created first → See VM-Creation-API.md
| Operation |
Method |
Endpoint |
Key Type |
Purpose |
| Power On |
POST |
/api/v4/vm_actions |
VM key |
Start virtual machine |
| Power Off |
POST |
/api/v4/vm_actions |
VM key |
Graceful shutdown (ACPI) |
| Force Off |
POST |
/api/v4/vm_actions |
VM key |
Immediate termination |
| Reboot |
POST |
/api/v4/vm_actions |
VM key |
Restart VM |
| VM Info |
GET |
/api/v4/vms/{id} |
VM key |
Configuration data |
| Power State |
GET |
/api/v4/machine_status/{id} |
Machine key |
Runtime status |
- 409 Conflict: VM already running, VM not running, power state mismatch
- 507 Insufficient Resources: Not enough cluster resources, memory/CPU unavailable
- 403 Forbidden: API key permissions, cluster access denied, VM access restricted
- 404 Not Found: Invalid VM key, VM deleted, machine key not found
- 408 Request Timeout: Power operation timeout, VM unresponsive, cluster communication failure
- 500 Internal Server Error: Hypervisor issues, node problems, storage failures
Description: Powers on a virtual machine and waits for it to reach running state.
Power On Request:
{
"action": "poweron",
"params": {},
"vm": "42"
}
Complete API Call:
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "poweron",
"params": {},
"vm": "42"
}'
Response: 201 Created when action is initiated.
Best Practices
- Always verify VM configuration before powering on
- Ensure all required drives and network interfaces are attached
- Check cluster resource availability
- Verify VM is not already running to avoid conflicts
Description: Sends an ACPI shutdown signal to the guest operating system, allowing it to shut down cleanly.
{
"action": "poweroff",
"vm": "42"
}
Complete API Call:
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "poweroff",
"vm": "42"
}'
Description: Immediately terminates the VM without allowing the guest OS to shut down cleanly. Use only when graceful shutdown fails.
{
"action": "kill",
"vm": "42"
}
Complete API Call:
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "kill",
"vm": "42"
}'
Force Power Off
Using kill action may cause data loss or corruption. Always try graceful poweroff first and only use kill when necessary.
Description: Sends an ACPI reset signal to the guest operating system for a clean restart.
{
"action": "reset",
"params": {
"graceful": true
},
"vm": "42"
}
Complete API Call:
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "reset",
"params": {
"graceful": true
},
"vm": "42"
}'
Description: Immediately restarts the VM without allowing the guest OS to shut down cleanly.
{
"action": "reset",
"vm": "42"
}
Complete API Call:
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "reset",
"vm": "42"
}'
Description: Retrieves VM configuration and metadata using various field filters.
Get Complete VM Information:
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \
-H "Authorization: Bearer YOUR_API_KEY"
Response Example:
{
"$key": 42,
"name": "test",
"machine": 54,
"description": "test vm",
"enabled": true,
"created": 1755991665,
"modified": 1755993248,
"is_snapshot": false,
"machine_type": "pc-q35-9.0",
"allow_hotplug": true,
"guest_agent": true,
"cpu_cores": 3,
"cpu_type": "host",
"ram": 16384,
"console": "spice",
"video": "qxl",
"sound": "none",
"os_family": "linux",
"rtc_base": "utc",
"boot_order": "cd",
"console_pass_enabled": false,
"usb_tablet": true,
"uefi": true,
"secure_boot": false,
"serial_port": false,
"boot_delay": 5,
"uuid": "821e96ec-2479-7cc4-7c14-c623557bdd2b",
"need_restart": false,
"console_status": 42,
"cloudinit_datasource": "none",
"imported": false,
"created_from": "custom",
"migration_method": "auto",
"note": "This is a test VM",
"power_cycle_timeout": 0,
"allow_export": true,
"creator": "admin",
"nested_virtualization": true,
"disable_hypervisor": true,
"usb_legacy": false
}
Description: Retrieves the actual runtime status and power state of a VM using the machine key.
Check VM Power State:
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \
-H "Authorization: Bearer YOUR_API_KEY"
{
"$key": 54,
"machine": 54,
"running": false,
"migratable": true,
"node": null,
"migrated_node": null,
"migration_destination": null,
"started": 1755993338,
"local_time": 0,
"status": "stopped",
"status_info": "",
"state": "offline",
"powerstate": false,
"last_update": 1755993358,
"running_cores": 3,
"running_ram": 16384,
"agent_version": "",
"agent_features": [],
"agent_guest_info": []
}
{
"$key": 44,
"machine": 44,
"running": true,
"migratable": true,
"node": 3,
"migrated_node": null,
"migration_destination": null,
"started": 1755460982,
"local_time": 0,
"status": "running",
"status_info": "",
"state": "online",
"powerstate": true,
"last_update": 1755993927,
"running_cores": 6,
"running_ram": 12288,
"agent_version": "",
"agent_features": [],
"agent_guest_info": []
}
VM vs Machine Status
- VM Information (
/api/v4/vms/{vm_key}): Configuration, settings, and metadata
- Power State (
/api/v4/machine_status/{machine_key}): Runtime status, power state, and resource usage
- Always use the machine key (not VM key) to check actual power state and runtime status
Status Fields
powerstate: Boolean indicating if VM is powered onrunning: Boolean indicating if VM is currently runningstatus: Text status ("running", "stopped", etc.)state: Overall state ("online", "offline")node: Which physical node the VM is running on (null if stopped)
For quick power state checks, you can request specific fields:
# Check just the power state
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \
-H "Authorization: Bearer YOUR_API_KEY"
Response:
{
"powerstate": true,
"running": true,
"status": "running"
}
import time
import requests
def wait_for_power_state(machine_id, desired_state, max_retries=10):
"""Wait for VM to reach desired power state"""
for attempt in range(max_retries):
response = requests.get(
f"https://your-vergeos.example.com/api/v4/machine_status/{machine_id}",
params={"fields": "powerstate,running,status"},
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()
if data.get("powerstate") == desired_state:
return True
time.sleep(5) # Wait 5 seconds between checks
return False
# Example usage
if wait_for_power_state("54", True):
print("VM is now running")
else:
print("VM failed to start within timeout")
# Step 1: Attempt graceful shutdown
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "poweroff", "vm": "42"}'
# Step 2: Wait and check status (repeat as needed)
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \
-H "Authorization: Bearer YOUR_API_KEY"
# Step 3: Force shutdown if graceful failed (after reasonable timeout)
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"action": "kill", "vm": "42"}'
# Step 1: Graceful reboot
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "reset",
"params": {"graceful": true},
"vm": "42"
}'
# Step 2: Monitor restart progress
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \
-H "Authorization: Bearer YOUR_API_KEY"
Error: 409 Conflict - VM already running
{
"error": "Cannot power on VM: already in running state"
}
: Check current power state before issuing power commands.
Error: 409 Conflict - VM not running
{
"error": "Cannot power off VM: not in running state"
}
: Verify VM is actually running before attempting shutdown.
Error: 507 Insufficient Resources
{
"error": "Insufficient cluster resources to start VM"
}
: Check cluster resource availability or reduce VM resource requirements.
Set appropriate timeouts for power operations:
- Power On: 30-60 seconds
- Graceful Shutdown: 60-120 seconds
- Force Shutdown: 10-30 seconds
- Reboot: 60-120 seconds
Need Help?
For additional support with VM power management:
- Check the VergeOS documentation portal
- Contact VergeOS support with specific error messages
- Review system logs for detailed error information
- Consult the VergeOS community forums
