virtuOSo — Hybrid Infrastructure Platform for Homelabs & Cloud

Everything you need to run VMs

A complete VM management platform spanning on-prem and cloud. Run it on a single server or scale to AWS.

Hybrid Cloud

Manage on-prem KVM and AWS EC2 instances from the same dashboard. Launch cloud VMs alongside your homelab with unified controls.

Apps Marketplace

One-click deployment of Kubernetes clusters, Docker hosts, Gitea, databases, and monitoring stacks. Scale K8s workers up and down from the UI.

Quick Launch

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

Multi-VM Stacks

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

Terraform Provider

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

Browser-Based Access

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

Custom Images

Boot from cloud images, uploaded ISOs, or QCOW2 disk images. Full support for Linux and Windows guests with automatic device model selection.

VPN & Remote Access

Built-in Tailscale integration for secure remote access to your VMs from anywhere. Connect your server to a tailnet with one click.

AI Assistant & MCP

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

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 distribution

Cloud images download automatically. Upload custom ISOs or QCOW2 disk images for any OS, including Windows.

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 Images

ISO QCOW2

ISOs & QCOW2 · Linux & Windows

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
`2xlarge`	4	32 GB	200 GB
`4xlarge`	8	64 GB	200 GB
`8xlarge`	16	128 GB	500 GB

Deploy complete environments with Stacks

Define multi-VM environments as simple YAML templates. Launch, update, and tear them down as a single unit.

One definition. Multiple VMs. Fully wired together at deploy time.

Launch environments in the right order automatically Dependencies start first, and virtuOSo waits for required services to come online before continuing.
Wire services together without manual setup Use ${vm.name.ip} and ${secret.KEY} to inject runtime values before dependent VMs boot.
Inject secrets safely at deploy time Keep sensitive values out of your YAML and let virtuOSo handle secure substitution.
Tear everything down as a single unit Create, redeploy, and destroy complete environments without managing each VM separately.

stack.yaml

vms:
  - name: database
    os: ubuntu-24.04
    size: medium

  - name: web
    os: ubuntu-24.04
    size: small
    depends_on: [database]
    user-script: |
      # Injected before the VM boots
      echo "DB_HOST=${vm.database.ip}" >> /etc/environment

What happens when you deploy it

database starts first
virtuOSo waits for it to get an IP address
web starts next with DB_HOST already configured

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 25+ 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

Tailscale VPN

Built-in Tailscale integration for secure remote access to your VMs from anywhere. Connect your server to a tailnet and route VM subnets automatically.

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.

Cloud-Init & Secrets

Run custom scripts on first boot. Inject encrypted secrets into VMs at deploy time with AES-256-GCM encryption at rest.

Get started

virtuOSo ships as a bootable ISO for on-prem servers. Install on dedicated hardware and manage VMs from your browser in minutes. Optionally connect AWS for hybrid cloud.

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.

AWS Provider

Launch EC2 instances alongside on-prem KVM VMs. Configure IAM, VPCs, firewall rules, and Tailscale for hybrid cloud.

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 hybrid infrastructure platform for homelabs and cloud. It manages VMs across on-prem KVM/libvirt and AWS EC2 from a single dashboard, with a built-in apps marketplace, REST API, Terraform provider, and AI assistant.

Key features:

Hybrid cloud: manage on-prem KVM and AWS EC2 from one dashboard
Launch from cloud images, custom ISOs, or QCOW2 disk images (Linux & Windows)
Apps marketplace: Kubernetes, Docker, Gitea, databases, monitoring
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
Tailscale VPN integration for secure remote access
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, Amazon Linux 2023, Custom ISO, or Custom QCOW2
Size — micro (1 vCPU / 1 GB), small (1 / 2 GB), medium (2 / 4 GB), large (2 / 8 GB), xlarge (4 / 16 GB), 2xlarge (4 / 32 GB), 4xlarge (8 / 64 GB), or 8xlarge (16 / 128 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.

Booting from QCOW2

Select "Custom QCOW2" to boot from an uploaded QCOW2 disk image. Upload QCOW2 files via Settings (Storage tab). Choose a Guest OS type (Linux or Windows) — Windows uses SATA/e1000e devices and TPM 2.0, while Linux uses virtio for better performance. Each VM gets a copy-on-write overlay, leaving the base image untouched.

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
Tailscale — if configured by the admin, VMs are accessible over your Tailscale network

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 ISOs and QCOW2 disk images
Tailscale — connect your server to a Tailscale network for remote VM access
AWS — configure AWS credentials and default region for hybrid cloud

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
Setup
IAM Policy
VPC
Launching Instances
Tailscale on AWS
Kubernetes on AWS

Overview

The AWS provider lets you launch and manage EC2 instances from the same dashboard as your on-prem KVM VMs. All apps (Compute, Docker, Kubernetes, databases, monitoring) work on both providers. Configure AWS credentials in Settings, then select AWS as the provider when creating apps.

Setup

Create an IAM User or Role with the policy below
Go to Settings > AWS and enter your Access Key ID, Secret Access Key, and default region
Launch any app and select AWS as the provider

Changes take effect immediately — no restart required.

IAM Policy

VirtuOSo needs EC2, SSM, and IAM permissions. Create an IAM user with this policy:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VirtuOSoEC2",
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances", "ec2:TerminateInstances",
        "ec2:DescribeInstances", "ec2:DescribeVpcs",
        "ec2:CreateVpc", "ec2:ModifyVpcAttribute",
        "ec2:DescribeSubnets", "ec2:CreateSubnet",
        "ec2:ModifySubnetAttribute",
        "ec2:DescribeSecurityGroups",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:CreateInternetGateway",
        "ec2:AttachInternetGateway",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeRouteTables", "ec2:CreateRoute",
        "ec2:DescribeAvailabilityZones",
        "ec2:CreateTags", "ec2:DescribeImages"
      ],
      "Resource": "*"
    },
    {
      "Sid": "VirtuOSoSSM",
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter", "ssm:SendCommand",
        "ssm:GetCommandInvocation"
      ],
      "Resource": "*"
    },
    {
      "Sid": "VirtuOSoIAM",
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole", "iam:TagRole",
        "iam:AttachRolePolicy",
        "iam:CreateInstanceProfile",
        "iam:TagInstanceProfile",
        "iam:AddRoleToInstanceProfile",
        "iam:GetInstanceProfile", "iam:PassRole"
      ],
      "Resource": "*"
    }
  ]
}

VPC

VirtuOSo automatically creates a VPC when you select a region with no VPCs. The auto-created VPC includes:

CIDR 10.0.0.0/16 with DNS hostnames enabled
2 public subnets across 2 availability zones
Internet gateway with default route
Auto-assign public IPs on both subnets

You can also use an existing VPC — just select it from the dropdown when creating an app.

Cost note: VPCs, subnets, internet gateways, and route tables have no hourly charges. You only pay for EC2 instances.

Launching Instances

When AWS is configured, app create forms show a Provider dropdown. Select AWS to configure:

Region — AWS region (defaults to your configured region)
VPC & Subnet — dynamically loaded from your AWS account
Instance Type — EC2 instance types (t3.micro through t3.2xlarge)
Firewall Rules — per-instance security group rules with My IP auto-detection, custom CIDR, or public access
User Data — optional shell commands to run on first boot

SSH port 22 is included by default. Security groups are created per-instance and per-user for traffic isolation.

Tailscale on AWS

When Tailscale is configured in Settings, AWS instances automatically join your tailnet with Tailscale SSH enabled. This lets you SSH into cloud instances without managing SSH keys or opening additional ports.

Instances register with hostname <user>-<app>-<instance>
SSH via Tailscale IP works without public internet exposure
You can use private subnets (no internet gateway) with Tailscale

Kubernetes on AWS

The Kubernetes app works identically on AWS. Select AWS as the provider when creating a cluster. Worker nodes can be scaled up/down from the cluster detail page — each worker is a separate EC2 instance in the same VPC.

Workers join automatically via k3s and are drained before removal
Kubeconfig available from the cluster detail page
With Tailscale, access the K8s API via tailnet without opening port 6443 publicly

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

Run complete environments on-prem or in the cloud

One platform. Multiple control surfaces.

Everything you need to run VMs

Hybrid Cloud

Apps Marketplace

Quick Launch

Multi-VM Stacks

Terraform Provider

Browser-Based Access

Custom Images

VPN & Remote Access

AI Assistant & MCP

See it in action

Launch any major distribution

Ubuntu

Fedora

Amazon Linux

Custom Images

Instance Sizes

Deploy complete environments with Stacks

What happens when you deploy it

Automate everything

REST API

Terraform Provider

AI Assistant + MCP

Tailscale VPN

AI-Safe Guardrails

Delete Protection

Cloud-Init & Secrets

Get started

Download & Install

Open the UI

Launch a VM