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

# GPU sandboxes

> Build an image, choose a GPU, and run CUDA workloads in a sandbox.

Run model inference, training, and other CUDA workloads on a GPU sandbox. You choose the GPU and bring your application in a Docker image. Once the sandbox is running, you can execute commands, work with files, and expose services as you would in any other sandbox.

<Info>
  Contact us at [info@hyperbrowser.ai](mailto:info@hyperbrowser.ai) or through support chat to enable GPU access for your team.
</Info>

## Before you start

[Install and configure the CLI](/docs/sandboxes/install), using `hx` 0.1.25 or later. The example below builds an image remotely, so you don't need Docker installed on your computer.

## Build a GPU image

Your image needs the libraries your application will use on the GPU. This example uses PyTorch with CUDA 12.8.

Create a folder called `gpu-python` and save the following as `gpu-python/Dockerfile`:

```dockerfile theme={null}
FROM pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime
WORKDIR /workspace
CMD ["sleep", "infinity"]
```

From the parent directory, build the image:

```bash theme={null}
hx vm image build --remote ./gpu-python gpu-python --enable-gpu-builds
```

Copy the build ID from the output and replace `YOUR_BUILD_ID` below:

```bash theme={null}
hx vm image wait YOUR_BUILD_ID
```

Wait for this command to finish successfully before continuing. It waits for both the build and GPU image upload.

Hyperbrowser supplies the GPU driver when your sandbox starts. The build itself runs without a GPU, so Dockerfile steps should install dependencies rather than run GPU computations. For more build options, see [Custom images](/docs/sandboxes/custom-images).

## Create a GPU sandbox

Start your image on an L4 GPU:

```bash theme={null}
hx vm create gpu-python --gpu L4 \
  --cpu 2 --memory 4g --timeout-minutes 10 \
  --wait-for-provisioning
```

This gives you one L4 GPU, 2 vCPUs, 4 GiB of system memory, and the default 12 GiB of disk. The command waits until the sandbox is ready, which can take several minutes. Its ten-minute lifetime and usage billing begin once it starts running.

Copy the sandbox ID from the output into this variable for the remaining commands:

```bash theme={null}
SANDBOX_ID="YOUR_SANDBOX_ID"
```

If you interrupt the wait, the sandbox continues provisioning. You can still use its ID to [stop it](#stop-the-sandbox).

## Run code on the GPU

Run a small PyTorch computation inside the sandbox:

```bash theme={null}
hx vm exec "$SANDBOX_ID" 'python -' <<'PY'
import torch

x = torch.tensor([1.0, 2.0, 3.0], device="cuda")
print(torch.cuda.get_device_name(0))
print((x * x).sum().item())
PY
```

You should see:

```text theme={null}
NVIDIA L4
14.0
```

PyTorch has created a tensor on the GPU and computed the sum of its squared values. You can now run your own scripts the same way. Use [background processes](/docs/sandboxes/processes) for longer jobs, or [expose a port](/docs/sandboxes/runtime) to serve a model or web application. Servers should listen on `0.0.0.0`.

## Stop the sandbox

Stop the sandbox when you're done:

```bash theme={null}
hx vm stop "$SANDBOX_ID"
```

Stopping releases its resources and ends usage billing. Files written inside the sandbox are deleted, so download results or save them to external storage first. Your image remains available to start another sandbox.

## Choose GPUs and resources

Set `--gpu` to a GPU type from the [pricing table](/docs/pricing#gpu-sandboxes). Add `--gpu-count` when your application needs more than one GPU. You can request 1–8 GPUs of the same type on one host, subject to available capacity and host sizes. Each GPU is reserved for your sandbox; the host may also run other sandboxes.

| Resource | How to choose it |
| - | - |
| GPU | Choose a type with enough GPU memory (VRAM) for your model and workload. |
| CPU (`--cpu`) | Allocate CPU cores for work such as loading data and preprocessing. |
| System memory (`--memory`) | Set the RAM your application needs. This is separate from GPU memory. |
| Disk (`--disk`) | Allow space for downloaded models, temporary files, and results. GPU sandboxes default to 12 GiB and support 12–64 GiB, subject to plan and host limits. |

GPU sandboxes use the `us` region by default. GPU, CPU, and system memory are billed while the sandbox is running, including idle time. Provisioning time is not billed. See [Pricing](/docs/pricing#gpu-sandboxes) for rates and a worked example.

## Use the REST API

After building the image, you can also create and manage GPU sandboxes with the API. The Node 1.3.0 and Python 1.13.0 SDKs do not expose GPU creation fields; use the CLI or REST API with those versions.

<Accordion title="Create, run, and stop with cURL">
  Set `HYPERBROWSER_API_KEY` as described in [Install](/docs/sandboxes/install), then create a sandbox from the `gpu-python` image you built above:

  ```bash theme={null}
  curl --fail-with-body https://api.hyperbrowser.ai/api/sandbox \
    -H "x-api-key: $HYPERBROWSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "imageName": "gpu-python",
      "region": "us",
      "gpu": "L4",
      "gpuCount": 1,
      "vcpus": 2,
      "memMiB": 4096,
      "diskSizeMiB": 12288,
      "timeoutMinutes": 10
    }'
  ```

  The response is `202 Accepted` with `status: "provisioning"`. Copy its `id` into `SANDBOX_ID`:

  ```bash theme={null}
  SANDBOX_ID="YOUR_SANDBOX_ID"
  ```

  Check the sandbox's status:

  ```bash theme={null}
  curl --fail-with-body \
    "https://api.hyperbrowser.ai/api/sandbox/$SANDBOX_ID" \
    -H "x-api-key: $HYPERBROWSER_API_KEY"
  ```

  Repeat this request every few seconds until `status` is `active`. If it ends or fails instead, check `closeReason` before creating another sandbox. While provisioning, `runtime` and `token` are `null`.

  Once active, copy `runtime.baseUrl` and `token` from the response:

  ```bash theme={null}
  RUNTIME_BASE_URL="YOUR_RUNTIME_BASE_URL"
  SANDBOX_TOKEN="YOUR_SANDBOX_TOKEN"
  ```

  Send a command to the runtime URL using the sandbox token:

  ```bash theme={null}
  curl --fail-with-body "$RUNTIME_BASE_URL/exec" \
    -H "Authorization: Bearer $SANDBOX_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- <<'JSON'
  {"command":"python -c \"import torch; x = torch.tensor([1., 2., 3.], device='cuda'); print(torch.cuda.get_device_name(0)); print((x * x).sum().item())\""}
  JSON
  ```

  The command output is in `result.stdout`. It contains `NVIDIA L4` and `14.0`, just like the CLI example.

  Stop the sandbox when you're finished. This also works while it is still provisioning:

  ```bash theme={null}
  curl --fail-with-body -X PUT \
    "https://api.hyperbrowser.ai/api/sandbox/$SANDBOX_ID/stop" \
    -H "x-api-key: $HYPERBROWSER_API_KEY"
  ```
</Accordion>

<a id="availability-and-limits" />

## Storage and interruptions

GPU sandboxes support [files](/docs/sandboxes/filesystem/overview), [terminals](/docs/sandboxes/terminal), [exposed ports](/docs/sandboxes/runtime), and [network policies](/docs/sandboxes/networking). They do not support memory snapshots, shared volumes, or managed secret injection through secrets, vaults, or 1Password.

GPU workloads can be interrupted, and running processes are not automatically resumed or replayed. Save checkpoints and results to external storage so you can recover your work in a new sandbox.

## Troubleshooting

| Problem | What to do |
| - | - |
| GPU access is not enabled (`403`) | Contact us to enable GPU access for your team. |
| Team image not found (`404`) | Use a GPU image built by your team. Built-in CPU images such as `node` and `python` cannot be used for GPU creation. |
| GPU image is not uploaded yet (`409`) | Run `hx vm image wait` with the build ID. If you use the build API, wait for `gpuImageReady: true`; `status: "completed"` alone does not confirm GPU readiness. Rebuild if GPU publication failed. |
| Invalid resources (`400`) | Check the GPU type and count, use `region: "us"`, and request at least 12 GiB of disk. |
| Capacity or quota limit (`429`) | Read the error message. Retry later for capacity, or adjust resources or your team's quota. |
| Provisioning ends without becoming active | Check `closeReason` and keep the sandbox ID when contacting support. |

See the [create-sandbox API reference](/docs/api-reference/create-new-sandbox) for all request fields.


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