Cloud-Init

Cloud-Init

Cube AI can be deployed on standard Ubuntu cloud images using cloud-init for automated provisioning. This approach uses a pre-built Ubuntu base image and configures the Cube AI stack (Cube Agent, Ollama or vLLM, TLS certificates) at first boot via cloud-init user-data.

Overview

The cloud-init approach provisions a standard Ubuntu Noble (24.04) cloud image with:

• Cube Agent built from source at first boot
• Ollama or vLLM LLM backend
• Self-signed TLS certificates for mTLS
• Systemd services for Cube Agent and the chosen backend
• Default LLM models pulled in the background
• Support for Intel TDX and AMD SEV-SNP confidential VMs

Cloud-Init vs Buildroot

Prerequisites

Before running the cloud-init deployment, ensure you have:

• A Linux host machine with KVM support
• At least 35GB free disk space
• QEMU installed (qemu-system-x86_64)
• cloud-image-utils package (provides cloud-localds)
• wget for downloading the base image
• OVMF firmware (/usr/share/OVMF/OVMF_CODE.fd and OVMF_VARS.fd)

For AMD SEV-SNP deployments, also install genisoimage — used to create the seed ISO bundling the custom kernel.

Install dependencies on Ubuntu/Debian:

sudo apt-get install qemu-system-x86 cloud-image-utils wget ovmf

# For SNP only
sudo apt-get install genisoimage

Configuration Files

The hal/ubuntu/ directory contains separate cloud-init files for each CVM mode and backend:

The qemu.sh script automatically selects the Ollama variants (user-data-{mode}.yaml) based on detected or forced CVM mode. To use vLLM, pass the corresponding user-data-vllm-{mode}.yaml file manually or edit qemu.sh to point to the desired file.

Steps

1. Clone the Cube Repository

git clone https://github.com/ultravioletrs/cube.git
cd cube/hal/ubuntu

2. Launch the VM

The qemu.sh script automates the entire process — downloading the Ubuntu base image, creating the seed image, and launching QEMU.

Auto-detect CVM mode

sudo ./qemu.sh start

This detects available CVM support on the host (TDX or SNP) and launches with the appropriate configuration.

Force a specific mode

sudo ./qemu.sh start_tdx       # Intel TDX
sudo ./qemu.sh start_regular   # Regular KVM (no CVM)

AMD SEV-SNP (two steps required)

SNP requires a two-step process because the custom kernel must be installed before booting with SNP:

# Step 1: Boot in regular KVM mode to install the custom kernel via cloud-init
sudo ./qemu.sh prepare_snp

# Step 2: Once prepare_snp completes, boot the prepared image with SNP
sudo ./qemu.sh start_snp

See AMD SEV-SNP below for details on the custom kernel requirement.

Environment variables

ENABLE_CVM=tdx sudo ./qemu.sh start      # Force TDX
ENABLE_CVM=none sudo ./qemu.sh start     # Disable CVM
RAM=32768M CPU=16 sudo ./qemu.sh start   # Customize resources

3. First Boot Provisioning

On first boot, cloud-init automatically:

1. Creates the ultraviolet user with sudo access
2. Creates the ollama or vllm system user (depending on backend)
3. Installs packages: curl, git, build-essential
4. Installs Go from the official source (version matching go.mod)
5. Generates TLS certificates (CA, server, and client for mTLS)
6. Installs the chosen backend (Ollama or vLLM)
7. Clones the Cube repository and builds the agent from source
8. Starts backend and Cube Agent systemd services
9. Pulls default LLM models in the background (Ollama only)

4. Access the VM

Once provisioning is complete, connect via SSH:

ssh -p 6190 ultraviolet@localhost

Default credentials:

• Username: ultraviolet
• Password: password

5. Verify Services

systemctl status cube-agent.service
systemctl status ollama.service   # or vllm.service

CVM Support

Intel TDX

The script auto-detects Intel TDX support on the host. TDX mode uses user-data-tdx.yaml, which:

• Installs the tdx_guest kernel module
• Configures the tdx_guest module to load at boot
• Sets AGENT_OS_TYPE=tdx

Ubuntu 24.04 has CONFIG_INTEL_TDX_GUEST=y built into the standard kernel — no custom kernel is needed.

AMD SEV-SNP

SNP support requires Coconut SVSM on the host, which in turn requires a custom kernel inside the guest VM. The standard Ubuntu 24.04 kernel does not support Coconut SVSM.

Custom Kernel Requirement

The guest kernel must be custom-built with the following configuration options:

• CONFIG_AMD_MEM_ENCRYPT=y — AMD memory encryption support
• CONFIG_SEV_GUEST=y — SEV guest driver
• CONFIG_TCG_PLATFORM=y — vTPM support
• Coconut SVSM guest support patches applied

The kernel must be packaged as .deb files and placed in a debs/ directory next to qemu.sh:

hal/ubuntu/
  qemu.sh
  user-data-snp.yaml
  debs/
    linux-image-*.deb
    linux-headers-*.deb

Two-Step Boot Process

Step 1 — prepare_snp: Boots the Ubuntu image in regular KVM mode (no SNP flags). Cloud-init mounts the seed ISO, installs the .deb kernel packages, and runs update-grub. The seed ISO is created using genisoimage and includes both the user-data and the debs/ directory.

Step 2 — start_snp: Boots the prepared image using IGVM and Coconut SVSM QEMU. The guest boots with the custom kernel installed in Step 1.

Host Requirements for SNP

• AMD EPYC CPU with SEV-SNP support (Milan or newer)
• SEV-SNP enabled in BIOS
• Host kernel with SEV-SNP/SVSM support
• /dev/sev device available
• Coconut SVSM QEMU binary
• IGVM file (default: /etc/cocos/coconut-qemu.igvm, or set IGVM env var)
• genisoimage installed
• Custom kernel .deb files in debs/

Configuration

Cube Agent Environment

The agent is configured via /etc/cube/agent.env:

UV_CUBE_AGENT_LOG_LEVEL=info
UV_CUBE_AGENT_HOST=0.0.0.0
UV_CUBE_AGENT_PORT=7001
UV_CUBE_AGENT_INSTANCE_ID=cube-agent-01
UV_CUBE_AGENT_TARGET_URL=http://localhost:11434  # 11434 for Ollama, 8000 for vLLM
UV_CUBE_AGENT_SERVER_CERT=/etc/cube/certs/server.crt
UV_CUBE_AGENT_SERVER_KEY=/etc/cube/certs/server.key
UV_CUBE_AGENT_SERVER_CA_CERTS=/etc/cube/certs/ca.crt
UV_CUBE_AGENT_CA_URL=https://prism.ultraviolet.rs/am-certs

The cube agent is backend-agnostic — it proxies all requests to UV_CUBE_AGENT_TARGET_URL. Set this to http://localhost:11434 for Ollama or http://localhost:8000 for vLLM.

To modify configuration, edit /etc/cube/agent.env inside the VM and restart the service:

sudo systemctl restart cube-agent.service

:::warning Security The example above uses plain_text_passwd: password for local development and testing only. Always use a strong password or SSH key-based access before exposing a VM to any network or using it in staging/production. :::

TLS Certificates

Cloud-init generates self-signed certificates at first boot:

Key files are set to 600 permissions, certificates to 644.

For production deployments, replace these with certificates from a trusted CA or configure UV_CUBE_AGENT_CA_URL to fetch certificates at runtime from the Certs Service.

VM Resources

RAM=32768M CPU=16 sudo ./qemu.sh start

Port Forwarding

Cloud Deployment (GCP / Azure)

For deploying on cloud providers, use the configs in hal/ubuntu/cloud/ together with the cocos-infra Terraform templates. Cloud providers handle confidential computing at the hypervisor level — no custom kernel, IGVM, or module loading is needed.

See cloud/README.md in the cube repository for deployment instructions.

Next Steps

• Manage CVMs - Start, monitor, and manage confidential VMs
• Upload Private Models - Add custom models to your CVM
• Test with Chat UI - Interact with models through the web interface