awkto/makevms-api repository overview

⁠MakeVMs API

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

Uses the Proxmox REST API (via proxmoxer) for all VM operations — no SSH to Proxmox required for core functionality.

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-api \
  -p 8000:8000 \
  -v proxmox-data:/data \
  -e AUTH_ENABLED=true \
  awkto/makevms-api:latest

Or with docker-compose:

services:
  makevms-api:
    image: awkto/makevms-api:latest
    ports:
      - "8000:8000"
    volumes:
      - proxmox-data:/data
    environment:
      - AUTH_ENABLED=true
    restart: unless-stopped

volumes:
  proxmox-data:

Access at http://localhost:8000⁠

⁠First-time setup

When AUTH_ENABLED=true (default), the first visit prompts you to create an admin account. All subsequent users are created by the admin.

⁠Data volume

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

⁠Environment variables

⁠Zero-touch deploy

For scripted / orchestrated deploys (Ansible, deploy scripts), the app can come up fully configured with no UI interaction:

docker run -d \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD='hunter2' \
  -e API_TOKEN='your-long-random-string' \
  -v makevms_data:/data \
  -p 8000:8000 \
  awkto/makevms-api:latest

# Use the token directly — no /api/auth/login round-trip needed:
curl -H "Authorization: Bearer your-long-random-string" http://localhost:8000/api/vms

If API_TOKEN is omitted, scrape the generated one from logs:

docker logs <container> 2>&1 | grep '^\[FIRST_RUN\] API_TOKEN=' | head -1 | cut -d= -f2

⁠Connect to Proxmox

MakeVMs API connects to Proxmox using an API token for all VM management operations (create, start, stop, destroy, status polling).

A small number of operations still use SSH as a workaround for Proxmox API limitations (see below).

⁠1. Create a Proxmox API token

On your Proxmox host:

pveum user token add root@pam makevms-api --privsep 0 --comment "makevms-api"

Or for a non-root user (must have Administrator role):

pveum user token add youruser@pam makevms-api --privsep 0 --comment "makevms-api"

Save the token value — it's only shown once.

⁠2. Generate an SSH key (for snippet upload)

Go to Settings → Proxmox Connection and click Generate Key. Add the displayed public key to the Proxmox user's authorized_keys:

# On the Proxmox host, for the user that matches your "Proxmox User" setting
echo "ssh-ed25519 AAAA... proxmox-web" >> ~/.ssh/authorized_keys

The user needs passwordless sudo on the Proxmox host.

⁠3. Configure settings

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

⁠SSH usage

Most operations use the Proxmox REST API. SSH is only used for:

VM console and Ansible SSH to the VMs themselves, not to Proxmox.

⁠Creating VMs

⁠Distros & Images

Cloud images must be pre-staged on the Proxmox host at /var/lib/vz/. On first use of a distro, MakeVMs API automatically creates a template VM from the image.

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.

⁠DHCP & DNS Integration

MakeVMs API can automatically create DHCP reservations and DNS records when creating VMs.

When a VM is deleted, its DHCP reservation and DNS record are automatically cleaned up.

⁠Console View

The browser terminal connects to your VM over SSH via a WebSocket bridge in the MakeVMs API 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.