Create your first VM with VMgenie

Six short steps and you have a live virtual server, brought up through the VMgenie panel API itself.

The VMgenie control panel is the single API surface for everything VMgenie manages — a hosted trial panel lives at https://your-company.vmgen.ie and a self-hosted install uses your own panel domain. Every command on this page is a real curl against that panel — no host shell, no SSH, no helper scripts.

1. Set the panel API key

VMgenie authenticates every panel call with a bearer token. Create a key under Settings › API access and export it before you run anything:

export VMGENIE_API_KEY=<your API key from Settings › API access>
PANEL=https://your-company.vmgen.ie   # self-hosted: use your own panel domain
AUTH=(-H "Authorization: Bearer $VMGENIE_API_KEY")

Create the key in the panel under Settings › API access and keep it out of your shell history; the panel answers 401 for a missing or revoked key.

2. Confirm your session

Before you create anything, verify the panel accepts your key:

curl -sS "${AUTH[@]}" "$PANEL/api/v1/auth/session"
# expect: {"data":{"authenticated":true,...}}

If authenticated is not true, create a new key under Settings › API access and run the check again.

3. Pick a plan and an OS template

List the plans and templates the panel offers so you can copy the names exactly:

curl -sS "${AUTH[@]}" "$PANEL/api/v1/plans"      | jq '.data[] | {name, vcpu, ram_mb, disk_gb}'
curl -sS "${AUTH[@]}" "$PANEL/api/v1/templates"  | jq '.data[] | {name, ostype}'

Pick one of each — for example plan=standard and template=ubuntu-24.04.

4. Create the first VM

Create the VM through VMgenie's own POST /api/v1/vms endpoint. The panel returns a task id; the actual VM is provisioned asynchronously.

curl -sS "${AUTH[@]}" -X POST "$PANEL/api/v1/vms" \
    --data-urlencode "username=demo" \
    --data-urlencode "plan=standard" \
    --data-urlencode "server=" \
    --data-urlencode "template=ubuntu-24.04" \
    --data-urlencode "password=$(openssl rand -base64 24)"
# expect: 202 {data:{task:{id,...},vm:{name:"demo",...}}}

Save the task id — the next step polls it.

5. Wait for the provisioning task

Most panel writes return 202 with a task id. Poll it until it finishes:

task_wait() {  # $1 = task id
  for _ in $(seq 1 120); do
    s=$(curl -sS "${AUTH[@]}" "$PANEL/api/v1/tasks/$1" | jq -r '.data.task.status')
    case "$s" in Complete) return 0 ;; Failed) return 1 ;; esac
    sleep 5
  done; return 2
}
task_wait "<task-id-from-step-4>"

If the task ends in Failed, pull the log: curl -sS "${AUTH[@]}" "$PANEL/api/v1/tasks/<id>/log".

6. Verify from the outside

Don't rely only on the panel's status field — the panel has shown running for a VM that was in fact unreachable. Confirm the VM responds on its own:

curl -sS "${AUTH[@]}" "$PANEL/api/v1/vms/demo" | jq '.data.vm | {name, ip, status}'
ssh demo@<ip-from-the-response> 'uname -a'

The VM is yours to configure over its own SSH — that is the VM, not the host it runs on.

Need a panel instance first? See Get Started for launching a hosted panel or self-hosting VMgenie on your own hardware.