Debug a VM that will not come up

The question to settle first is whether the platform failed to build or start the machine, which you can read, or whether the guest is refusing you, which you cannot. In this order:

1. Did the create even succeed?

POST /v1/vms blocks until the machine is built, so a provisioning failure came back on the create itself as 409 create_failed, carrying the hypervisor's own text, and the partial VM was destroyed and its IP released. There is no half-built machine to inspect. Fix what detail said and create again.

2. What does the platform think the machine is doing?

GET /v1/vms/{id}

Two separate fields, and there is no state:

• status is the platform's view of the record (active).
• power is read live from the hypervisor on every request — running, stopped, or unknown.

power: "unknown" with health: "unreachable" means the hypervisor could not be reached. That is ours, not yours, and actions on that VM fail fast until it clears. A VM that was running when the hypervisor under it rebooted comes back up on its own.

If power is stopped, start it: creation leaves a machine stopped, and starting it is a separate call.

3. What happened, in order?

GET /v1/vms/{id}/events

The newest 100 events for that VM, in order: what the platform did, when, and what failed. This is where to look when a create or an action did not do what you expected.

4. Is it running but unreachable?

If power is running, nothing on our side is left to check. Then:

• The address. Each machine carries its own ip in GET /v1/vms. A recreated VM has a different address — the old one went back to the pool. If you wrote an address down rather than putting a DNS name in front, this is usually it.
• Your own firewall. The only rule the platform enforces is anti-spoof. Nothing else inbound is filtered by us, so anything dropping your connection is running in your guest: Firewall.
• Your key. The keys you passed at creation are the only way in. Log in as ubuntu.

5. If it is the guest, it is unrecoverable

There is no console, no password and no rescue mode, so a firewall or sshd change that locks you out has no door behind it. Two ways out:

• Roll back a snapshot, if you took one before the change. It needs the VM stopped and leaves it stopped, and only the newest snapshot is restorable. See Snapshots.
• Recreate the VM and re-run your configuration. Your volumes detach from the old machine and attach to the new one with their data intact; the root disk does not survive.

To not be here again, make every firewall and sshd change revert itself unless you confirm it: Harden a VM.