Start, stop and destroy
The three actions
| Action | Offered when the instance is | What it does | Usually takes | Reversible |
|---|---|---|---|---|
| Stop | running | shuts the container down, keeps the disk, holds the GPU slot | a few seconds | yes, with Start |
| Start | stopped | brings the same container back up on the same machine and disk | a few seconds | yes, with Stop |
| Destroy | any state but destroyed — including creating, starting and stopping | removes the container, deletes the disk, returns the GPU to the marketplace | a few seconds | no |
Read Stop vs destroy before you use the third one. It is the decision that determines whether you keep your data and whether you keep paying, and it is not repeated here.
Where the buttons are
Every row in Instances carries the actions that apply to that instance's current state, and the same set appears in the header of the instance detail page. Buttons that do not apply are not shown — there is no Start on a running instance and no Stop on a stopped one. Destroy stays available while an instance is still creating, starting or stopping, so an instance stuck in one of those states is never out of your reach. The console takes this list from the API's allowed_actions.
Stop and Destroy ask for confirmation first. The stop dialog says what the stop costs: the GPUs stay reserved for you, so the instance can start again right away, and while it is stopped you pay storage only. It also says what happens to the GPUs if your balance runs out. While a payment dispute has frozen the organization's payments, it says instead that this stop releases the GPUs, where the machine supports it. The destroy dialog spells out what is about to be deleted. Start does not ask.
What happens after you click
None of the three is instant. The instance moves into a transitional state, the badge pulses, and the console polls until the machine reports back:
| You clicked | State while it works | State when it lands |
|---|---|---|
| Stop | stopping | stopped |
| Start | starting | running |
| Destroy | destroying | destroyed |
While an instance is in a transitional state it accepts no action except Destroy. Asking for another one anyway returns 409 INVALID_STATE with a message naming the state that blocked it, for example Cannot stop an instance while it is creating. Wait for the transition to land and try again. The full map of which state can move where is in Instance states.
A transition the host never confirms does not leave the instance stuck. After 30 minutes a stop that has not landed puts the instance back in running — the container is still up, so it bills the GPU again — and keeps retrying the stop. A start that has not landed puts it back in stopped. The instance page then says The last action did not complete and why, and over the API the instance's error_code reads stop_timed_out or start_timed_out.
Starting again
A start needs credits: your organization's balance has to cover one hour of everything it would then be running — this instance's GPU and disk, plus the GPU and disk of every other instance that is running, starting or being created and the disk of every one that is stopped — not merely be above zero. If it does not, the start is refused with 402 INSUFFICIENT_BALANCE and nothing happens to the instance — add credits first. Storage charges that accrued while the instance sat stopped are settled at the moment you start it, so the balance you see afterwards accounts for the whole stopped period.
The host has to take the start, too. If it cannot, the instance stays stopped with its disk, and the start is refused:
| Response | What happened | What to do |
|---|---|---|
409 CAPACITY_UNAVAILABLE | The instance's GPUs were released — your balance reached zero, or a payment dispute froze payments — and another renter is using one of them now. The instance page showed GPUs released before you pressed Start | Try again later. If you cannot wait, copy your data off and destroy the instance |
409 HOST_UNREACHABLE | The machine your instance lives on is not connected right now | Start it again later |
409 START_REFUSED | The host refused to resume the instance, or no longer holds its workload | Try again later. If it keeps happening — or the API's message says the host no longer holds the workload — destroy the instance and deploy again |
503 START_UNAVAILABLE | The resume could not be completed right now | Try again shortly. If the resume did land after all, the instance moves to running on its own |
A start can also be accepted and then fail on the machine. The instance goes back to stopped on its own, with its disk, and the instance page says why under The last action did not complete — gpus_unavailable when its released GPUs turned out to be taken.
A start puts you back on the same machine with the same disk. Connection details are reissued, though, so re-copy the SSH command rather than reusing the old one. See Connect over SSH.
An instance in error
An instance that failed to come up, whose workload failed or was lost, or whose job ran to completion lands in error. It cannot be started, and it cannot be stopped. The only action available is Destroy. Read What went wrong on the instance page, which explains the instance's error_code, and the logs to find out more, then destroy it and deploy again. If the platform finds the workload running or held after all, it moves the instance back to running or stopped on its own.
Over the API
These examples use $SUPERHEAT_API and $SUPERHEAT_KEY — set them as shown in the
API overview.
curl -X POST -H "Authorization: Bearer $SUPERHEAT_KEY" \
$SUPERHEAT_API/v1/instances/$INSTANCE_ID/stop
curl -X POST -H "Authorization: Bearer $SUPERHEAT_KEY" \
$SUPERHEAT_API/v1/instances/$INSTANCE_ID/start
curl -X DELETE -H "Authorization: Bearer $SUPERHEAT_KEY" \
$SUPERHEAT_API/v1/instances/$INSTANCE_ID
Each returns the instance in its new transitional state. Poll GET /v1/instances/{id} to watch it land. See Instances.
Actions the platform takes for you
Two of these three run on their own when an organization runs out of money:
| Balance | What happens |
|---|---|
| reaches $0 | running instances are stopped, and the GPUs of stopped instances are released where the machine supports it; disks are kept |
| at or below $0 for 24 hours, and at or below −$5 | stopped and errored instances are destroyed; disks are deleted |
See Auto-stop and auto-destroy.