Instance lifecycle
An instance is always in exactly one of eight states. Which state it is in decides three things you care about: whether you can connect to it, whether it is billing you, and which actions are available.
The state machine
The normal path is creating → running → stopping → stopped → starting → running. Teardown is always destroying → destroyed, and it can begin from running, stopped or error.
There are no other legal moves. Asking for one the current state does not allow — starting an instance that is already running, stopping one that is still creating — is rejected, and the instance stays where it was.
Every state
| State | Transitional | Billing | What it means |
|---|---|---|---|
creating | yes | none | The slice has been reserved and your workload is being brought up for the first time. |
starting | yes | none | A stopped instance is coming back on the same machine, with the same disk. |
running | no | GPU, per second | The workload is up. SSH, JupyterLab and your published ports are reachable. |
stopping | yes | none | The container is being shut down. Your disk is being kept. |
stopped | no | disk, per GB per hour | Nothing is executing. The disk and the GPU slot are still held for you. |
destroying | yes | none | The container and the disk are being torn down. |
destroyed | no | none | Final. The disk is gone and the offer is back on the marketplace. |
error | no | none | The instance could not be brought up. See below. |
Transitional states are the four the platform is actively working through; the console shows them with a pulsing badge and refreshes more often while one is in flight. They resolve on their own — there is nothing to click and no action to retry.
Non-transitional states are stable. An instance sits in running, stopped, destroyed or error until you or the billing system moves it.
What causes each transition
| Transition | Trigger |
|---|---|
→ creating | You deploy: POST /v1/instances with an offer, a template and a disk size. |
creating/starting → running | The workload reported itself up. The GPU meter starts here, not at deploy. |
creating/starting → error | The workload could not be brought up. |
running → stopping | You stop it, or your balance reaches $0. |
stopping → stopped | The shutdown finished. The disk meter starts here. |
stopped → starting | You start it. Requires a positive balance. |
running/stopped/error → destroying | You destroy it, or your balance reaches −$5. |
destroying → destroyed | Teardown finished. The disk is deleted and the offer is released. |
Two of those triggers are not yours. When the organization's balance hits zero, running instances are stopped automatically; if it keeps falling to −$5, everything is destroyed. Both are covered in Auto-stop and auto-destroy.
Deploying and starting both require a balance above zero. Stopping and destroying never do — you can always shut something down, whatever your balance is.
Billing follows the state
Charges are settled at the rate of the state the instance was actually in, and every state change settles what was owed before the change takes effect. The GPU meter runs only in running. The disk meter runs only in stopped. The four transitional states, error and destroyed are free.
This is why a deployment that takes two minutes to come up is not billed for those two minutes, and why a stopped instance still produces a charge every minute in your ledger.
What "error" means
error means the platform could not bring your workload up — the image failed to pull, the container refused to start, or the host stopped reporting during launch.
Four things follow from that:
- You are not billed. The meter is off in
error, and nothing accrues while the instance sits there. - It will not fix itself. There is no automatic retry. The instance stays in
erroruntil you act. - The offer is still held. The slice is not released back to the marketplace until the instance reaches
destroyed. - Destroy is the only move. You cannot start, stop or repair an errored instance. Destroy it, fix the cause, and deploy again.
The usual causes are in the template rather than the hardware: an image name or tag that does not exist, or a private registry whose credentials are wrong. An ssh or jupyter template whose image is not built on the Superheat base image cannot come up either, because those modes depend on the base image's entrypoint.
An instance that never reached running has no logs to read, so debug from the template rather than from the instance. Troubleshooting works through the specific failures.
It costs nothing, but nobody else can rent that slice and you cannot redeploy onto it. Destroy it so the slice goes back on the market.
Where you see states
The Instances page lists everything except destroyed instances. Through the API, GET /v1/instances?include_destroyed=true brings them back.
Each instance page shows the current state as a badge, only the actions the current state allows — Start on a stopped instance, Stop on a running one, Destroy on running, stopped or errored — and, once the workload is up, the connect details on its Connect tab.