# Run a GPU notebook

Source: https://docs.oiy.ai/docs/gpu-notebook

Open the PyTorch starter, verify CUDA, save a result, and resume your workspace.



Use the built-in PyTorch template to run a small calculation on a GPU. This guide uses JupyterLab and the SDK already included in Oiy's catalog runtime image. You need a verified account, sufficient balance, an available GPU placement, and browser access enabled for your deployment.

## 1. Launch the PyTorch starter [#1-launch-the-pytorch-starter]

In the console, choose **Templates → PyTorch**. Keep its catalog image, Jupyter command, and HTTP port `8888`. Select a GPU model and matching memory profile that the live console can place and price; `gpuCount` must be at least `1` for this guide.

Review CPU, system memory, workspace size and price before creating the service. Save durable work in `/workspace`. Choose independent storage if your files must outlive this service. The default idle timeout is fifteen minutes.

Create the service, then inspect its state and logs. `running` means the runtime is up; Jupyter may still be initializing. [GPU profiles](/docs/compute) describe accepted configurations, while the console determines current availability.

## 2. Open JupyterLab [#2-open-jupyterlab]

Select **Open in browser** in the service details. This creates an Oiy browser session for your account. If startup is still in progress, wait for the application and inspect logs if it keeps failing.

Jupyter has its **own application login**, separate from Oiy's browser session. For the default starter, read the generated Jupyter token from the service's startup logs and paste it into Jupyter's login form. The localhost URL printed beside that token points inside the container: use the Oiy browser launch URL to reach the application.

If you configured a Jupyter token or password yourself, use that credential instead. Keep tokens and launch URLs private; do not substitute your Oiy API key or disable Jupyter authentication to bypass this step. See [Jupyter's authentication documentation](https://jupyter-server.readthedocs.io/en/latest/operators/security.html).

Create a Python notebook and save it under `/workspace`, for example `/workspace/first-gpu.ipynb`.

## 3. Confirm the GPU is visible [#3-confirm-the-gpu-is-visible]

Run this cell in the notebook:

```python
import torch

print("PyTorch:", torch.__version__)
print("CUDA runtime:", torch.version.cuda)
if not torch.cuda.is_available():
    raise RuntimeError("No CUDA device is available to this notebook kernel.")

print("Visible devices:", torch.cuda.device_count())
print("Device 0:", torch.cuda.get_device_name(0))
```

The device name and count depend on your allocation. This checks CUDA visibility; it is not a performance benchmark or proof that a requested model was substituted. If it fails, check that the service has a GPU, the selected profile is supported in its placement, and the kernel uses the catalog image's Python environment. Avoid installing a different CUDA stack before checking the service configuration. [PyTorch CUDA availability reference](https://docs.pytorch.org/docs/2.10/generated/torch.cuda.is_available.html).

## 4. Compute and save a result [#4-compute-and-save-a-result]

This cell performs matrix multiplication on the first visible GPU and saves the result to a new file in the persistent workspace:

```python
from pathlib import Path
from uuid import uuid4
from oiy_ai import Client

with Client().task(name="First GPU calculation"):
    values = torch.tensor([[1.0, 2.0], [3.0, 4.0]], device="cuda:0")
    result = values @ values
    torch.cuda.synchronize()

    output = Path("/workspace") / f"gpu-result-{uuid4().hex[:8]}.pt"
    torch.save(result.cpu(), output)

print("Result:", result.cpu().tolist())
print("Saved:", output)
```

The expected result is `[[7.0, 10.0], [15.0, 22.0]]`. Note the saved filename for the resume step.

The SDK task context registers activity before the calculation and releases it on exit. It uses the managed instance's injected service-scoped credentials; a personal API key is not needed in this notebook. If registration fails, the calculation does not start. Check the service's runtime/deployment configuration rather than printing its environment. For longer work, wrap your actual training or inference task in the same context. [Task protection](/docs/services/sleep).

## 5. Pause and resume [#5-pause-and-resume]

Save the notebook and wait for your task to finish. Close notebook tabs when finished: a live kernel WebSocket connection can keep the service active. For explicit control, pause the service in the console and wait for `sleeping` with no allocation. Compute charges stop after confirmed release; the retained workspace remains billable.

Wake the service when needed, wait for Jupyter to initialize, then use **Open in browser** again. Jupyter may request a fresh login token. Open the saved notebook, but do not expect its previous kernel variables or GPU memory to survive.

Load the exact result file from step 4 in a fresh cell, replacing the filename below:

```python
import torch

saved = torch.load(
    "/workspace/gpu-result-YOUR_SAVED_ID.pt",
    map_location="cpu",
    weights_only=True,
)
print(saved.tolist())
```

You should see the same matrix. Load only files you created or trust. Saved files persist across sleep; running processes and unsaved kernel state do not. Back up important work before deleting a service or volume. [Storage lifecycle](/docs/storage) · [Restart behavior](/docs/services/restart).

## Common issues [#common-issues]

| Symptom                                   | Check                                                                                                                              |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| No **Open in browser** control            | Browser access must be enabled for the deployment; inspect the service port and account eligibility.                               |
| Jupyter asks for a token after Oiy launch | Complete the separate Jupyter login with its application token.                                                                    |
| CUDA is unavailable                       | GPU count, placement/profile availability, runtime readiness, and the notebook's Python kernel.                                    |
| `No module named oiy_ai`                  | Use the current catalog runtime image or follow the source-distributed [SDK setup](/docs/developers/python).                       |
| Automatic sleep does not occur            | Open browser connections, running protected tasks, and stale activity records. Confirm tasks ended before releasing stale records. |