Rebuild a Cloud Instance

Rebuilding a cloud instance throws away its current system and installs a fresh one from an image, on the same instance with the same specs and the same primary IP. It is how you start over: change the operating system, recover from a broken install, or return a machine to a known clean state. The one thing to be certain of first is that it erases everything on the instance.

What rebuild does, and does not, keep

A rebuild replaces the disk with a clean image. Your data, installed packages and configuration are gone. What stays is the instance itself: its CPU, memory and disk size, its account, and its primary IP address. Your SSH keys and your cloud-init user data are applied to the new system as it comes up, so a rebuilt instance can arrive already configured.

Because it wipes the disk, take a snapshot or a backup first if there is anything on the instance you might want. A rebuild cannot be undone from within itself.

In the portal

1. Open the instance from Cloud and go to its Rebuild tab.
2. Pick an image from the list of templates.
3. Choose how you will log in: tick the SSH keys to install, or set a root password.
4. Optionally set a hostname. Confirm, and the rebuild starts.

The instance goes through provisioning and comes back up on the new image after a few minutes. Watch its progress on the instance page or the Activity log.

With the API

Rebuild needs the VMs scope (vms.write). First list the images available to the instance, then rebuild onto one. See Getting started with the Amóni API for keys.

curl -s https://api.amoni.app/v1/vms/990204/411/templates \
  -H "Authorization: Bearer nr_live_..."
# { "success": true, "data": [ { "vmid": 9001, "name": "ubuntu-24.04" },
#                              { "vmid": 9002, "name": "debian-12" } ] }

Rebuild with the template's vmid. Add SSH keys and a hostname so the machine comes up ready:

curl -s -X POST https://api.amoni.app/v1/vms/990204/411/rebuild \
  -H "Authorization: Bearer nr_live_..." -H "Content-Type: application/json" \
  -d '{
        "template_vmid": 9001,
        "hostname": "app1.example.com",
        "ssh_key_ids": [12]
      }'

{ "success": true, "data": {
    "message": "Rebuild started. This wipes the current system and takes several minutes.",
    "operation": { "id": 91, "status": "pending" }
} }

A rebuild is asynchronous: the call answers 202 with a pending operation. Poll GET /v1/operations/{id} until its status reaches succeeded or failed, or subscribe a webhook and act on the operation.succeeded event for vm.rebuild. Pass ssh_key_ids from your stored keys, or a raw sshkeys string; set a password instead if you want password login. To shape the first boot further, set cloud-init user data before you rebuild.

Rebuild, reinstall or restore

• Rebuild is for cloud instances: a fresh image from a template, wiping the disk.
• Reinstall is the bare-metal equivalent; see reinstall the operating system.
• Restore puts back a specific earlier state from a backup, rather than a clean image. Reach for it when you want your data back, not a blank machine.

Questions we get

• Does rebuild keep my data? No. It wipes the disk. Snapshot or back up first if you need anything.
• Does my IP change? No. The instance keeps its primary IP, specs and account.
• Can I change the operating system? Yes. Pick a different image; that is the main reason to rebuild rather than restore.
• How do I know when it is done? Poll the operation id, watch the Activity log, or use a webhook. It takes a few minutes.
• My SSH key did not get installed. Confirm the key id is still in your account and was passed to the rebuild. You can add keys and re-run cloud-init afterwards.

Still stuck?

Open a support ticket with the instance and the rebuild's operation id, and we can see exactly what the image did.