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 both ask for confirmation first. The stop dialog, Stop this instance?, says that the GPUs stay reserved for you and that you pay storage only while it is stopped (with the instance's storage rate per hour), and that if your balance runs out, instances are stopped for you and their GPUs released where the machine supports it; Stop instance confirms and Keep running cancels. The destroy dialog spells out what is about to be deleted. Start does not ask twice.
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 a balance that covers one hour of everything the organization 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. Being above zero is not enough. Short of that, the start is refused with 402 INSUFFICIENT_BALANCE (required_micro in the response is the amount needed) 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, and the balance check uses the balance after that settlement, 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 kept, the start is refused, and the console toasts the matching message:
| Response | What the console says | What to do |
|---|---|---|
409 HOST_UNREACHABLE | "The machine this instance lives on isn’t connected right now. It’s still stopped — try starting it again later." | Start it again later |
409 START_REFUSED | "The machine couldn’t resume this instance, so it’s still stopped. If this keeps happening, destroy it and deploy again." | The API's message says whether the host refused the resume or no longer holds the workload; in the second case destroy the instance and deploy again, otherwise try again later |
503 START_UNAVAILABLE | "The instance couldn’t be resumed right now. It’s still stopped — try again shortly." | Try again shortly. If the resume did land after all, the instance moves to running on its own |
409 CAPACITY_UNAVAILABLE | "The GPUs this instance used are in use by someone else right now, so it can’t start. It’s still stopped with its disk — try again later." | Happens only to an instance whose GPUs were released. Start it again later: nothing can reach the disk until a start succeeds. If it keeps failing, the only way forward is to destroy it, which deletes the disk, and deploy again |
An instance whose GPUs were released when the balance ran out — an auto-stopped one, or one you had stopped yourself, where the machine supports it — has to take back the same GPUs on the same machine when it starts. When the platform accepts the start and the machine only then finds them taken or out of service, the request returns no error: the instance goes to starting and back to stopped, and the instance page shows, under The last action did not complete, "The GPUs this instance used on its machine are in use by someone else right now. It’s still stopped with its disk — try starting it later, or destroy it." See After the GPUs are released.
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, whose job ran to completion, or whose container disappeared while it was stopped (workload_gone) 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, disks are kept. Where the machine supports it, their GPUs and those still held by stopped instances are released |
| at or below ¥0 for 24 hours, and at or below −¥35 | stopped and errored instances are destroyed; disks are deleted |
See Auto-stop and auto-destroy.