> ## 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.

# GPU Compute (pilot)

> Rent RunPod GPU containers, attach persistent storage, and pay through your AI Reserve wallet — all from the portal, REST API, or CLI.

<Note>
  GPU Compute is currently in a **closed pilot**. Access is enabled per organization by AI Reserve and requires an eligible wallet. Contact your account team to request access. The feature description below reflects the pilot scope; additional capabilities will be added in later releases.
</Note>

GPU Compute lets an enabled organization rent GPU-backed containers through
[RunPod](https://runpod.io) Secure Cloud, attach independently-billed persistent
network volumes, and manage the full lifecycle — create, stop, start, terminate —
through the AI Reserve portal, REST API (`/v1/gpu/*`), or CLI
(`aireserve gpu ...`). Billing runs through your existing AI Reserve wallet
using hourly accrued charges and receipt-confirmed wallet collection.

This is general-purpose GPU infrastructure, not an extension of the
[Dedicated GPU Endpoints](/capabilities/dedicated-gpu-endpoints) feature.
Dedicated GPU Endpoints run managed vLLM inference through the AI Reserve
gateway; GPU Compute gives you a raw container where you install and run
whatever software you need.

## What you can do

| Capability         | Description                                                                                                                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GPU catalog        | Browse GPU models, counts, available data centers, and estimated hourly prices. Browsing does not reserve capacity.                                                                         |
| Create a pod       | Launch a GPU container from a curated template or custom Docker image. Configure GPU/count, container disk size, ports, environment variables, SSH keys, and an optional persistent volume. |
| Stop and start     | Stop a pod to release the GPU container without deleting the persistent volume. Restart it later — subject to capacity availability and billing rules below.                                |
| Terminate          | Permanently destroy a pod. The attached volume remains and continues to bill independently until you delete it.                                                                             |
| Persistent volumes | Create a RunPod network volume, attach it at pod creation, grow it, and reuse it with a new pod after termination.                                                                          |
| Templates          | Use curated PyTorch, JupyterLab, vLLM, and ComfyUI starting configurations, or save private organization templates.                                                                         |
| Private images     | Store an encrypted registry credential and pull from private container registries. Credentials are never echoed back.                                                                       |
| Connect            | Copy SSH commands, view exposed port URLs, and open authenticated web services for curated templates that support them.                                                                     |
| Logs               | View live and recent container logs from the portal or CLI for debugging. Logs are relayed on demand; AI Reserve stores no log archive.                                                     |
| REST and CLI       | Perform any operation programmatically using the `/v1/gpu/*` REST routes or `aireserve gpu ...` CLI commands.                                                                               |

## Billing

### Compute (pods)

GPU usage is recorded in completed hourly intervals after the ordered allocation
is confirmed running. The web app owns the accrued charges; wallet collection is
attempted separately, and charges are cleared only after an authoritative receipt.
Stopping or terminating closes the final partial interval proportionally to elapsed
time, rounded up to one microdollar. Stopped time does not accrue GPU charges.

The default payment grace is **24 hours from the first unpaid interval becoming
due**. Operators can configure it; retries do not reset the deadline. Existing
workloads can run during grace, but outstanding charges block new allocations and
restarts. At expiry, running pods are stopped, not deleted. Unknown settlement
outcomes retain debt and do not extend credit indefinitely. Top-ups allow automatic
collection to retry; they do not automatically restart stopped workloads.

### Storage (volumes)

Persistent volumes are billed separately and independently of pod state.
A volume accrues charges continuously while it exists at RunPod — whether or
not a pod is attached, stopped, or running. Storage billing is not paused when
a pod stops.

Each completed hour's storage charge accrues in a separate billing window. The
current rate and accumulated charges are visible on the volume detail page.

Unpaid storage uses the same configured payment grace, followed by operator escalation. Volumes are never deleted automatically for nonpayment.

**Deleting the volume stops storage accrual.** A running or stopped pod must
be terminated before its attached volume can be deleted.

### What is not charged

* Stopped-pod compute time: no new GPU compute charge accrues after confirmed stop.
* Inference requests through your container: GPU Compute pods are not routed
  through the AI Reserve gateway. Any model inference your container performs
  is billed by RunPod or the provider you configure directly.

## Storage persistence

| Disk type                   | Persists across stop/start?               | Persists after terminate? | Billed when?                            |
| --------------------------- | ----------------------------------------- | ------------------------- | --------------------------------------- |
| Container disk              | No — ephemeral; lost on stop or terminate | No                        | Included in compute quote while running |
| Network volume (persistent) | Yes                                       | Yes                       | Continuously, independent of pod state  |

The container disk is sized at pod creation and is lost whenever the container
is destroyed. Attach a RunPod network volume to store data durably.
Volume contents at the mount path (default `/workspace`) survive stops, restarts,
and pod termination — as long as the volume itself has not been deleted.

**Files outside the mounted volume path are lost when a pod stops or terminates.**
AI Reserve does not copy, back up, index, or browse volume contents. RunPod
holds the volume data; consult RunPod's documentation and your data agreements
for their retention and privacy practices.

## SSH and connections

### Direct SSH

Direct SSH is the baseline supported connection method. Every pod exposes an
SSH endpoint. Add your public SSH key under **Compute → Settings → SSH Keys**
before creating a pod, then select it during pod creation. The portal and CLI
provide the exact `ssh` command to copy and run.

**Key requirements:** Ed25519, RSA (2048–8192 bit), or ECDSA (nistp256/384/521).
`authorized_keys` options are not accepted. Keys are validated, type-checked,
and stored with their canonical SHA-256 fingerprint. Removing or rotating a key
in the portal takes effect at the next pod restart; existing SSH sessions are
not instantly severed.

### Curated template web services

Curated templates (JupyterLab, vLLM, ComfyUI) expose authenticated web
services. The portal shows launch links once authentication is confirmed.

<Warning>
  Public RunPod proxy URLs are not shielded by your portal login. These
  services enforce their own application-layer authentication — AI Reserve does
  not add an additional auth layer in front of them.
</Warning>

### Custom images

If you bring your own Docker image, you are responsible for configuring SSH
access and any application authentication inside the container. AI Reserve
does not inject keys into arbitrary images, does not run an in-browser terminal
relay, and cannot retroactively enforce authentication on a running custom
container. Custom HTTP ports you expose are explicitly public; the portal shows
a disclosure during pod creation.

## Access control

GPU Compute requires an explicit grant on the API key used. Existing inference
keys gain no Compute authority.

| Access level     | What it allows                                                                                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` (default) | No access to any Compute endpoint or portal section. All existing inference keys are unaffected.                                                                                        |
| `read`           | Browse catalog; view pod/volume/template/registry/SSH-key metadata; check operation status; view usage and charges. No access to workload logs, SSH credentials, or connection details. |
| `manage`         | Everything in `read`, plus: create/start/stop/terminate pods; create/grow/delete volumes; manage templates, registry credentials, and SSH keys; view logs and connection details.       |

An organization admin grants compute access to a key from
**Compute → Settings → API Keys**. Team-scoped keys cannot hold compute grants
in this release.

Portal sessions follow the same model: org members get read access; org admins
get manage access. Revoking a key removes its Compute control-plane access
immediately but does not delete org resources or cancel storage billing.

## Limitations and pilot notes

* **Secure Cloud only.** On-demand RunPod Secure Cloud GPUs. No spot,
  serverless, or other cloud tier in this release.
* **One volume per pod.** A pod can be attached to at most one network volume,
  chosen at creation. Live detach, volume shrink, and cross-data-center volume
  migration are not supported.
* **Restart capacity is not guaranteed.** Stopping and restarting a pod may
  fail if capacity for your GPU type is no longer available.
* **No in-browser terminal.** AI Reserve does not run a browser-based SSH
  relay. Use the SSH command provided in the portal or CLI.
* **No log archive.** Live and recent container logs are relayed on demand;
  AI Reserve does not store workload log archives. RunPod-side retention is
  governed by RunPod's policies.
* **Single data center per volume.** A network volume and its attached pod must
  be in the same RunPod data center.

## CLI quickstart

Install the `aireserve` CLI and export your API key (must have compute `manage` access):

```bash theme={"dark"}
export AIRESERVE_API_KEY="aireserve_api_..."

# Browse available GPUs
aireserve gpu catalog

# Quote storage, then copy its quoteId into the create command
aireserve gpu quote --datacenter EU-RO-1 --volume-size-gb 50
aireserve gpu volumes create \
  --name my-workspace \
  --datacenter EU-RO-1 \
  --size-gb 50 \
  --quote-id <volume-quote-id> \
  --storage-billing-acknowledged

# Quote a GPU pod (use a GPU type ID returned by the catalog)
aireserve gpu quote \
  --gpu-type <gpu-type-id> \
  --datacenter EU-RO-1 \
  --container-disk-gb 20

# Launch a pod using a Docker image configured for your workload and SSH
aireserve gpu pods create \
  --name dev-box \
  --gpu-type <gpu-type-id> \
  --gpu-count 1 \
  --datacenter EU-RO-1 \
  --image-id <docker-image> \
  --container-disk-gb 20 \
  --volume-id <volume-id> \
  --ssh-key-id <key-id> \
  --quote-id <pod-quote-id> \
  --ephemeral-disk-acknowledged

# Watch operation progress
aireserve gpu operations wait <operation-id>

# Inspect pod metadata
aireserve gpu pods get <pod-id>

# Connect with your registered local SSH key
aireserve gpu pods ssh <pod-id>

# View live logs
aireserve gpu pods logs <pod-id>

# Stop the pod (volume keeps billing)
aireserve gpu pods stop <pod-id>

# Terminate the pod when done
aireserve gpu pods terminate <pod-id>

# Delete the volume to stop storage charges
aireserve gpu volumes delete <volume-id>
```

<Warning>
  Terminating a pod is irreversible. The attached volume is not deleted
  automatically — it continues to accrue storage charges until you explicitly
  delete it.
</Warning>

## REST quickstart

All Compute endpoints require a key with `read` or `manage` compute access and
live under the `/v1/gpu/` prefix. Include an `Idempotency-Key` header
on all mutating requests so retries are safe.

```bash theme={"dark"}
export KEY="aireserve_api_..."

# Browse the GPU catalog
curl https://api.aireserve.com/v1/gpu/catalog/gpus \
  -H "Authorization: Bearer $KEY"

# Obtain a short-lived quote for the exact hardware spec
curl -X POST https://api.aireserve.com/v1/gpu/quotes \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpuTypeId": "<gpu-type-id-from-catalog>",
    "gpuCount": 1,
    "dataCenterId": "EU-RO-1",
    "containerDiskGb": 20
  }'

# Copy quoteId from the response; keep the same idempotency key when retrying
# Create a pod (returns 202 + operation/resource IDs)
curl -X POST https://api.aireserve.com/v1/gpu/pods \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-dev-box-request-001" \
  -d '{
    "quoteId": "<quote-id>",
    "name": "dev-box",
    "gpuTypeId": "<gpu-type-id-from-catalog>",
    "gpuCount": 1,
    "dataCenterId": "EU-RO-1",
    "templateId": "<curated-template-id>",
    "containerDiskGb": 20,
    "networkVolumeId": "<volume-id>",
    "sshKeyIds": ["<key-id>"],
    "ephemeralDiskAcknowledged": true
  }'

# Poll operation status
curl https://api.aireserve.com/v1/gpu/operations/<operation-id> \
  -H "Authorization: Bearer $KEY"
```

All mutations return `202 Accepted` with a resource ID and an operation ID.
Poll `GET /v1/gpu/operations/{id}` for terminal status (`succeeded`,
`failed`). Synchronous validation and funding errors use `4xx` codes; later
provider failures appear in operation state. See the
[API Reference](/api-reference) for the complete schema.

## Data and privacy

AI Reserve stores control-plane metadata (pod/volume configuration, SSH public
keys, billing records, operation logs) but does not store prompt or response
bodies, workload logs, or volume contents. Volume data is held by RunPod as a
subprocessor. See [Data & Privacy](/trust/data-privacy) and the
[AI Reserve subprocessors list](https://privacy.aireserve.com/subprocessors).

Registry credentials and environment variable secrets are encrypted at rest
and never returned in API responses. SSH connection details and terminal tokens
are scoped to sessions and not logged.