Docs/Getting started
Getting started

The tenant environment

By Samuel Seidel · Updated November 12, 2026 · 6 min read

A GPUwerk instance is your own container on a dedicated DGX Spark: not a virtual machine, not bare metal. This page tells you what that means in practice: what you can install, whether Docker and systemd work, what survives a stop or rebuild, how to start services automatically, and how the network reaches your container.

On this page
  1. What you get
  2. What the container is not
  3. Docker and systemd
  4. What persists across a restart
  5. The startup hook
  6. Storage: the shared 1 TB NVMe
  7. Get your files out
  8. Networking
  9. Spark Cluster 2×: the second machine

What you get

Each instance is one dedicated DGX Spark: a GB10 chip with 128 GB of unified memory shared between CPU and GPU, not split across the two. It is an ARM64 (aarch64) machine, so x86-only binaries and images do not run. Your workload runs in a container with that GPU passed straight through, and inside the container you are root. You are not root on the host.

You pick the image when you deploy: DGX OS 7 or Ubuntu 24.04 LTS, both with the CUDA 13.0 toolkit, or on GPUwerk's own Sparks a model preset (vLLM or llama.cpp serving a model) or a tool image (JupyterLab, VS Code in the browser, ComfyUI). You cannot boot your own base image, but you can install anything inside it, and on some machines run your own containers (see Docker and systemd).

The NVIDIA driver comes from the host, and the CUDA userspace comes from the image. Do not install or upgrade a driver yourself: the kernel module lives on the host, outside the container, and a rebuild restores whatever the image ships.

What the container is not

It is not a full Linux host. The kernel and the NVIDIA driver belong to the host, so you cannot load kernel modules, install a driver or reboot the machine; restarting the instance restarts your container. What does not work on any machine:

Start your own services from a shell for a quick test, inside tmux so they survive a disconnect, or from the startup hook so they come back after a restart. On a system container (below) a systemd unit works too.

Docker and systemd

Docker inside the rental is available on some machines only. In November 2026 about half of the Sparks, GPUwerk's own and partners' alike, run the system container and the rest run the plain one. Which you get depends on the machine your instance lands on; you can't pick it yet, and the console does not show it before you deploy.

To check which one you have, run docker info: it answers on a system container and fails on a plain one.

What persists across a restart

/workspace is a separate volume, not part of the container's own filesystem.

ActionUnder /workspaceEverything else (apt packages, system pip installs)
RestartKeptKept
Stop and startKeptKept while the machine is held; see below
RebuildKeptGone: the image is reinstalled fresh
TerminateDeleted for goodDeleted

Stop. A stop keeps the machine reserved for you with the container quiesced and /workspace on the node, so starting again takes seconds. If your credit runs out or your monthly budget is reached, the instance is stopped and its machine released. The workspace stays on that machine for up to 48 hours. Top up and start it again in that time and it picks up where it left off, unless someone else has rented the machine, which deletes it sooner. After 48 hours the instance and its /workspace are deleted for good. Nothing is copied off the machine.

Terminate is the one action that deletes /workspace for good, which is why the console asks you to type the instance name first.

Workspaces are not backed up. GPUwerk keeps no copy of /workspace, not even one to recover from a failed drive. If the drive fails, the workspace is lost. Copy anything you need off the node yourself: Get your files out has scp, rsync and Hugging Face examples.

SSH host keys are also kept in /workspace, under .hostkeys, so your instance's identity stays the same across restarts and you do not get a host-key warning each time.

The startup hook

To start your services automatically after every restart:

  1. Write the script below to /workspace/.gpuwerk-init, with your own commands.
  2. Make it executable: chmod +x /workspace/.gpuwerk-init.
  3. Restart the instance from the console.

It runs as root on every container start (first boot, restart or rebuild). It is launched detached, so a hook that hangs or fails cannot delay SSH. Its output goes to /workspace/.gpuwerk-init.log, not your terminal. The hook needs an image built after September 19, 2026; if your instance is older, a rebuild picks up the new image and keeps /workspace.

#!/bin/sh
# /workspace/.gpuwerk-init: must not block, it runs detached anyway
cd /workspace
nohup llama-server -m my-model.gguf --host 0.0.0.0 --port 8899 \
    >> llama-server.log 2>&1 &
nohup python3 my-service.py >> my-service.log 2>&1 &

Result: after the restart, /workspace/.gpuwerk-init.log has a new timestamp line followed by your script's output, and your services are running. Each run writes its own timestamp line, so you can tell restarts apart.

Storage: the shared 1 TB NVMe

The included storage is 1 TB NVMe shared with the system and model cache, not a slice cut out for you. The host, GPUwerk's container images, staged model weights, your container and /workspace (with any Docker images you pull) all share it.

Networking

Spark Cluster 2×: the second machine

On a Spark Cluster 2× each machine runs its own container, and the two are joined by a ConnectX link on eth1. Use that interface for everything between them: eth0 is private to each machine and the other one cannot reach it. Both containers start with these variables set, in SSH sessions too:

If you start a multi-node job in a shell that does not have them (for example a fresh env -i or a container of your own), set them yourself: without VLLM_HOST_IP a two-machine vLLM picks eth0 and waits for a peer it can never reach.

NextCreate an SSH key and connect Back toAll docs
First top-up: pay $20, get $30 in credit

See the container from the inside.

A dedicated DGX Spark in Czechia or at a partner in Europe, North America or Hong Kong, through the console.

Create account