GPU sandboxes

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.

Before you start

Install and configure the CLI, 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:

FROM pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime
WORKDIR /workspace
CMD ["sleep", "infinity"]

From the parent directory, build the image:

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:

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.

Create a GPU sandbox

Start your image on an L4 GPU:

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:

SANDBOX_ID="YOUR_SANDBOX_ID"

If you interrupt the wait, the sandbox continues provisioning. You can still use its ID to stop it.

Run code on the GPU

Run a small PyTorch computation inside the sandbox:

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:

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 for longer jobs, or expose a port 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:

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

Create, run, and stop with cURL

Set HYPERBROWSER_API_KEY as described in Install, then create a sandbox from the gpu-python image you built above:

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:

SANDBOX_ID="YOUR_SANDBOX_ID"

Check the sandbox’s status:

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:

RUNTIME_BASE_URL="YOUR_RUNTIME_BASE_URL"
SANDBOX_TOKEN="YOUR_SANDBOX_TOKEN"

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

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:

curl --fail-with-body -X PUT \
  "https://api.hyperbrowser.ai/api/sandbox/$SANDBOX_ID/stop" \
  -H "x-api-key: $HYPERBROWSER_API_KEY"

Storage and interruptions

GPU sandboxes support files, terminals, exposed ports, and network policies. 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 for all request fields.

Get Started

Sandbox

Base Images

Custom Images

Volumes

Local Filesystem

Before you start

Build a GPU image

Create a GPU sandbox

Run code on the GPU

Stop the sandbox

Choose GPUs and resources

Use the REST API

Storage and interruptions

Troubleshooting

​Before you start

​Build a GPU image

​Create a GPU sandbox

​Run code on the GPU

​Stop the sandbox

​Choose GPUs and resources

​Use the REST API

​Storage and interruptions

​Troubleshooting

Before you start

Build a GPU image

Create a GPU sandbox

Run code on the GPU

Stop the sandbox

Choose GPUs and resources

Use the REST API

Storage and interruptions

Troubleshooting