virtuOSo — KVM Virtual Machine Manager for Homelabs

Everything you need to run VMs

A complete VM management platform that runs on a single server. No cloud account required.

Browser-Based Access

SSH shell, serial console, and VNC desktop — all from your browser. No client software needed.

Multi-VM Stacks

Define multi-VM deployments as YAML templates. Deploy and tear down entire environments together.

Built-In AI Assistant

Use Claude Code or OpenAI Codex from the built-in chat UI. virtuOSo exposes typed VM tools over MCP.

Terraform Provider

Infrastructure-as-code for your homelab. Manage VMs, SSH keys, and access grants with Terraform.

Multi-User Access Control

Create user accounts with per-VM permissions. Admins control who can see and manage each VM.

Encrypted Secrets

Inject passwords, API keys, and tokens into VMs at deploy time. Values encrypted at rest with AES-256-GCM.

Cloud-Init Scripts

Run custom shell scripts on first boot. Install packages, configure services, and set up your environment automatically.

NAT & Bridged Networking

Use NAT for isolated VMs or bridged mode to put VMs directly on your LAN with real IP addresses.

Quick Launch

Spin up a VM in one click with pre-configured defaults. The fastest way to get a test environment running.

See it in action

A clean, intuitive interface for managing your entire VM fleet from the browser.

See all your VMs at a glance

Launch any major Linux distribution

Cloud images download automatically. Just pick an OS and go.

Ubuntu

25.10 24.04 LTS 22.04 LTS

Desktop available · User: ubuntu

Fedora

Desktop available · User: fedora

Amazon Linux

2023

User: ec2-user

Custom ISOs

Any OS

Upload ISOs · Boot via VNC

Instance Sizes

Size	vCPUs	Memory	Default Disk
`micro`	1	1 GB	50 GB
`small`	1	2 GB	50 GB
`medium`	2	4 GB	50 GB
`large`	2	8 GB	100 GB
`xlarge`	4	16 GB	100 GB

Deploy entire environments with Stacks

Define multi-VM deployments as YAML templates. Reference VM IPs across the stack with template variables. Deploy and tear down as a unit.

Dependency ordering VMs launch in the right order. IP addresses are resolved before dependent VMs start.
Template variables Use ${vm.name.ip} and ${secret.KEY} to wire VMs together at deploy time.
Reusable templates Save stack templates to a library and reuse them across deployments.
Encrypted secrets Inject sensitive values without hardcoding them in your YAML. AES-256-GCM encryption at rest.

stack.yaml

vms:
  - name: database
    os: ubuntu-24.04
    size: large
    disk: 200
    user-script: |
      apt-get update
      apt-get install -y postgresql
      sudo -u postgres psql -c \
        "ALTER USER postgres PASSWORD
         '${secret.DB_PASSWORD}';"

  - name: web
    os: ubuntu-24.04
    size: medium
    depends_on: [database]
    user-script: |
      apt-get update
      apt-get install -y nginx
      # IP resolved at deploy time
      echo "DB=${vm.database.ip}" \
        >> /etc/environment

Automate everything

Choose the control surface that fits the job: direct API calls, Terraform plans, or AI assistants connected through the built-in MCP server.

REST API

Complete VM lifecycle management via JSON endpoints. Create API keys from the web UI and use them with any HTTP client.

python

import requests

API = "https://your-server/api/v1"
KEY = "vmk_..."
s = requests.Session()
s.headers["Authorization"] = f"Bearer {KEY}"

# Launch a VM
resp = s.post(f"{API}/vms", json={
    "name": "web-01",
    "os": "ubuntu-24.04",
    "size": "medium",
})
print(resp.json())

GETPOSTPUTDEL 20+ endpoints

Terraform Provider

Declare your infrastructure in HCL. The provider manages VMs, SSH keys, and access grants with full lifecycle support.

main.tf

resource "virtuoso_vm" "web" {
  name      = "web-server"
  size      = "medium"
  os        = "ubuntu-24.04"
  disk_gb   = 40
  ssh_key   = virtuoso_ssh_key.deploy.public_key
  started   = true
  autostart = true

  user_script = <<-EOT
    apt-get update
    apt-get install -y nginx
  EOT
}

virtuoso_vm virtuoso_ssh_key virtuoso_vm_access

AI Assistant + MCP

The built-in AI Assistant supports Claude Code and OpenAI Codex.

codex / claude

Hello! I'm your virtuOSo AI assistant.

I can help you manage VMs, generate Terraform configs, create Stack definitions, and more.

What would you like to do?

Claude Code OpenAI Codex 15 MCP tools

WireGuard VPN

Built-in WireGuard server for secure remote access to your VMs from anywhere. Manage peer configs directly from the web UI.

AI-Safe Guardrails

Credentials stay out of AI responses, delete protection is respected, and ambiguous destructive prompts are treated as conversation instead of bulk VM operations.

Delete Protection

Guard important VMs against accidental deletion. Protection must be explicitly disabled before a VM can be removed.

ISO Boot

Upload custom ISOs and boot VMs from them for manual OS installations. VNC is auto-enabled for installer interaction.

Get started

virtuOSo is distributed as a bootable ISO. Install it on dedicated hardware and you're managing VMs from your browser in minutes.

System Requirements: x86_64 CPU · UEFI boot · 16 GB+ RAM · SSD recommended

Download & Install

Download the virtuOSo ISO and install it on dedicated hardware.

Open the UI

Navigate to your server's IP in a browser. Log in with the admin credentials created during install.

Launch a VM

Click Launch, pick an OS and size, and your VM will be running in seconds. Use Quick Launch for one-click creation.

View on GitHub Read the Docs

On this page

Topic Guides
Overview
AI Assistant
Dashboard
Launching VMs
VM Management
Quick Launch
Networking
Shell & Console Access
Profile & SSH Keys
Settings (Admin)

Topic Guides

In-depth documentation for specific features:

Stacks

Multi-VM deployments as YAML templates. Define, deploy, and tear down groups of VMs together.

REST API

Programmatic VM management with API keys. Full endpoint reference with curl, Python, Go, and PowerShell examples.

Terraform Provider

Infrastructure-as-code for virtuOSo. Manage VMs, SSH keys, and access grants with Terraform.

MCP Server

Use Claude Code and OpenAI Codex with the built-in AI Assistant or connect external MCP clients to structured VM tools.

Overview

virtuOSo is a web-based KVM virtual machine manager for homelabs. It lets you create, manage, and access Ubuntu, Fedora, and Amazon Linux VMs from your browser using libvirt/QEMU.

Key features:

Launch VMs from cloud images or custom ISOs
Browser-based SSH shell, serial console, and VNC desktop access
Multi-VM stacks with YAML templates and dependency ordering
Built-in AI Assistant with Claude Code and OpenAI Codex support
NAT and bridged networking modes
REST API and Terraform provider for automation
Multi-user access control with per-VM permissions

AI Assistant

The /ai page provides a built-in chat interface backed by the virtuOSo MCP server. It supports both Claude Code and OpenAI Codex, with provider-specific login handled from the web UI.

Structured tools — the AI calls typed VM tools like list_vms, launch_vm, and change_vm_network
Built-in auth flows — Claude Code uses claude auth login; Codex uses codex login --device-auth
Guardrails — credentials are never exposed to the AI, bulk deletion is blocked, and delete protection is enforced

Dashboard

The dashboard (/vms) shows all your virtual machines with live status updates. Each VM row displays:

Name — click to open the VM detail page
State — running, shutoff, creating, or paused
IP address — appears once the VM is online
Resources — vCPUs, memory, disk usage
Cloud-init status — tracks first-boot provisioning progress

The dashboard auto-refreshes every few seconds via HTMX polling so you can watch VMs boot in real time.

Launching VMs

Navigate to Launch to create a new VM. Fill in the form:

Name — alphanumeric characters, hyphens, underscores, and dots (1-63 chars)
OS — choose from Ubuntu 25.10, Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, Fedora 43, or Amazon Linux 2023
Size — micro (1 vCPU / 1 GB), small (1 / 2 GB), medium (2 / 4 GB), large (2 / 8 GB), or xlarge (4 / 16 GB)
Disk — override the default disk size in GB
SSH Key — select a key from your profile or paste one directly
User Script — shell commands to run on first boot via cloud-init
Desktop — installs a desktop environment and enables VNC
Bridged — places the VM on the LAN instead of NAT

Booting from ISO

To install an OS manually, select an ISO from the dropdown instead of a cloud image. ISOs can be uploaded via Settings (Storage tab). ISO-booted VMs automatically get VNC enabled so you can interact with the installer.

Tip: After launching, a password is generated and shown once. Copy it before navigating away. You can also view it later on the VM detail page.

VM Management

Click a VM name on the dashboard to open its detail page. Available actions:

Start / Stop / Restart / Kill — lifecycle controls. Stop sends an ACPI shutdown; Kill forces immediate power-off
Delete — permanently destroys the VM and its disk image
Resize Disk — grow the disk while the VM is shut off (disks can only be increased, not shrunk)
Autostart — toggle whether the VM starts automatically when the host boots
Delete Protection — prevent accidental deletion until protection is disabled
Change Network — switch between NAT and bridged networking (requires VM to be shut off)

The detail page also shows the VM password, SSH command, OS info, resource usage, and cloud-init status.

Quick Launch

The dashboard includes quick-launch buttons for common VM configurations. Click a quick-launch option to instantly create a VM with pre-configured settings (OS, size, and name are auto-generated). This is the fastest way to spin up a VM for testing.

Networking

VMs can use one of two network modes:

NAT (default) — VMs get an IP on the 192.168.122.x subnet via libvirt's default network. VMs can reach the internet but are not directly accessible from the LAN
Bridged — VMs get an IP directly from your router's DHCP, appearing as regular devices on your LAN. Requires a host bridge (br0) to be configured on the server

You can switch a VM's network mode from the VM detail page while it's shut off. The admin can configure the default network mode and bridge settings in Settings.

Shell & Console Access

virtuOSo provides three ways to access VMs from the browser:

SSH Shell — browser-based SSH terminal. Uses the VM's IP and default user (e.g., ubuntu for Ubuntu, fedora for Fedora, ec2-user for Amazon Linux). Requires the VM to be running with an IP assigned
Serial Console — direct serial console connection via libvirt. Works even when networking is down or the VM hasn't finished booting. Useful for debugging boot issues
VNC — graphical desktop access. Available when the VM was launched with VNC or desktop mode enabled. Required for ISO-booted VMs to interact with the OS installer

Profile & SSH Keys

The Profile page lets you manage:

SSH Keys — upload public keys that can be injected into VMs at launch. Supports ssh-rsa, ssh-ed25519, and ecdsa-sha2 formats
API Keys — create bearer tokens for the REST API. Keys are shown once at creation and cannot be retrieved later
Secrets — encrypted key-value pairs that can be referenced in stack templates using ${secret.NAME} syntax. Values are encrypted at rest with AES-256-GCM
WireGuard — if enabled by the admin, manage VPN peer configurations for secure remote access to your VMs

Settings (Admin)

Admins can access Settings to configure:

Users — create and delete user accounts, reset passwords, assign admin roles
Network — configure default networking mode and bridge interface
Storage — upload and manage ISO files for manual OS installations
WireGuard — enable/disable the VPN and configure server settings

Admin-only tools are also available in the nav menu: Host Shell for direct terminal access to the server.

Contents

Overview
Template Format
Field Reference
Template Variables
Secrets
Available OS Images
Examples
Lifecycle
REST API
Template Library
Access Control

Overview

Stacks let you define multi-VM deployments as a single YAML template and manage them as a unit. Instead of launching VMs one at a time, you describe all the VMs you need in a template, then deploy and tear them down together.

A stack has three components:

Name — a unique identifier for the stack (same rules as VM names)
Template — a YAML document defining the VMs
State — tracked automatically: undeployed, deployed, or partial

VM names are automatically prefixed with the stack name. For example, a stack called my-app with a VM named web creates a VM called my-app-web.

Template Format

Templates are YAML documents with a single top-level key vms containing a list of VM specifications:

vms:
  - name: web-server
    os: ubuntu-24.04
    size: medium
    disk: 100
    user-script: |
      apt-get update
      apt-get install -y nginx

  - name: database
    os: ubuntu-24.04
    size: large
    disk: 200
    user-script: |
      apt-get update
      apt-get install -y postgresql

Field Reference

Field	Type	Required	Default	Description
`name` required	string	Yes	—	VM name within the stack. Combined with the stack name to form the full VM name (`{stack}-{name}`). Must be unique within the template.
`os` required	string	Yes	—	OS image ID. Available options: `ubuntu-24.04`, `ubuntu-22.04`, `ubuntu-25.10`, `fedora-43`, `amazon-2023`. Append `+desktop` for a desktop environment (e.g. `ubuntu-24.04+desktop`).
`size` required	string	Yes	—	Instance size. One of: `micro` (1 vCPU, 1 GB RAM, 50 GB disk), `small` (1 vCPU, 2 GB RAM, 50 GB disk), `medium` (2 vCPU, 4 GB RAM, 50 GB disk), `large` (2 vCPU, 8 GB RAM, 100 GB disk), `xlarge` (4 vCPU, 16 GB RAM, 100 GB disk)
`disk` optional	int	No	from size	Override disk size in GB. When set, overrides the default disk size for the chosen instance size.
`user-script` optional	string	No	—	Shell commands to run on first boot (via cloud-init). Use YAML `\|` for multi-line scripts. Also accepts `user_script`.
`ssh-key` optional	string	No	—	SSH public key to inject into the VM. Also accepts `ssh_key`.
`vnc` optional	bool	No	false	Enable VNC graphics. Automatically enabled when `desktop` is true.
`desktop` optional	bool	No	false	Install a desktop environment. Implies `vnc: true`. Can also be set by appending `+desktop` to the `os` value.
`depends_on` optional	list	No	[]	List of VM names (from this template) that must be launched and have an IP address before this VM starts. Used to ensure `${vm.X.ip}` variables resolve to real IPs. Also accepts `depends-on`.

Template Variables

Use variables in user-script to reference other VMs in the same stack. Variables are resolved at deploy time.

Variable	Resolves To	When
`${vm.SPECNAME.name}`	Full prefixed VM name (e.g. `mystack-database`)	Deploy time (immediate)
`${vm.SPECNAME.ip}`	Actual IP address of the sibling VM (e.g. `192.168.122.237`)	Deploy time (requires `depends_on` — the dependency is launched first and its IP is collected before this VM starts)
`${secret.NAME}`	Decrypted value of the secret named `NAME`	Deploy time (secret must exist in Profile > Secrets or as a per-stack secret)

SPECNAME is the name field of a VM in the same stack template (not the full prefixed name).

Example — web server connecting to database

vms:
  - name: database
    os: ubuntu-24.04
    size: medium
    user-script: |
      apt-get update
      apt-get install -y postgresql

  - name: web
    os: ubuntu-24.04
    size: small
    depends_on: [database]
    user-script: |
      apt-get update
      apt-get install -y nginx
      # database IP is substituted directly by the host before cloud-init
      echo "DB_HOST=${vm.database.ip}" >> /etc/environment
      echo "DB_VM=${vm.database.name}" >> /etc/environment

Note: To use ${vm.X.ip}, add depends_on: [X] to the VM that needs the IP. The host launches dependencies first, waits for them to get an IP (up to 2 minutes), then substitutes the actual IP address directly into the user-script before the dependent VM is created. No guest-side DNS resolution is needed. Name variables (${vm.X.name}) are replaced instantly and don't require depends_on.

Secrets

Secrets let you inject sensitive values (database passwords, API keys, tokens) into VM user-scripts without hardcoding them in the YAML template. Secret values are encrypted at rest using AES-256-GCM and only decrypted at deploy time.

Scopes

Global secrets — set in Profile > Secrets. Available to all your stacks.
Per-stack secrets — set on the stack detail page > Secrets tab. Override global secrets of the same name for that specific stack.

At deploy time, global secrets are loaded first, then per-stack secrets overlay them. If a per-stack secret has the same name as a global secret, the per-stack value wins.

Usage

Reference secrets in user-script using ${secret.NAME} syntax:

vms:
  - name: database
    os: ubuntu-24.04
    size: large
    user-script: |
      apt-get install -y postgresql
      sudo -u postgres psql -c "ALTER USER postgres PASSWORD '${secret.DB_PASSWORD}';"

  - name: web
    os: ubuntu-24.04
    size: medium
    depends_on: [database]
    user-script: |
      echo "DB_HOST=${vm.database.ip}" >> /etc/environment
      echo "DB_PASSWORD=${secret.DB_PASSWORD}" >> /etc/environment

Security Model

Secret values are write-only — once saved, they are never displayed in the UI or returned by the API.
Values are encrypted with AES-256-GCM using an auto-generated master key stored in the database.
Decrypted values exist only in server memory during deployment and are substituted directly into cloud-init user-scripts.
Secret names may contain letters, digits, hyphens, and underscores (max 128 characters).
If a template references a secret that doesn't exist, the ${secret.NAME} placeholder is left as-is and a warning is logged.

Secrets API

GET /api/v1/secrets API Key

List global secrets (metadata only, values not included).

POST /api/v1/secrets API Key

Field	Type	Required	Description
`name`	string	Yes	Secret name
`value`	string	Yes	Secret value (encrypted at rest)

Response 201 Created: {"ok": true, "name": "DB_PASSWORD"}

GET /api/v1/secrets/{id}/value API Key

Retrieve the decrypted value of a global secret. Response: {"value": "the-secret-value"}

PUT /api/v1/secrets/{id} API Key

Field	Type	Required	Description
`value`	string	Yes	New secret value

Update the value of an existing global secret.

DELETE /api/v1/secrets/{id} API Key

Delete a global secret by ID.

GET /api/v1/stacks/{name}/secrets API Key

List per-stack secrets (metadata only).

POST /api/v1/stacks/{name}/secrets API Key

Create or update a per-stack secret. Same request body as global secrets.

GET /api/v1/stacks/{name}/secrets/{id}/value API Key

Retrieve the decrypted value of a per-stack secret. Response: {"value": "the-secret-value"}

PUT /api/v1/stacks/{name}/secrets/{id} API Key

Update the value of a per-stack secret. Same request body as global update.

DELETE /api/v1/stacks/{name}/secrets/{id} API Key

Delete a per-stack secret by ID.

Available OS Images

Use these values for the os field:

OS ID	Name	Default User	Desktop Available
`ubuntu-25.10`	Ubuntu 25.10	`ubuntu`	Yes — `ubuntu-25.10+desktop`
`ubuntu-24.04`	Ubuntu 24.04 LTS	`ubuntu`	Yes — `ubuntu-24.04+desktop`
`ubuntu-22.04`	Ubuntu 22.04 LTS	`ubuntu`	Yes — `ubuntu-22.04+desktop`
`fedora-43`	Fedora 43	`fedora`	Yes — `fedora-43+desktop`
`amazon-2023`	Amazon Linux 2023	`ec2-user`	No

Tip: The default user is the SSH login username for each OS. For Ubuntu VMs, SSH in with ssh ubuntu@<ip>. For Fedora, use fedora. For Amazon Linux, use ec2-user. A random password is also generated for each VM at deploy time.

Examples

Minimal — two VMs with defaults

vms:
  - name: app
    os: ubuntu-24.04
    size: small
  - name: db
    os: ubuntu-24.04
    size: medium

Web application stack with provisioning

vms:
  - name: nginx
    os: ubuntu-24.04
    size: small
    user-script: |
      apt-get update
      apt-get install -y nginx
      systemctl enable nginx

  - name: app
    os: ubuntu-24.04
    size: medium
    disk: 80
    ssh-key: ssh-ed25519 AAAA... user@host
    user-script: |
      apt-get update
      apt-get install -y nodejs npm

  - name: postgres
    os: ubuntu-24.04
    size: large
    disk: 200
    user-script: |
      apt-get update
      apt-get install -y postgresql
      systemctl enable postgresql

Desktop development environment

vms:
  - name: dev-box
    os: ubuntu-24.04+desktop
    size: large
    disk: 150
    ssh-key: ssh-ed25519 AAAA... user@host
    user-script: |
      snap install code --classic
      apt-get update
      apt-get install -y git build-essential

Mixed OS testing

vms:
  - name: ubuntu-test
    os: ubuntu-24.04
    size: micro
  - name: fedora-test
    os: fedora-43
    size: micro
  - name: amazon-test
    os: amazon-2023
    size: small

Lifecycle

A stack goes through these stages:

Action	What happens
Create	The stack name and template are saved to the database. No VMs are launched yet.
Deploy	VMs are launched in dependency order. VMs with no `depends_on` start first (in parallel), then VMs that depend on them, and so on. Each VM gets an auto-generated password. Non-admin users are automatically granted access to the VMs.
Update Template	The template YAML is updated in the database. Already-deployed VMs are not affected — changes take effect on the next deploy.
Tear Down	All VMs belonging to the stack are deleted (destroyed + disk removed). The stack itself remains so you can redeploy later.
Delete Stack	Tears down all VMs (if any) and then removes the stack from the database entirely.

Note: Deploying a stack does not skip VMs that already exist. If you need to redeploy, tear down first, then deploy again.

REST API

Stacks can be managed programmatically via the REST API. All endpoints require an API key (Authorization: Bearer vmk_...).

List Stacks

GET /api/v1/stacks API Key

Returns all stacks visible to the authenticated user (admins see all, users see their own).

[{
  "name": "my-app",
  "vm_count": 3,
  "deployed": 3,
  "status": "deployed",
  "created_by": 1,
  "created_at": "2026-02-15 12:00:00",
  "updated_at": "2026-02-15 12:00:00"
}]

Create Stack

POST /api/v1/stacks API Key

Field	Type	Required	Description
`name`	string	Yes	Stack name (unique, same rules as VM names)
`template`	string	Yes	YAML template content

Response 201 Created:

{"name": "my-app", "created_at": "2026-02-15 12:00:00"}

Get Stack

GET /api/v1/stacks/{name} API Key

Returns the stack template and live VM status.

{
  "name": "my-app",
  "template": "vms:\n  - name: web\n    os: ubuntu-24.04\n    size: small",
  "vms": [
    {"spec_name": "web", "full_name": "my-app-web", "state": "running", "ip": "192.168.122.10", "cloud_init": "done"}
  ],
  "created_by": 1,
  "created_at": "2026-02-15 12:00:00",
  "updated_at": "2026-02-15 12:00:00"
}

Update Stack Template

PUT /api/v1/stacks/{name} API Key

Field	Type	Required	Description
`template`	string	Yes	Updated YAML template

Response 200 OK: {"ok": true}

Deploy Stack

POST /api/v1/stacks/{name}/deploy API Key

Launches all VMs defined in the template. Returns immediately with 202 Accepted while VMs are created in the background.

{
  "stack": "my-app",
  "vms": [
    {"name": "my-app-web", "password": "aBcDeFgH", "status": "creating"}
  ]
}

Tear Down Stack

POST /api/v1/stacks/{name}/destroy API Key

Deletes all VMs belonging to the stack. The stack itself is preserved.

Response 200 OK: {"ok": true}

Delete Stack

DELETE /api/v1/stacks/{name} API Key

Tears down all VMs and removes the stack from the database.

Response 200 OK: {"ok": true}

Template Library

The template library lets you save stack templates for reuse. Saved templates persist independently of stacks, so you can delete a stack and still reuse its template later.

Saving a Template

On any stack detail page, use the Save as Template form below the YAML editor. Enter a name for the template and click save. The stack's current YAML is saved to your personal library.

Loading a Saved Template

When creating a new stack, a dropdown appears above the YAML editor if you have saved templates. Select a template and click Load to populate the editor with the saved YAML. You can edit it before creating the stack.

Deleting a Saved Template

On the new stack page, select a template from the dropdown and click the Delete button to remove it from your library.

Template Library API

GET /api/v1/stack-templates API Key

Returns all saved templates belonging to the authenticated user.

[{"id": 1, "name": "web-app", "template": "vms:\n  ...", "created_at": "2026-02-15 12:00:00"}]

POST /api/v1/stack-templates API Key

Field	Type	Required	Description
`name`	string	Yes	Template name (unique per user)
`template`	string	Yes	YAML template content

Response 201 Created: {"ok": true, "name": "web-app"}

DELETE /api/v1/stack-templates/{id} API Key

Deletes a saved template by ID. Only the owner can delete their templates.

Response 200 OK: {"ok": true}

Access Control

Admin users can see and manage all stacks.
Regular users can only see and manage stacks they created.
When a non-admin deploys a stack, they are automatically granted access to the created VMs.
Deployed VMs appear on the Dashboard like any other VM — they can be individually started, stopped, and accessed via shell/VNC.

Contents

Overview
Authentication
Client Examples — curl, Python, Go, PowerShell
Error Format
Quick Reference
API Keys
Current User
VMs
Users (Admin)
VM Access (Admin)
SSH Keys

Overview

Base URL: /api/v1/
Content-Type: All requests and responses use application/json
Versioning: Via the URL path (v1)

Authentication

The API uses two authentication methods:

1. Session Cookies (API key bootstrap)

The three /api/v1/auth/apikeys endpoints use the same session cookies as the web UI. You can also create API keys from the Profile page.

2. Bearer Token (everything else)

All other endpoints require an API key as a Bearer token:

Authorization: Bearer vmk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Admin-only endpoints additionally require the key to belong to an admin user.

Getting Started

Go to Profile and create an API key
Copy the key (it's only shown once)
Use it in the Authorization header for API calls

Client Examples

Complete working examples in four languages. Replace YOUR_API_KEY and your-server with your actual values.

List VMs

curl -sk https://your-server/api/v1/vms \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

API = "https://your-server/api/v1"
KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {KEY}"}

vms = requests.get(f"{API}/vms", headers=headers, verify=False).json()
for vm in vms:
    print(f"{vm['name']:20s} {vm['state']:10s} {vm.get('ip', 'N/A')}")

package main

import (
    "crypto/tls"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    api := "https://your-server/api/v1"
    key := "YOUR_API_KEY"

    client := &http.Client{
        Transport: &http.Transport{
            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
        },
    }

    req, _ := http.NewRequest("GET", api+"/vms", nil)
    req.Header.Set("Authorization", "Bearer "+key)

    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var vms []map[string]any
    json.NewDecoder(resp.Body).Decode(&vms)
    for _, vm := range vms {
        fmt.Printf("%-20s %-10s %s\n", vm["name"], vm["state"], vm["ip"])
    }
}

# Skip TLS verification for self-signed certs
$SkipCert = [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

$Api = "https://your-server/api/v1"
$Headers = @{ "Authorization" = "Bearer YOUR_API_KEY" }

$Vms = Invoke-RestMethod -Uri "$Api/vms" -Headers $Headers -SkipCertificateCheck
$Vms | Format-Table name, state, ip -AutoSize

Launch a VM

curl -sk https://your-server/api/v1/vms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "dev-box",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40
  }'

resp = requests.post(f"{API}/vms", headers=headers, verify=False, json={
    "name": "dev-box",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40,
})
result = resp.json()
print(f"VM {result['name']} is {result['status']}")
print(f"Password: {result['password']}")

body := strings.NewReader(`{
    "name": "dev-box",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40
}`)
req, _ := http.NewRequest("POST", api+"/vms", body)
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")

resp, err := client.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("VM %s is %s (password: %s)\n",
    result["name"], result["status"], result["password"])

$Body = @{
    name    = "dev-box"
    size    = "medium"
    os      = "ubuntu-24.04"
    disk_gb = 40
} | ConvertTo-Json

$Result = Invoke-RestMethod -Uri "$Api/vms" -Method Post `
    -Headers $Headers -Body $Body -ContentType "application/json" `
    -SkipCertificateCheck

Write-Host "VM $($Result.name) is $($Result.status)"
Write-Host "Password: $($Result.password)"

Launch with User Script (cloud-init)

Pass a user_script field to run a script on first boot via cloud-init. The script runs as root after the VM is provisioned.

curl -sk https://your-server/api/v1/vms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "docker-host",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40,
    "user_script": "#!/bin/bash\napt-get update\napt-get install -y docker.io\nsystemctl enable --now docker"
  }'

script = """#!/bin/bash
apt-get update
apt-get install -y docker.io
systemctl enable --now docker
"""

resp = requests.post(f"{API}/vms", headers=headers, verify=False, json={
    "name": "docker-host",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40,
    "user_script": script,
})
print(resp.json())

body := strings.NewReader(`{
    "name": "docker-host",
    "size": "medium",
    "os": "ubuntu-24.04",
    "disk_gb": 40,
    "user_script": "#!/bin/bash\napt-get update\napt-get install -y docker.io\nsystemctl enable --now docker"
}`)
req, _ := http.NewRequest("POST", api+"/vms", body)
req.Header.Set("Authorization", "Bearer "+key)
req.Header.Set("Content-Type", "application/json")

resp, err := client.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
fmt.Printf("VM %s is %s\n", result["name"], result["status"])

$Script = @"
#!/bin/bash
apt-get update
apt-get install -y docker.io
systemctl enable --now docker
"@

$Body = @{
    name        = "docker-host"
    size        = "medium"
    os          = "ubuntu-24.04"
    disk_gb     = 40
    user_script = $Script
} | ConvertTo-Json

$Result = Invoke-RestMethod -Uri "$Api/vms" -Method Post `
    -Headers $Headers -Body $Body -ContentType "application/json" `
    -SkipCertificateCheck

Write-Host "VM $($Result.name) is $($Result.status)"

Launch from ISO

Boot a VM from a custom ISO file. Upload ISOs via the Settings page (Storage tab), then reference the full path. VNC is automatically enabled for ISO boots.

curl -sk https://your-server/api/v1/vms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "custom-os",
    "size": "medium",
    "iso": "/var/lib/vm-lab/vms/isos/ubuntu-server.iso"
  }'

resp = requests.post(f"{API}/vms", headers=headers, verify=False, json={
    "name": "custom-os",
    "size": "medium",
    "iso": "/var/lib/vm-lab/vms/isos/ubuntu-server.iso",
})
print(resp.json())

Launch with Bridged Networking

Use bridged: true to place the VM on the LAN with a real IP from your router's DHCP, instead of the default NAT (192.168.122.x). Requires a host bridge (br0) to be configured on the server.

curl -sk https://your-server/api/v1/vms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "lan-server",
    "size": "medium",
    "os": "ubuntu-24.04",
    "bridged": true
  }'

resp = requests.post(f"{API}/vms", headers=headers, verify=False, json={
    "name": "lan-server",
    "size": "medium",
    "os": "ubuntu-24.04",
    "bridged": True,
})
print(resp.json())

VM Lifecycle (start, stop, restart, kill, delete)

# Start
curl -sk -X POST https://your-server/api/v1/vms/dev-box/start \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Stop (graceful shutdown)
curl -sk -X POST https://your-server/api/v1/vms/dev-box/stop \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Restart
curl -sk -X POST https://your-server/api/v1/vms/dev-box/restart \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Kill (force stop)
curl -sk -X POST https://your-server/api/v1/vms/dev-box/kill \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Delete
curl -sk -X DELETE https://your-server/api/v1/vms/dev-box \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Start
requests.post(f"{API}/vms/dev-box/start", headers=headers, verify=False)

# Stop (graceful shutdown)
requests.post(f"{API}/vms/dev-box/stop", headers=headers, verify=False)

# Restart
requests.post(f"{API}/vms/dev-box/restart", headers=headers, verify=False)

# Kill (force stop)
requests.post(f"{API}/vms/dev-box/kill", headers=headers, verify=False)

# Delete
requests.delete(f"{API}/vms/dev-box", headers=headers, verify=False)

// Helper function for simple actions
func vmAction(client *http.Client, api, key, vm, action, method string) error {
    url := fmt.Sprintf("%s/vms/%s", api, vm)
    if action != "" {
        url += "/" + action
    }
    req, _ := http.NewRequest(method, url, nil)
    req.Header.Set("Authorization", "Bearer "+key)
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    resp.Body.Close()
    return nil
}

vmAction(client, api, key, "dev-box", "start", "POST")    // Start
vmAction(client, api, key, "dev-box", "stop", "POST")     // Stop
vmAction(client, api, key, "dev-box", "restart", "POST")  // Restart
vmAction(client, api, key, "dev-box", "kill", "POST")     // Kill
vmAction(client, api, key, "dev-box", "", "DELETE")        // Delete

# Start
Invoke-RestMethod -Uri "$Api/vms/dev-box/start" -Method Post `
    -Headers $Headers -SkipCertificateCheck

# Stop (graceful shutdown)
Invoke-RestMethod -Uri "$Api/vms/dev-box/stop" -Method Post `
    -Headers $Headers -SkipCertificateCheck

# Restart
Invoke-RestMethod -Uri "$Api/vms/dev-box/restart" -Method Post `
    -Headers $Headers -SkipCertificateCheck

# Kill (force stop)
Invoke-RestMethod -Uri "$Api/vms/dev-box/kill" -Method Post `
    -Headers $Headers -SkipCertificateCheck

# Delete
Invoke-RestMethod -Uri "$Api/vms/dev-box" -Method Delete `
    -Headers $Headers -SkipCertificateCheck

Full Python Script Example

#!/usr/bin/env python3
"""virtuOSo API client example — launch a VM, wait for it, then SSH in."""
import requests, time

API = "https://your-server/api/v1"
KEY = "YOUR_API_KEY"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {KEY}"
s.verify = False

# Launch a VM
resp = s.post(f"{API}/vms", json={
    "name": "test-vm",
    "size": "small",
    "os": "ubuntu-24.04",
})
print(f"Launched: {resp.json()}")

# Poll until it's running and has an IP
for _ in range(60):
    vm = s.get(f"{API}/vms/test-vm").json()
    if vm.get("ip") and vm["state"] == "running" and vm.get("cloud_init") == "done":
        print(f"Ready! IP: {vm['ip']}, password: {vm.get('password', 'N/A')}")
        break
    time.sleep(5)
else:
    print("Timed out waiting for VM")

# Clean up
# s.delete(f"{API}/vms/test-vm")

Error Format

All errors return JSON with error and status fields:

{"error": "VM not found", "status": 404}

Status	Meaning
400	Bad request (invalid input)
401	Unauthorized (missing or invalid auth)
403	Forbidden (admin access required)
404	Not found
409	Conflict (duplicate name)
500	Internal server error

Quick Reference

Method	Endpoint	Auth	Description
POST	`/api/v1/auth/apikeys`	Session	Create API key
GET	`/api/v1/auth/apikeys`	Session	List API keys
DELETE	`/api/v1/auth/apikeys/{id}`	Session	Delete API key
GET	`/api/v1/me`	API Key	Current user info
GET	`/api/v1/vms`	API Key	List VMs
POST	`/api/v1/vms`	API Key	Launch VM
GET	`/api/v1/vms/{name}`	API Key	Get VM details
DELETE	`/api/v1/vms/{name}`	API Key	Delete VM
POST	`/api/v1/vms/{name}/start`	API Key	Start VM
POST	`/api/v1/vms/{name}/stop`	API Key	Graceful shutdown
POST	`/api/v1/vms/{name}/kill`	API Key	Force stop
POST	`/api/v1/vms/{name}/restart`	API Key	Reboot VM
POST	`/api/v1/vms/{name}/resize`	API Key	Resize disk
PUT	`/api/v1/vms/{name}/autostart`	API Key	Set autostart
PUT	`/api/v1/vms/{name}/network`	API Key	Change network mode
PUT	`/api/v1/vms/{name}/protected`	API Key	Set delete protection
GET	`/api/v1/users`	Admin	List users
POST	`/api/v1/users`	Admin	Create user
GET	`/api/v1/users/{id}`	Admin	Get user
DELETE	`/api/v1/users/{id}`	Admin	Delete user
PUT	`/api/v1/users/{id}/password`	Admin	Reset password
GET	`/api/v1/vms/{name}/access`	Admin	List VM access
POST	`/api/v1/vms/{name}/access`	Admin	Grant access
DELETE	`/api/v1/vms/{name}/access/{user_id}`	Admin	Revoke access
GET	`/api/v1/sshkeys`	API Key	List SSH keys
POST	`/api/v1/sshkeys`	API Key	Add SSH key
DELETE	`/api/v1/sshkeys/{id}`	API Key	Delete SSH key

API Keys

API key management uses session cookie auth (not Bearer tokens). Create keys from the Profile page or via these endpoints.

Create API Key

POST /api/v1/auth/apikeys Session

Field	Type	Required	Description
`name`	string	Yes	Display name (unique per user)

Response 201 Created:

{"id": 1, "name": "my-key", "prefix": "vmk_a1b2c3d4", "key": "vmk_a1b2c3d4e5f6...", "created_at": "..."}

The full key value is only returned at creation time. Store it securely.

List API Keys

GET /api/v1/auth/apikeys Session

Response 200 OK:

[{"id": 1, "name": "my-key", "prefix": "vmk_a1b2c3d4", "created_at": "...", "last_used": "..."}]

Delete API Key

DELETE /api/v1/auth/apikeys/{id} Session

Response 200 OK: {"ok": true}

Current User

Get Current User

GET /api/v1/me API Key

Response 200 OK:

{"id": 1, "username": "admin", "role": "admin", "created_at": "..."}

VMs

Admins see all VMs. Regular users only see VMs they've been granted access to.

List VMs

GET /api/v1/vms API Key

Response 200 OK:

[{
  "name": "web-server", "state": "running", "ip": "192.168.122.45",
  "vcpus": 2, "memory_mb": 2048, "autostart": false, "has_vnc": false,
  "disk_cap_gb": 20.0, "disk_used_gb": 4.2, "cloud_init": "done",
  "network": "default", "protected": false
}]

The network field is "default" for NAT or "bridge:br0" for bridged networking. The protected field indicates delete protection — protected VMs cannot be deleted until protection is disabled.

Launch VM

POST /api/v1/vms API Key

Launches asynchronously. Returns immediately with status "creating".

Field	Type	Required	Default	Description
`name`	string	Yes	—	VM name (alphanumeric + hyphens)
`size`	string	No	small	`micro`, `small`, `medium`, `large`, `xlarge`
`os`	string	No*	—	`ubuntu-24.04`, `ubuntu-22.04`, `ubuntu-25.10`, `fedora-43`, `amazon-2023` (append `+desktop` for GUI). Required unless `iso` is set
`iso`	string	No	—	Absolute path to an ISO file on the server. When set, the VM boots from the ISO instead of a cloud image (`os` is ignored, VNC is auto-enabled). ISOs uploaded via Settings are stored in `/var/lib/vm-lab/vms/isos/`
`ssh_key`	string	No	—	SSH public key to inject
`disk_gb`	int	No	20	Disk size in GB
`password`	string	No	auto	VM user password
`vnc`	bool	No	false	Enable VNC graphics
`desktop`	bool	No	false	Desktop environment (implies VNC)
`user_script`	string	No	—	Cloud-init script for first boot
`bridged`	bool	No	false	Use bridged networking instead of NAT. The VM gets an IP directly from the LAN router's DHCP. Requires a host bridge (`br0`) to be configured

Response 202 Accepted:

{"name": "dev-box", "password": "auto-generated-or-provided", "status": "creating"}

Get VM Details

GET /api/v1/vms/{name} API Key

Response 200 OK:

{
  "name": "web-server", "state": "running", "ip": "192.168.122.45",
  "vcpus": 2, "memory_mb": 2048, "autostart": false, "has_vnc": false,
  "disk_cap_gb": 20.0, "disk_used_gb": 4.2, "cloud_init": "done",
  "network": "default", "protected": false,
  "password": "the-vm-password", "os_id": "ubuntu-24.04"
}

Delete VM

DELETE /api/v1/vms/{name} API Key

Stops and permanently deletes the VM and its disk.

Response 200 OK: {"ok": true}

Start VM

POST /api/v1/vms/{name}/start API Key

Response 200 OK: {"ok": true}

Stop VM

POST /api/v1/vms/{name}/stop API Key

Graceful shutdown (ACPI power button).

Response 200 OK: {"ok": true}

Kill VM

POST /api/v1/vms/{name}/kill API Key

Force-stops immediately.

Response 200 OK: {"ok": true}

Restart VM

POST /api/v1/vms/{name}/restart API Key

Response 200 OK: {"ok": true}

Resize VM Disk

POST /api/v1/vms/{name}/resize API Key

VM must be shut off. Disk can only be grown, not shrunk.

Field	Type	Required	Description
`size_gb`	int	Yes	New total disk size in GB

Response 200 OK: {"ok": true}

Set Autostart

PUT /api/v1/vms/{name}/autostart API Key

Field	Type	Required	Description
`enabled`	bool	Yes	true to enable, false to disable

Response 200 OK: {"ok": true}

Change Network Mode

PUT /api/v1/vms/{name}/network API Key

VM must be shut off. Switches between NAT and bridged networking.

Field	Type	Required	Description
`network`	string	Yes	`"default"` for NAT, or `"bridge:br0"` for bridged

Response 200 OK: {"ok": true}

Set Delete Protection

PUT /api/v1/vms/{name}/protected API Key

Enables or disables delete protection. Protected VMs cannot be deleted until protection is removed.

Field	Type	Required	Description
`protected`	bool	Yes	true to enable, false to disable

Response 200 OK: {"ok": true}

Users (Admin Only)

These endpoints require an API key belonging to an admin user.

List Users

GET /api/v1/users Admin

Response 200 OK:

[{"id": 1, "username": "admin", "role": "admin", "created_at": "...", "updated_at": "..."}]

Create User

POST /api/v1/users Admin

Field	Type	Required	Default	Description
`username`	string	Yes	—	Username (unique)
`password`	string	Yes	—	Password (min 6 chars)
`role`	string	No	user	`admin` or `user`

Response 201 Created:

{"id": 3, "username": "newuser", "role": "user"}

Get User

GET /api/v1/users/{id} Admin

Response 200 OK:

{"id": 2, "username": "dev", "role": "user", "created_at": "...", "updated_at": "..."}

Delete User

DELETE /api/v1/users/{id} Admin

Cannot delete yourself.

Response 200 OK: {"ok": true}

Reset User Password

PUT /api/v1/users/{id}/password Admin

Field	Type	Required	Description
`password`	string	Yes	New password (min 6 chars)

Response 200 OK: {"ok": true}

VM Access (Admin Only)

Control which non-admin users can access which VMs. Admins can access all VMs regardless.

List VM Access

GET /api/v1/vms/{name}/access Admin

Response 200 OK:

[{"id": 2, "username": "dev", "role": "user"}]

Grant VM Access

POST /api/v1/vms/{name}/access Admin

Field	Type	Required	Description
`user_id`	int	Yes	User ID to grant access to

Response 200 OK: {"ok": true}

Revoke VM Access

DELETE /api/v1/vms/{name}/access/{user_id} Admin

Response 200 OK: {"ok": true}

SSH Keys

Manage SSH public keys for your account. Keys can be injected into VMs at launch.

List SSH Keys

GET /api/v1/sshkeys API Key

Response 200 OK:

[{"id": 1, "name": "work-laptop", "public_key": "ssh-ed25519 AAAA...", "created_at": "..."}]

Add SSH Key

POST /api/v1/sshkeys API Key

Field	Type	Required	Description
`name`	string	Yes	Display name (unique per user)
`public_key`	string	Yes	SSH public key (OpenSSH format)

Response 201 Created:

{"id": 1, "name": "work-laptop", "public_key": "ssh-ed25519 AAAA...", "created_at": "..."}

Delete SSH Key

DELETE /api/v1/sshkeys/{id} API Key

Response 200 OK: {"ok": true}

Contents

Installation
Provider Configuration
Resource: virtuoso_vm
Resource: virtuoso_ssh_key
Resource: virtuoso_vm_access
Data Source: virtuoso_vm
Data Source: virtuoso_vms
Full Example

Installation

Run this one-liner to download and install the provider (auto-detects your OS and architecture):

curl -sfL -k https://192.168.33.99/terraform/provider/install.sh | sh

Or download manually for a specific platform:

Linux (x86_64) · Linux (ARM64) · macOS (Intel) · macOS (Apple Silicon)

If downloading manually, place the binary at:

~/.terraform.d/plugins/registry.terraform.io/rickjacobo/virtuoso/0.1.0/OS_ARCH/terraform-provider-virtuoso

Then reference it in your Terraform config:

terraform {
  required_providers {
    virtuoso = {
      source = "rickjacobo/virtuoso"
    }
  }
}

Provider Configuration

Configure the provider with your virtuOSo server endpoint and an API key. Create an API key from the Profile page.

provider "virtuoso" {
  endpoint = "https://192.168.33.99"
  api_key  = var.virtuoso_api_key
  insecure = true  # for self-signed TLS certs
}

Attribute	Type	Description
`endpoint`	String	Server URL. Env: `VIRTUOSO_ENDPOINT`
`api_key` sensitive	String	API key (`vmk_...`). Env: `VIRTUOSO_API_KEY`
`insecure`	Bool	Skip TLS verification. Env: `VIRTUOSO_INSECURE`

All attributes can be set via environment variables as an alternative to hardcoding in config files.

Resource: virtuoso_vm

Manages a virtual machine. Most fields are immutable — changing them destroys and recreates the VM.

resource "virtuoso_vm" "web" {
  name      = "web-server"
  size      = "medium"
  os        = "ubuntu-24.04"
  disk_gb   = 40
  ssh_key   = virtuoso_ssh_key.deploy.public_key
  started   = true
  autostart = true
}

Arguments

Attribute	Type	Description
`name` required force new	String	VM name (1-63 chars, alphanumeric/hyphens/underscores/dots)
`os` optional force new	String	OS image: `ubuntu-24.04` (default), `ubuntu-22.04`, `ubuntu-25.10`, `fedora-43`, `amazon-2023`. Ignored when `iso` is set
`iso` optional force new	String	Absolute path to an ISO file on the server. When set, the VM boots from the ISO instead of a cloud image (`os` is ignored, VNC is auto-enabled). Upload ISOs via Settings > Storage; they are stored at `/var/lib/vm-lab/vms/isos/`
`size` optional force new	String	`micro` (1 vCPU/1 GB), `small` (1/2 GB), `medium` (2/4 GB), `large` (2/8 GB), `xlarge` (4/16 GB). Default: `small`
`ssh_key` optional force new	String	SSH public key to inject
`disk_gb` optional	Int	Disk size in GB. Can be increased in-place; cannot be shrunk
`password` optional sensitive force new	String	VM password. Auto-generated if omitted
`vnc` optional force new	Bool	Enable VNC graphics
`desktop` optional force new	Bool	Install desktop environment (implies VNC)
`user_script` optional force new	String	Shell commands to run on first boot via cloud-init
`bridged` optional	Bool	Use bridged networking (VM gets a LAN IP from router DHCP) instead of NAT. Default: `false`. Updateable in-place (stops VM, switches network, restarts automatically)
`autostart` optional	Bool	Start VM automatically on host boot. Default: `false`. Updateable in-place
`protected` optional	Bool	Delete protection. When enabled, the VM cannot be deleted until protection is disabled. Default: `false`. Updateable in-place. Terraform auto-unprotects before destroy
`started` optional	Bool	Whether the VM should be running. Default: `true`. Updateable in-place

Read-Only Attributes

Attribute	Type	Description
`ip`	String	VM IP address
`state`	String	VM state: `running`, `shutoff`, `creating`
`vcpus`	Int	Number of virtual CPUs
`memory_mb`	Int	Memory in MB
`disk_cap_gb`	Float	Disk capacity in GB
`disk_used_gb`	Float	Disk used in GB
`has_vnc`	Bool	Whether VNC is available
`cloud_init`	String	Cloud-init status (`running`, `done`, `error`)
`network`	String	Network identifier: `"default"` for NAT or `"bridge:br0"` for bridged
`os_id`	String	OS identifier from server
`password` sensitive	String	VM password (captured at creation)

Update Behavior

In-place updates (no VM replacement):

autostart — toggles autostart on/off
started — starts or gracefully stops the VM
disk_gb — grows the disk (stops VM, resizes, restarts automatically)
bridged — switches between NAT and bridged networking (stops VM, switches, restarts automatically)
protected — enables or disables delete protection (Terraform auto-unprotects before terraform destroy)

Disk resize requires a VM restart. The provider handles the stop → resize → start sequence automatically. Disks can only be grown, not shrunk.

Import

terraform import virtuoso_vm.web web-server

Import by VM name. Config-only fields (size, os, etc.) will be empty after import — fill them in or use ignore_changes.

Resource: virtuoso_ssh_key

Manages an SSH public key associated with your account. Immutable — any change recreates the key.

resource "virtuoso_ssh_key" "deploy" {
  name       = "deploy-key"
  public_key = file("~/.ssh/id_ed25519.pub")
}

Arguments

Attribute	Type	Description
`name` required force new	String	Display name for the key
`public_key` required force new	String	SSH public key content (ssh-rsa, ssh-ed25519, or ecdsa-sha2-*)

Read-Only Attributes

Attribute	Type	Description
`id`	String	Server-assigned key ID
`created_at`	String	Creation timestamp

Import

terraform import virtuoso_ssh_key.deploy 42

Import by numeric key ID.

Resource: virtuoso_vm_access

Grants a user access to a VM. Admin-only. Immutable — any change recreates the grant.

resource "virtuoso_vm_access" "dev_access" {
  vm_name = virtuoso_vm.web.name
  user_id = 2
}

Arguments

Attribute	Type	Description
`vm_name` required force new	String	Name of the VM
`user_id` required force new	Int	ID of the user to grant access

Read-Only Attributes

Attribute	Type	Description
`id`	String	Synthetic ID: `{vm_name}/{user_id}`

Import

terraform import virtuoso_vm_access.dev_access web-server/2

Data Source: virtuoso_vm

Reads details of an existing VM.

data "virtuoso_vm" "existing" {
  name = "web-server"
}

output "vm_ip" {
  value = data.virtuoso_vm.existing.ip
}

Returns all read-only VM attributes: state, ip, vcpus, memory_mb, disk_cap_gb, disk_used_gb, has_vnc, cloud_init, network, password, os_id, autostart.

Data Source: virtuoso_vms

Lists all VMs you have access to.

data "virtuoso_vms" "all" {}

output "vm_names" {
  value = [for vm in data.virtuoso_vms.all.vms : vm.name]
}

Returns a vms list, each with: name, state, ip, vcpus, memory_mb, autostart, has_vnc, disk_cap_gb, disk_used_gb, cloud_init, network.

Full Example

terraform {
  required_providers {
    virtuoso = {
      source = "rickjacobo/virtuoso"
    }
  }
}

provider "virtuoso" {
  endpoint = "https://192.168.33.99"
  api_key  = var.virtuoso_api_key
  insecure = true
}

variable "virtuoso_api_key" {
  type      = string
  sensitive = true
}

# Upload your SSH key
resource "virtuoso_ssh_key" "deploy" {
  name       = "deploy-key"
  public_key = file("~/.ssh/id_ed25519.pub")
}

# Launch a VM
resource "virtuoso_vm" "web" {
  name      = "web-server"
  size      = "medium"
  os        = "ubuntu-24.04"
  disk_gb   = 40
  ssh_key   = virtuoso_ssh_key.deploy.public_key
  started   = true
  autostart = true

  user_script = <<-EOT
    apt-get update
    apt-get install -y nginx
  EOT
}

# Launch a VM with bridged networking (LAN IP from router DHCP)
resource "virtuoso_vm" "lan" {
  name    = "lan-server"
  size    = "medium"
  os      = "ubuntu-24.04"
  bridged = true
}

# Boot a VM from an ISO (for manual OS installs)
# Upload ISOs via Settings > Storage, then reference the path below
resource "virtuoso_vm" "custom" {
  name = "custom-os"
  size = "large"
  iso  = "/var/lib/vm-lab/vms/isos/my-installer.iso"
}

# Grant another user access
resource "virtuoso_vm_access" "dev" {
  vm_name = virtuoso_vm.web.name
  user_id = 2
}

output "web_ip" {
  value = virtuoso_vm.web.ip
}

output "web_password" {
  value     = virtuoso_vm.web.password
  sensitive = true
}

# Apply
export VIRTUOSO_API_KEY="vmk_your_key_here"
terraform init
terraform plan
terraform apply

Contents

Overview
AI Assistant
External Setup
Key Tools
Security

Overview

virtuOSo includes a built-in Model Context Protocol server so AI assistants can manage VMs through typed JSON tools instead of parsing shell output. The MCP server runs as vm mcp-serve and exposes structured VM lifecycle, discovery, and configuration operations.

AI Assistant

The /ai page provides a built-in chat interface with provider tabs for Claude Code and OpenAI Codex. Authentication is handled from the web UI using each provider's CLI login flow.

Claude Code — signs in with claude auth login
Codex — signs in with codex login --device-auth
Status dots — green means authenticated, red means login required, gray means the CLI is not installed

External Setup

You can connect external MCP clients to the same server over stdio:

claude mcp add virtuoso /path/to/vm mcp-serve
codex mcp add virtuoso -- /path/to/vm mcp-serve

For Codex, you can also configure it in ~/.codex/config.toml:

[mcp_servers.virtuoso]
command = "/path/to/vm"
args = ["mcp-serve"]
env = { VM_DIR = "/var/lib/vm-lab/vms" }

Key Tools

The MCP server exposes 15 tools. Common examples:

list_vms — list VM names, state, IP, vCPUs, and memory
get_vm — fetch detailed VM info including autostart and network
launch_vm — create a new VM with options like size, os, bridged, desktop, and user_script
change_vm_network — switch a shut off VM between libvirt networks or a host bridge
resize_vm_disk — grow a shut off VM's disk
set_vm_protection — enable or disable delete protection

Security

Passwords and SSH keys are never exposed to the AI assistant
Delete protection is enforced by MCP tools
Bulk destructive requests are guarded against in the built-in chat UI
The MCP server is local-only and communicates over stdio plus the local libvirt socket

Your homelab VM manager,simplified.

Everything you need to run VMs

Browser-Based Access

Multi-VM Stacks

Built-In AI Assistant

Terraform Provider

Multi-User Access Control

Encrypted Secrets

Cloud-Init Scripts

NAT & Bridged Networking

Quick Launch

See it in action

Launch any major Linux distribution

Ubuntu

Fedora

Amazon Linux

Custom ISOs

Instance Sizes

Deploy entire environments with Stacks

Automate everything

REST API

Terraform Provider

AI Assistant + MCP

WireGuard VPN

AI-Safe Guardrails

Delete Protection

ISO Boot

Get started

Download & Install

Open the UI

Launch a VM

Your homelab VM manager,
simplified.