VM API¶

The VM API allows you to manage virtual machines on your Unraid server. This includes starting, stopping, and monitoring VMs.

Available Methods¶

get_vms¶

Retrieves a list of all virtual machines on the Unraid server.

def get_vms() -> List[VMModel]

Returns: A list of VMModel objects representing each virtual machine.

Example:

# Synchronous client
from unraid_api import UnraidClient

client = UnraidClient("192.168.1.10", api_key="your-api-key")
vms = client.vm.get_vms()

for vm in vms:
    print(f"VM: {vm.name}, Status: {vm.status}")

# Asynchronous client
import asyncio
from unraid_api import AsyncUnraidClient

async def main():
    client = AsyncUnraidClient("192.168.1.10", api_key="your-api-key")
    vms = await client.vm.get_vms()

    for vm in vms:
        print(f"VM: {vm.name}, Status: {vm.status}")

asyncio.run(main())

get_vm¶

Retrieves information about a specific virtual machine.

def get_vm(vm_id: str) -> VMModel

Parameters:

• vm_id (str): The ID or name of the VM to retrieve.

Returns: A VMModel object representing the specified VM.

Raises:

• APIError: If the VM does not exist or cannot be accessed.

Example:

# Get a specific VM
vm = client.vm.get_vm(vm_id="windows10")
print(f"VM: {vm.name}, Status: {vm.status}")

start_vm¶

Starts a virtual machine.

def start_vm(vm_id: str) -> bool

Parameters:

• vm_id (str): The ID or name of the VM to start.

Returns: True if the VM was successfully started, False otherwise.

Raises:

• APIError: If the VM does not exist or cannot be started.

Example:

# Start a VM
result = client.vm.start_vm(vm_id="windows10")
if result:
    print("VM started successfully")

stop_vm¶

Stops a virtual machine.

def stop_vm(vm_id: str, force: bool = False) -> bool

Parameters:

• vm_id (str): The ID or name of the VM to stop.
• force (bool, optional): Whether to force stop the VM. Default is False.

Returns: True if the VM was successfully stopped, False otherwise.

Raises:

• APIError: If the VM does not exist or cannot be stopped.

Example:

# Stop a VM gracefully
result = client.vm.stop_vm(vm_id="windows10")
if result:
    print("VM stopped successfully")

# Force stop a VM
result = client.vm.stop_vm(vm_id="windows10", force=True)
if result:
    print("VM force stopped")

restart_vm¶

Restarts a virtual machine.

def restart_vm(vm_id: str) -> bool

Parameters:

• vm_id (str): The ID or name of the VM to restart.

Returns: True if the VM was successfully restarted, False otherwise.

Raises:

• APIError: If the VM does not exist or cannot be restarted.

Example:

# Restart a VM
result = client.vm.restart_vm(vm_id="windows10")
if result:
    print("VM restarted successfully")

pause_vm¶

Pauses a running virtual machine.

def pause_vm(vm_id: str) -> bool

Parameters:

• vm_id (str): The ID or name of the VM to pause.

Returns: True if the VM was successfully paused, False otherwise.

Raises:

• APIError: If the VM does not exist or cannot be paused.

Example:

# Pause a VM
result = client.vm.pause_vm(vm_id="windows10")
if result:
    print("VM paused successfully")

resume_vm¶

Resumes a paused virtual machine.

def resume_vm(vm_id: str) -> bool

Parameters:

• vm_id (str): The ID or name of the VM to resume.

Returns: True if the VM was successfully resumed, False otherwise.

Raises:

• APIError: If the VM does not exist or cannot be resumed.

Example:

# Resume a VM
result = client.vm.resume_vm(vm_id="windows10")
if result:
    print("VM resumed successfully")

Model Reference¶

VMModel¶

Represents a virtual machine on the Unraid server.

Properties: