VM management

All VM commands go through the server API.

Browse available OS templates

swarm vm templates

Filter by zone:

swarm vm templates --zone fi-hel1

If no --zone flag is given and a default zone is configured, templates are filtered to that zone. Use --all to show all zones regardless of the default.

List available server plans

See the exact plan codes accepted by vm create --plan (the provider rejects unknown codes with PLAN_INVALID):

swarm vm plans

Output:

NAME        CPU  MEMORY (MB)  DISK (GB)  TIER
1xCPU-1GB   1    1024         25         maxiops
8xCPU-16GB  8    16384        50         maxiops

List available zones

See the zone codes accepted by vm create --zone (and swarm config set zone <value>):

swarm vm zones

Output:

fi-hel1
fi-hel2
nl-ams1

Private networks

VMs can join an UpCloud private network for east-west traffic. Configure the network server-side (created per zone on demand when create_if_missing):

"private_network": {
  "name": "swarm-net",
  "create_if_missing": true,
  "ip_network": "10.100.0.0/24"
}

Multiple networks use the list form (private_networks, which takes precedence); server_private_ip marks a network the swarm-server host itself is on. List the account’s networks and pick one per VM:

swarm vm networks [--zone fi-hel2]
swarm vm create --name my-server --network prod-net ...

vm info and vm list show the VM’s private IP. Networks are zone-scoped (a swarm-net in fi-hel2 is separate from one in fi-hel1); swarm never auto-deletes them.

Trusted pool

The private network gives VMs reachability to each other with no isolation — treat VMs on it as a trusted pool. East-west isolation is not implemented.

Create a VM

swarm vm create --name my-server [--zone fi-hel1] [--plan 1xCPU-1GB] [--template UUID] [--disk-size 100]

• --name is always required. It is the console/display name and may contain spaces or mixed case. The machine hostname is derived from it (lowercase; Swarm Node 1 → swarm-node-1).
• --hostname sets an explicit hostname/FQDN (must be a valid lowercase hostname; invalid values are rejected before the provider call).
• --disk-size <GB> overrides the boot disk (10–2048 GB). Unset, the disk defaults to the plan’s storage size — useful when container workloads (Docker images, build caches) outgrow the plan default.
• --network <name> joins a private network.
• Remaining flags fall back to saved config defaults. If a flag is omitted and no default is set, the CLI tells you how to fix it:

Error: --zone is required (or set default: swarm config set zone <value>)

The server provisions the VM, stores the SSH key, and registers it in the server-side registry.

List VMs

swarm vm list

Output:

ID                                    NAME        IP            PROVIDER  STATUS   BOOTSTRAPPED
00a1b2c3-d4e5-6f78-9a0b-c1d2e3f4a5b6  my-server   95.216.1.100  upcloud   running  true

The server refreshes live status from the cloud provider before returning results.

Inspect a VM

swarm vm info <name-or-id>

Accepts either the VM name or its UUID. Shows live status plus the provisioning configuration captured at creation: plan, zone, template, and boot disk size (VMs created before beta.13 show empty plan/zone/template/disk — re-create to backfill).

ID:           00a1b2c3-d4e5-6f78-9a0b-c1d2e3f4a5b6
Name:         my-server
IP:           95.216.1.100
Provider:     upcloud
Status:       running
Bootstrapped: true
Created:      2026-02-07 14:30:00
Containers:   2

SSH access to VMs (operator keys)

By default only the server’s own SSH key can log into provisioned VMs. Register your personal public key so it is baked into newly created VMs alongside the server’s key, letting you ssh root@<vm-ip> to debug:

swarm ssh-key add <name> [--key-file /path/to/id_ed25519.pub]
swarm ssh-key list
swarm ssh-key remove <name>

Without --key-file, the CLI looks for ~/.ssh/id_ed25519.pub then ~/.ssh/id_rsa.pub. Keys apply to VMs created after registration — existing VMs are not modified.

Destroy a VM

swarm vm destroy <name-or-id>

Accepts either the VM name or its UUID.

Next

• Containers — deploy devcontainers on your VMs