Skip to main content

Deploy an instance

The deploy page is step 2 of 2: you arrive with a machine already chosen and decide what runs on it. Its header reads Configure & Deploy, and Back to GPUs returns you to the marketplace without losing anything.

The form, field by field​

Offer​

The offer is not a form field — it comes in from the marketplace and is shown as a summary card at the top: GPU model, slice size, VRAM per card, location and hourly price. It is fixed for this deploy. To change the machine, go back and pick another card.

Two states replace the form instead of showing it:

What you seeWhy
"No GPU selected"You opened the page without coming through the marketplace
"That offer is gone"The offer was withdrawn from the catalog between selection and now

Template​

A grid of template cards, each checked against the machine you chose. Incompatible templates are dimmed and unclickable, and the first compatible one is preselected. The picker lists the curated templates plus, if you arrived by pressing Launch in the gallery, that template pinned at the front. See Choosing a template.

Disk​

A slider, with the current value shown above it in GB or TB.

Minimum10 GB
MaximumThe host machine's disk, shown under the slider as "Max N on this machine"
Step10 GB
Default50 GB

The API accepts disk_gb anywhere from 10 to 20,000, but the request is rejected if you ask for more than the chosen machine physically has, and the error tells you that machine's ceiling.

Size this deliberately. The disk is what you pay for while the instance is stopped, at the per-GB-per-month rate printed under the slider, and it cannot be resized later — a bigger disk means a new instance.

SSH key​

A dropdown of the SSH keys on your account, defaulting to No key (web terminal only). Add key next to it opens the same dialog as the SSH Keys page, so you can paste a public key without leaving the form.

SSH keys belong to you, not to your organization: teammates deploying from the same organization each attach their own. The key is installed at launch, so adding a key afterward does not reach an instance that is already running — the connect command on the instance page authenticates with whatever you attached here.

Leaving it on No key launches the instance with no authorized key at all, which means no ssh session. Only choose it when the template gives you a browser entry point, such as a jupyter template.

Label​

Optional free text, up to 64 characters, for telling instances apart later — llama-finetune rather than a UUID prefix. Without one, the console falls back to the first eight characters of the instance id. The label is metadata only; nothing inside the container sees it.

Environment overrides​

The console form does not expose these. The API does: env_overrides on POST /v1/instances takes a list of {key, value} pairs that override the template's declared environment by key, which is how you fill in a template's blank secret without editing the template.

Three rules apply:

  • Your value wins over the template's value for the same key.
  • An entry with no value is dropped rather than set to an empty string.
  • The platform's own variables always win over yours. You cannot shadow JUPYTER_TOKEN, GPU_COUNT or the instance access token.

See Environment variables and Instances API.

The request​

Everything above lands in one call:

{
  "offer_id": "e1c0…",
  "template_id": "9b74…",
  "disk_gb": 100,
  "label": "llama-finetune",
  "ssh_key_id": "3f21…",
  "env_overrides": [{ "key": "HF_TOKEN", "value": "hf_…" }]
}

label, ssh_key_id and env_overrides are optional; the first three fields are not.

Before the button will work​

The Deploy instance button stays disabled while any of these is true:

ConditionWhat to do
Balance is zero or belowAdd credits. Admins get an Add credits shortcut in the panel; members are told to ask an admin
The selected template is incompatible with the machinePick another template, or another GPU
No template is selectedPick one
A deploy is already in flightWait — the button reads "Deploying…"

The balance condition only looks at zero or below. The deploy itself needs the balance to cover an hour of the instance plus an hour of the organization's existing instances (step 2 below), so with a positive balance that falls short, the button works and the server refuses the deploy for insufficient balance (below).

After you press deploy​

  1. The offer is locked and re-checked. If it is no longer available, the deploy fails here and nothing else runs.
  2. The disk, template and SSH key are validated — including whether your organization may deploy the template and whether the machine can be pinned — then your balance is checked. It has to cover one hour of the instance — GPU plus the disk you picked — plus one hour of everything the organization already runs: the GPU and disk of instances running, starting or being created, and the disk of stopped ones. Being above zero is not enough. The organization must also hold fewer than 25 instances that are not destroyed; stopped and errored ones count.
  3. Only then is your unit subtracted from every shape on that machine that overlaps it, and the instance is created in creating. If that leaves the machine short of a GPU — another deploy took it in the same moment — the deploy is refused as unavailable and nothing is kept. Nobody can take your GPUs; the same offer stays rentable if the machine still has free ones. The console moves you to its page with the message "Deploying — your instance is spinning up".
  4. The page polls itself every three seconds while the instance is in a transitional state, and the hint on screen reads "Provisioning your machine…".
  5. When the instance reaches running, the connect details appear — the ready-made ssh -p <port> <user>@<host> command, and for jupyter templates an Open JupyterLab button. Until then the tab says connection details appear once the instance is running.

Billing does not start when you press the button. The meter starts when the workload reports running, so the provisioning window costs nothing, and so does a deploy that never gets there.

When a deploy fails​

ErrorMeaningWhat the console does
Offer unavailableSomeone claimed that slice firstSends you back to the marketplace
Insufficient balanceThe balance does not cover an hour of this instance on top of the organization's existing instancesToasts "Deploying needs about {amount} of credit up front. Add credits first.", where {amount} is the required_micro the API returned, and refreshes the balance; the credits prompt appears when the balance is zero or below
Disk too largedisk_gb exceeds the host machine's diskReports the machine's ceiling
Template not foundThe template id is unknown or no longer activeShows the message inline
SSH key not foundThe key id is not one of yoursShows the message inline
Machine not VM-capableA vm template on a machine that cannot run VMsShows the message inline
Machine in maintenanceThe machine is booked offline too soon to start onNames the date and sends you back to the marketplace
Instance limit reachedThe organization already has 25 instances that are not destroyed; stopped and errored ones countSays "You’ve reached the instance limit for this organization. Destroy one first." and refreshes the instance list
Template can only be deployed by its ownerAnother organization's public template that pulls from a private registry with credentialsSays "This template pulls from a private registry and can only be deployed by the organization that owns it."
Offer cannot be pinned to its machineThe machine is not registered with the fleet's control plane (the marketplace never lists such an offer)Toasts "This machine can’t take deployments right now. Pick another one."

A template that is coming soon, needs an architecture other than x86_64, or pins a CUDA older than the machine's is refused by the server too (TEMPLATE_COMING_SOON, TEMPLATE_ARCH_UNSUPPORTED, TEMPLATE_CUDA_TOO_NEW), but the console already greys those templates out, so usually only API callers meet these. See Choosing a template.

A deploy refused at any of the steps above creates nothing and charges nothing. A deploy that gets past them and then fails while provisioning is different: the instance row exists, lands in error, and is cleaned up automatically — it never bills, because the meter starts when the workload reports running and this one never did. Full list in Error codes.

The meter starts as soon as the instance runs

There is no confirmation step after this page. From the moment the instance reaches running you are billed per second, and stopping it later still bills the disk. Read Stop vs destroy before you walk away from one.