Proxmox integration

Use kombify to provision and manage Proxmox Virtual Environment (VE) virtual machines and containers.

Overview

kombify integrates with Proxmox VE to:

Provision VMs from templates
Create LXC containers
Manage networking and storage
Deploy services to VMs automatically

Prerequisites

Proxmox VE

Proxmox VE 7.0+ installed

API access

API token with appropriate permissions

Setup

Step 1: Create API token

Access Proxmox web UI

Navigate to https://your-proxmox:8006

Create user for kombify

Datacenter → Permissions → Users → Add

User name: kombify@pve
Realm: Proxmox VE authentication server

Assign permissions

Datacenter → Permissions → Add → User Permission

Path: /
User: kombify@pve
Role: Administrator (or custom role)

Generate API token

Datacenter → Permissions → API Tokens → Add

User: kombify@pve
Token ID: kombify-token
Privilege Separation: Unchecked

Save the token ID and secret.

Step 2: Configure kombify

Add Proxmox credentials to your kombination.yaml:

kombination.yaml

providers:
  proxmox:
    endpoint: https://your-proxmox:8006/api2/json
    token_id: kombify@pve!kombify-token
    token_secret: your-secret-token
    insecure: false  # Set to true for self-signed certs

nodes:
  - name: proxmox-1
    type: proxmox
    role: hypervisor
    connection:
      host: your-proxmox
      node: pve  # Proxmox node name

Provision VMs

Create VM from template

Prepare template

Create a VM template in Proxmox with cloud-init support:

# Download Ubuntu cloud image
wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img

# Create VM
qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

# Import disk
qm importdisk 9000 jammy-server-cloudimg-amd64.img local-lvm

# Configure VM
qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0
qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0
qm set 9000 --serial0 socket --vga serial0

# Convert to template
qm template 9000

Define VM in kombination.yaml

vms:
  - name: app-server-1
    provider: proxmox
    template: ubuntu-template
    specs:
      cores: 4
      memory: 8192
      disk: 50G
    network:
      bridge: vmbr0
      ip: 192.168.1.100/24
      gateway: 192.168.1.1
    cloud_init:
      user: ubuntu
      ssh_keys:
        - ssh-rsa AAAA...

Deploy

kombify apply

kombify will:

Clone the template
Configure cloud-init
Start the VM
Install the kombify agent

Create LXC container

kombination.yaml

containers:
  - name: web-server-1
    provider: proxmox
    template: ubuntu-22.04-standard
    specs:
      cores: 2
      memory: 4096
      disk: 20G
    network:
      bridge: vmbr0
      ip: 192.168.1.101/24
      gateway: 192.168.1.1

Manage networking

Create VLAN

kombination.yaml

networks:
  - name: services-vlan
    provider: proxmox
    type: vlan
    vlan_id: 100
    bridge: vmbr0
    subnet: 10.0.100.0/24
    gateway: 10.0.100.1

vms:
  - name: service-vm
    network:
      vlan: services-vlan
      ip: 10.0.100.10/24

Configure firewall

kombination.yaml

firewall:
  - vm: app-server-1
    rules:
      - action: accept
        type: in
        proto: tcp
        dport: 80,443
        source: 0.0.0.0/0
      
      - action: accept
        type: in
        proto: tcp
        dport: 22
        source: 192.168.1.0/24

Storage management

Add storage pool

kombination.yaml

storage:
  - name: vm-storage
    provider: proxmox
    type: lvm-thin
    pool: data
    content: images,rootdir

Attach additional disk

kombination.yaml

vms:
  - name: database-server
    disks:
      - size: 100G
        storage: vm-storage
        mount: /var/lib/postgresql

Deploy services to VMs

Combine Proxmox provisioning with service deployment:

kombination.yaml

# Provision VM
vms:
  - name: docker-host
    provider: proxmox
    template: ubuntu-template
    specs:
      cores: 8
      memory: 16384
      disk: 100G

# Deploy services to the VM
services:
  - name: traefik
    node: docker-host
    type: docker
    
  - name: immich
    node: docker-host
    type: docker

kombify will:

Create the VM
Install Docker
Deploy the services

High availability

Create HA cluster

kombination.yaml

nodes:
  - name: proxmox-1
    type: proxmox
    role: hypervisor
    cluster: homelab-cluster
    
  - name: proxmox-2
    type: proxmox
    role: hypervisor
    cluster: homelab-cluster
    
  - name: proxmox-3
    type: proxmox
    role: hypervisor
    cluster: homelab-cluster

vms:
  - name: critical-service
    ha:
      enabled: true
      group: homelab-cluster
      priority: 100

Backup and snapshots

Create snapshots

kombination.yaml

vms:
  - name: app-server
    snapshots:
      - name: before-update
        description: Snapshot before system update
        include_ram: true

Schedule backups

kombination.yaml

backup:
  schedule: "0 2 * * *"  # Daily at 2 AM
  retention: 7  # Keep 7 days
  vms:
    - app-server-1
    - database-server
  storage: backup-storage

Monitoring

VM metrics

kombify automatically collects:

CPU usage
Memory usage
Disk I/O
Network traffic

Access in the kombify dashboard or via API:

curl http://localhost:5260/api/v1/vms/app-server-1/metrics

Troubleshooting

API authentication failed

Verify your API token:

curl -k -H "Authorization: PVEAPIToken=kombify@pve!kombify-token=YOUR-SECRET" \
  https://your-proxmox:8006/api2/json/version

VM creation fails

Check Proxmox logs:

# On Proxmox host
tail -f /var/log/pve/tasks/active

Common issues:

Insufficient storage
Template not found
Network bridge doesn’t exist

Cloud-init not working

Verify cloud-init configuration:

# On the VM
cloud-init status
cloud-init analyze show

Advanced: OpenTofu integration

kombify generates OpenTofu code for Proxmox:

# Generated by kombify
resource "proxmox_vm_qemu" "app_server_1" {
  name        = "app-server-1"
  target_node = "pve"
  clone       = "ubuntu-template"
  
  cores   = 4
  memory  = 8192
  
  disk {
    size    = "50G"
    storage = "local-lvm"
  }
  
  network {
    model  = "virtio"
    bridge = "vmbr0"
  }
}

Next steps

Coolify integration

Deploy kombify with Coolify

Zitadel integration

Set up SSO with Zitadel

Architecture

Understand kombify architecture

Quick start

Get started with kombify

Getting Started

Self-Hosting

Integrations

Authentication

AI-Assisted Setup

Help

Proxmox integration

Overview

Prerequisites

Proxmox VE

API access

Setup

Step 1: Create API token

Step 2: Configure kombify

Provision VMs

Create VM from template

Create LXC container

Manage networking

Create VLAN

Configure firewall

Storage management

Add storage pool

Attach additional disk

Deploy services to VMs

High availability

Create HA cluster

Backup and snapshots

Create snapshots

Schedule backups

Monitoring

VM metrics

Troubleshooting

Advanced: OpenTofu integration

Next steps

Coolify integration

Zitadel integration

Architecture

Quick start

Getting Started

Self-Hosting

Integrations

Authentication

AI-Assisted Setup

Help

​Overview

​Prerequisites

Proxmox VE

API access

​Setup

​Step 1: Create API token

​Step 2: Configure kombify

​Provision VMs

​Create VM from template

​Create LXC container

​Manage networking

​Create VLAN

​Configure firewall

​Storage management

​Add storage pool

​Attach additional disk

​Deploy services to VMs

​High availability

​Create HA cluster

​Backup and snapshots

​Create snapshots

​Schedule backups

​Monitoring

​VM metrics

​Troubleshooting

​Advanced: OpenTofu integration

​Next steps

Coolify integration

Zitadel integration

Architecture

Quick start

Overview

Prerequisites

Setup

Step 1: Create API token

Step 2: Configure kombify

Provision VMs

Create VM from template

Create LXC container

Manage networking

Create VLAN

Configure firewall

Storage management

Add storage pool

Attach additional disk

Deploy services to VMs

High availability

Create HA cluster

Backup and snapshots

Create snapshots

Schedule backups

Monitoring

VM metrics

Troubleshooting

Advanced: OpenTofu integration

Next steps