Skip to main content
An instance request describes the outcome you need. AI Reserve maps that request to eligible infrastructure, chooses a location, and returns a normalized resource.

​
Quote first

The recommended workflow is request → quote → launch:
A quote:
  • runs the same placement selection used by a direct launch;
  • includes GPU, root-disk, and requested persistent-storage prices;
  • shows what continues billing after stop or termination;
  • creates and charges nothing;
  • expires after 120 seconds and does not reserve capacity.
Launch the priced configuration and add workload-only settings:
Hardware, region, root disk, image, and storage stay as quoted. If their price changes before acceptance, launch fails with price_changed and creates nothing. Request a fresh quote.

​
Launch without a quote

For automation that already has a spending policy, launch directly with a ceiling:
The ceiling applies to the new running commitment: GPU, ephemeral root disk, and any persistent storage created by this request. The launch is refused before provisioning when no eligible placement fits.

​
Request controls

--persistent-gb and --volume-id are mutually exclusive. If you provide both region and an existing volume, the region must include the volume’s location. AI Reserve rejects a contradiction rather than moving the volume.

​
Accelerator IDs

Use an AI Reserve accelerator family such as H100_80GB, not a provider catalog name. The generated API Reference is the source of truth for the currently accepted enum; provider-specific SKUs can map into one stable family.

​
Custom images and secrets

Environment values are accepted at launch and are never returned. The normalized instance resource does not currently expose their key names. Use a stored registry credential for private images instead of placing a registry password in an environment variable.

​
Model-serving containers

The provider-hidden API can launch any compatible container without adding a model-specific preset. Pass simple image arguments as a JSON string array. The current backend serializes that array into the provider’s command field, so put complex shell logic in the image or a mounted script instead of relying on quoting here:
Pin an image version or digest. The exact model revision, quantization, parallelism, CUDA compatibility, and memory requirement are workload choices; AI Reserve does not infer them from the model name. An instance reaching running confirms the requested infrastructure is present, not that the model server has loaded its weights. Watch aireserve gpu instances logs <instance-id> --follow for startup. The stock vLLM image does not provide SSH or an authenticated health route, so this private launch is not yet a production endpoint. To serve traffic, package an authenticating proxy in your image, expose the proxy rather than vLLM directly, and probe that authenticated proxy before admitting traffic.

​
Public services

Expose an HTTP port only when the process inside the container enforces its own authentication:
The explicit acknowledgement is required for HTTP ports. Retrieve public URLs with aireserve gpu instances connections <instance-id> after the instance is running.

​
Direct REST

The CLI maps to POST /v1/gpu/instances/quote and POST /v1/gpu/instances. Launch mutations require an Idempotency-Key and return 202 Accepted with operationId and resourceId. Use the generated API Reference for exact schemas and Operations, pricing, and errors for reliable polling and retry behavior.