​
Deploy Your First VM

This guide walks you through creating a Droplet (virtual machine), connecting to it via SSH, and performing basic management operations.

​
Prerequisites

  • Uncloud backend running (see Quickstart)
  • KubeVirt installed (via Admin Setup)
  • An SSH key pair on your local machine

​
Step 1: Upload Your SSH Key

First, upload your public SSH key so you can access the VM: 
curl -X POST http://localhost:8080/api/v1/ssh-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-laptop",
    "public_key": "'"$(cat ~/.ssh/id_rsa.pub)"'"
  }'
Save the returned id (e.g., sk_abc123).

​
Step 2: Choose an Image and Plan

Browse available images and plans: 
# List OS images
curl http://localhost:8080/api/v1/images

# List instance plans
curl http://localhost:8080/api/v1/plans

​
Step 3: Create the Droplet

curl -X POST http://localhost:8080/api/v1/droplets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-vm",
    "image": "ubuntu-22-04",
    "plan_id": "s-1vcpu-1gb",
    "region": "nyc1",
    "ssh_key_ids": ["sk_abc123"]
  }'
The Droplet starts in provisioning status. After 30-60 seconds, the sync loop updates its status to running and assigns an IP.

​
Step 4: Check Droplet Status

Poll the Droplet until it’s running: 
curl http://localhost:8080/api/v1/droplets/dpl_your_id
Look for: 
{
  "status": "running",
  "public_ip": "10.0.1.15"
}

​
Step 5: Connect via SSH

ssh root@10.0.1.15

​
Managing Your Droplet

​
Reboot

curl -X POST http://localhost:8080/api/v1/droplets/dpl_your_id/actions \
  -H "Content-Type: application/json" \
  -d '{"type": "reboot"}'

​
Power Off

curl -X POST http://localhost:8080/api/v1/droplets/dpl_your_id/actions \
  -H "Content-Type: application/json" \
  -d '{"type": "power_off"}'

​
Power On

curl -X POST http://localhost:8080/api/v1/droplets/dpl_your_id/actions \
  -H "Content-Type: application/json" \
  -d '{"type": "power_on"}'

​
Create a Snapshot

curl -X POST http://localhost:8080/api/v1/droplets/dpl_your_id/snapshots \
  -H "Content-Type: application/json" \
  -d '{"name": "before-upgrade"}'

​
View Metrics

curl http://localhost:8080/api/v1/droplets/dpl_your_id/metrics

​
Resize

curl -X PATCH http://localhost:8080/api/v1/droplets/dpl_your_id \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "s-2vcpu-2gb"}'

​
Delete

curl -X DELETE http://localhost:8080/api/v1/droplets/dpl_your_id

​
Using the Dashboard

You can also create and manage Droplets through the web dashboard:
  1. Navigate to Droplets in the sidebar
  2. Click Create Droplet
  3. Select image, plan, region, and SSH keys
  4. Click Create
The dashboard shows real-time status, metrics, and provides VNC console access.

​
Next Steps