How to use the CUDA inside a smolvm machine agent skill

What the gpu-cuda skill makes the agent do

The skill teaches the agent to start a smolvm machine with the --cuda option. That option forwards CUDA driver calls from the guest to the host's NVIDIA GPU over vsock. The guest gets no NVIDIA driver and no /dev/nvidia* device; a compatibility libcuda.so.1 is injected at /opt/smolvm-cuda inside the guest.

The skill also checks that real GPU work happened, instead of trusting a zero exit code. Because the API is remoted, a CUDA program can exit zero without ever touching the device. The skill includes a read-only preflight check, a probe script, and a cleanup routine for the large CUDA images and machines it creates.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it into one of two places. For a personal setup, use ~/.claude/skills/. For a single project, use the .claude/skills/ folder inside that project.

In the Claude apps you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project: unzip into .claude/skills/ in your project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Check your requirements before you start

The skill was verified on smolvm v1.14.6 and v1.22.2. For real GPU runs you need an NVIDIA GPU with a working host NVIDIA driver, read/write access to /dev/kvm for your user, and Bash and Python for the scripts. The probe uses the python:3.12-slim image or another glibc image, which must be pulled, so internet access is needed if it is not already cached.

The host needs the NVIDIA driver (libcuda.so.1 and a loaded kernel module). No CUDA toolkit, container toolkit, device plugin or root access is required for the Driver API path.

• smolvm installed
• NVIDIA GPU with a working host driver for real runs
• Read/write access to /dev/kvm
• Bash and Python available
• Internet access to pull images if not cached

Run the preflight check first

Ask the agent whether CUDA can run on this machine, or run the preflight yourself. It is read-only: it starts no VM and touches no NVIDIA state. It reports the GPU and driver version, whether your user can open /dev/kvm, and the host's own libcuda count.

If the preflight reports gpu_present=no, stop there. On a host with no NVIDIA GPU, the probe can start a VM, reach a CPU emulation device and pass, which looks like a yes but is not a GPU.

Run the CUDA probe and read the result

The probe mounts the scripts folder into the guest, runs cuda-probe.py under --cuda, and checks two values. A real GPU run ends with device_named=ok, data_roundtrip=ok, device_kind=gpu and result=cuda_ok. The line that proves bytes reached the device is roundtrip first 16 bytes match: True.

If the device name is the smolvm CPU emulation device, the probe reports device_kind=cpu_emulation and result=cpu_emulation_not_gpu instead of passing.

• Default image: python:3.12-slim
• Other glibc images can be passed as an argument

Clean up images and machines

CUDA images are large, so the skill ends with a cleanup step. cleanup.sh waits up to 20 seconds for ephemeral machines to retire. Any persistent --cuda machine you kept must be pruned by name. Probe runs are ephemeral and leave nothing to prune.

The --cuda option changes nothing on the host. The shim is injected inside the guest only, and cleanup deletes only names recorded under the smolskill- prefix.