> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aireserve.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure and launch

> Choose accelerator, region, image, networking, and storage without binding your integration to one provider.

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**:

```bash theme={"dark"}
aireserve gpu instances quote \
  --accelerator H100_80GB \
  --count 1 \
  --region europe \
  --persistent-gb 200
```

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:

```bash theme={"dark"}
aireserve gpu instances launch \
  --quote-id <quote-id> \
  --name trainer-01 \
  --env-file ./trainer.env \
  --ssh-public-key-file ~/.ssh/id_ed25519.pub \
  --wait
```

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:

```bash theme={"dark"}
aireserve gpu instances launch \
  --accelerator H100_80GB \
  --max-hourly-price 3.50 \
  --ssh-public-key-file ~/.ssh/id_ed25519.pub \
  --wait
```

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

| CLI flag | REST field | Default | Purpose |
| - | - | - | - |
| `--accelerator` | `accelerator` | Required unless launching from a quote | Stable accelerator ID |
| `--count` | `count` | `1` | GPUs in one instance |
| `--region` | `region` | Any eligible region | Geographic requirement |
| `--max-hourly-price` | `maxHourlyPrice` | None | Required for direct launch; maximum new running commitment |
| `--disk-gb` | `diskGb` | `50` | Ephemeral root disk in GiB |
| `--persistent-gb` | `storage.persistentGb` | None | Create a persistent volume beside the GPU |
| `--volume-id` | `volumeId` | None | Attach an existing volume and pin placement to its location |
| `--mount-path` | `storage.mountPath` or `volumeMountPath` | `/workspace` | Persistent-storage mount path |
| `--image` | `image` | Maintained PyTorch/CUDA image | Docker-compatible image reference |
| `--name` | `name` | Generated | Human-readable name |
| `--ssh-public-key-file` | `sshPublicKey` | None | Inject one public key and open SSH |
| `--ssh-key-id` | `sshKeyIds` | `[]` | Inject registered organization keys |
| `--registry-id` | `registryCredentialId` | None | Stored private-registry credential |
| `--env-file` | `env` | `{}` | Write-only environment values |
| `--docker-start-cmd` | `dockerStartCmd` | Image default | JSON string array passed to the image's entrypoint |
| `--port` | `ports` | `[]` | Expose an HTTP or TCP port |

`--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](/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

```bash theme={"dark"}
aireserve gpu instances quote \
  --accelerator A100_80GB \
  --image ghcr.io/acme/trainer:2026-10-01

aireserve gpu instances launch \
  --quote-id <quote-id> \
  --env-file ./trainer.env \
  --registry-id <registry-credential-id> \
  --wait
```

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](/gpu-infrastructure/supporting-resources#private-container-registries)
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:

```bash theme={"dark"}
aireserve gpu instances launch \
  --accelerator H200_141GB \
  --count 8 \
  --max-hourly-price 60 \
  --image vllm/vllm-openai:<pinned-version> \
  --docker-start-cmd '["--model","<hub-owner>/<model>","--tensor-parallel-size","8"]' \
  --env-file ./model.env \
  --wait
```

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:

```bash theme={"dark"}
aireserve gpu instances launch \
  --accelerator A40_48GB \
  --max-hourly-price 1.00 \
  --port 8000/http \
  --public-ports-acknowledged \
  --wait
```

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](/api-reference) for exact schemas and [Operations, pricing, and
errors](/gpu-infrastructure/operations) for reliable polling and retry behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.