Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kombify.io/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Access Proxmox web UI

Navigate to https://your-proxmox:8006
2

Create user for kombify

Datacenter → Permissions → Users → Add
  • User name: kombify@pve
  • Realm: Proxmox VE authentication server
3

Assign permissions

Datacenter → Permissions → Add → User Permission
  • Path: /
  • User: kombify@pve
  • Role: Administrator (or custom role)
4

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

1

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
2

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...
3

Deploy

kombify apply
kombify will:
  1. Clone the template
  2. Configure cloud-init
  3. Start the VM
  4. 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:
  1. Create the VM
  2. Install Docker
  3. 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 https://api.kombify.io/v1/orchestrator/vms/app-server-1/metrics

​
Troubleshooting

Verify your API token:
curl -k -H "Authorization: PVEAPIToken=kombify@pve!kombify-token=YOUR-SECRET" \
  https://your-proxmox:8006/api2/json/version
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
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

Auth0 integration

Set up SSO with Auth0

Architecture

Understand kombify architecture

Quick start

Get started with kombify