awkto/makevms repository overview

⁠MakeVMs

Web UI for creating and managing Proxmox VMs with cloud-init, automatic DHCP reservations, and DNS records.

VMs are created from cloud images (not ISO installers) — fully configured in ~3 minutes with SSH keys, passwordless sudo, and a fully updated system.

⁠Deploy

docker run -d \
  --name makevms \
  -p 8000:8000 \
  -v proxmox-data:/data \
  awkto/makevms:latest

Or with docker-compose:

services:
  makevms:
    image: awkto/makevms:latest
    ports:
      - "8000:8000"
    volumes:
      - proxmox-data:/data
    restart: unless-stopped

volumes:
  proxmox-data:

Access at http://localhost:8000⁠

⁠Data volume

Everything persistent lives in /data (the Docker volume):

⁠Connect to Proxmox

MakeVMs SSHes into your Proxmox host to run qm and pvesh commands. It needs a non-root user with passwordless sudo.

1. Generate a keypair in the app

Go to Settings → Proxmox Connection and click Generate Key. The public key is displayed in the Public Key field below.

2. Add the public key to Proxmox

ssh-copy-id -i /path/to/id_proxmox_web.pub youruser@proxmox-host
# or paste the key manually into ~/.ssh/authorized_keys on the Proxmox host

3. Configure settings

Find your storage names with pvesm status on the Proxmox host.

⁠Creating VMs

⁠Distros & Images

The default distro list is seeded to /data/distros.csv on first startup. To add a custom image, append a row:

slug,label,url,filename,family,guest_agent_pkg
my-ubuntu,My Custom Ubuntu,https://example.com/custom.img,custom.img,debian,qemu-guest-agent

Fields:

• family: debian, rhel, or suse — controls sudo group and package manager
• guest_agent_pkg: package name for qemu-guest-agent, or empty to skip
• filename: local filename for the downloaded image; empty = auto-discovered from URL

⁠SSH Keys in VMs

New VMs receive SSH keys from two sources:

1. GitHub — public keys for the configured GitHub username (GITHUB_SSH_USER)
2. Console access key — the app's own /data/id_vm_access.pub key, if Console View Pubkey is enabled in Settings → VM User & SSH

The console access key enables password-free browser terminal access. It is auto-generated on startup.

⁠Creating a VM

From the Dashboard, click New VM. Options:

VM creation runs in the background (~3 minutes). Watch progress in the job log.

⁠Console View

The browser terminal connects to your VM over SSH via a WebSocket bridge in the MakeVMs backend.

How it works:

1. Browser opens a WebSocket to /api/vms/{id}/console
2. Backend establishes an SSH session to the VM's IP using the credentials from Settings
3. Input/output is proxied between the WebSocket and the SSH process

Authentication: if Console View Pubkey is enabled, the app uses /data/id_vm_access (key auth, no password prompt). Otherwise it falls back to the VM password from Settings.

The console key must be present in the VM's authorized_keys. This happens automatically for VMs created with the toggle enabled — it is injected via cloud-init at creation time. Existing VMs need the key added manually:

cat /data/id_vm_access.pub | ssh user@vm-ip "cat >> ~/.ssh/authorized_keys"