Rebuild a Cloud Instance

A rebuild throws away a cloud instance's current system and installs a fresh one from an image. It's the same instance afterwards, with the same specs and the same primary IP. Use it to start over: a different operating system, a broken install you'd rather not repair, or a machine you want back in a known clean state. Be certain of one thing first: it erases everything on the instance.

What rebuild does, and does not, keep

The disk is replaced with a clean image, and your data, installed packages and configuration go with the old one. The instance itself stays: its CPU, memory and disk size, its account, and its primary IP address. Your SSH keys and your cloud-init user data get applied to the new system as it boots, so a rebuilt instance can come up already configured. Any apps you staged in the App Library go on during the rebuild as well.

Because the disk gets wiped, take a snapshot or a backup first if there's anything on the instance you might want back. A rebuild has no undo of its own.

In the portal

1. Find the instance under Virtual Machines and open its Rebuild tab.
2. Choose an image from the template list.
3. Decide how you'll log in. Tick the SSH keys you want installed, or set a root password.
4. Set a hostname if you want one. Once you confirm, the rebuild starts.

The instance goes through provisioning and is back up on the new image a few minutes later. You can follow along on the instance page or in the Activity log.

With the API

Rebuild needs the VMs scope (vms.write). List the images the instance can use, then rebuild onto one of them. For keys, see Getting started with the Amóni API.

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 using the template's vmid. Pass SSH keys and a hostname too, and the machine comes up ready to use:

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, so the call comes back with 202 and a pending operation. From there, poll GET /v1/operations/{id} until its status reaches succeeded or failed, or subscribe a webhook and react to the operation.succeeded event for vm.rebuild. For login, pass ssh_key_ids from your stored keys or a raw sshkeys string, or set a password if you'd rather log in with one. For more control over the first boot, set cloud-init user data before you rebuild.

Rebuild, reinstall or restore

• Rebuild is for cloud instances. It wipes the disk and lays down a fresh image from a template.
• Reinstall is the same idea for bare metal; see reinstall the operating system.
• Restore brings back a specific earlier state from a backup instead of a clean image. Use it when what you want is your data, not a blank machine.

Questions we get

• Does rebuild keep my data? No, it wipes the disk. If you need anything from it, snapshot or back up first.
• Does my IP change? No. Its primary IP, specs and account all stay with the instance.
• Can I change the operating system? Yes, pick a different image. That's the main reason to rebuild instead of restoring.
• How do I know when it is done? It takes a few minutes. Poll the operation id, watch the Activity log, or let a webhook tell you.
• My SSH key did not get installed. Check that the key id still exists in your account and that it was actually passed to the rebuild. You can also add keys afterwards on the instance's SSH Keys tab. They apply after a stop and start from the portal; a reboot doesn't apply them.

Still stuck?

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