Skip to main content
Everything the installer does, explained. This page walks through the full setup process — what each step does, what to expect, and how to verify it worked.
The installer deploys a single-node secure environment on one machine — a local Kubernetes cluster on that host: native k3s on Linux, k3s in a small VM of Apple’s container runtime on a Mac, and k3s in tracebloc’s WSL distro on Windows. For multi-node or production deployments, see the EKS deployment guide.

​
Requirements

On Linux the installer sets up native k3s, with no Docker. What that needs, administrator rights and hosts included, is in Linux prerequisites. On a Mac the installer sets up k3s in Apple’s container runtime, with no Docker and no administrator rights. What that needs, the node’s memory and the Local Network prompt included, is in Mac prerequisites. On Windows the installer sets up k3s in tracebloc’s own WSL distro, with no Docker. What that needs, the one administrator step included, is in Windows prerequisites. On a machine an older installer set up on k3d, moving to k3s is a reinstall. The Linux, Mac and Windows prerequisites each say what the installer does on such a machine. The installer runs on any modern machine (one host per secure environment) and checks these before it starts. Below the minimum it stops on Linux with a clear message; on a Mac and on Windows it handles the VM’s memory as described below the table. “To run” keeps a secure environment online; training on the same machine needs the headroom — even the smallest experiment (4 GiB) only fits beside the platform’s own services in about 10 GB of memory. On a Mac the node is a VM that holds part of the Mac’s memory, and on Windows the platform runs in WSL’s VM.
  • A Mac: the installer sizes the node from the Mac’s memory and stops before it creates the node if an experiment would not fit beside the platform; see Mac prerequisites.
  • Windows: the platform runs in tracebloc’s WSL distro, so WSL’s VM is its budget. The installer warns below 8 GB in that VM, because a smaller one cannot fit one experiment beside the platform; 10 GB fits the smallest experiment, and 16 GB is recommended. Set memory= under [wsl2] in %UserProfile%\.wslconfig, then run wsl --shutdown.
Admin rights on a Mac: none. Apple’s container runtime installs into your own user folder; see Mac prerequisites. Admin rights on Linux (native k3s): k3s runs as root, so the installer needs them once, or an administrator prepares the machine for you; see Linux prerequisites. Supported platforms: macOS 26 or later (Apple silicon) · Linux (x86_64 & arm64) · Windows 11 (x86_64) GPU (optional): two kinds of GPU train. An NVIDIA GPU of the Turing generation or newer needs NVIDIA driver 580 or newer and an x86_64 machine running Linux or Windows. The GPU of a Mac with Apple silicon needs the current update of its macOS and 16 GB of memory or more. See GPU support for supported GPUs, drivers and platforms, and what isn’t supported. Outbound access needed: The installer pulls container images, the install scripts, and the Helm chart, then connects to the tracebloc platform. The host list, split into install-time and run-time, is on Security & data handling — use it as the single source when you write the firewall rules, since a partial allowlist fails in ways that read like a broken image rather than a blocked host.
Storage must be on a local disk. The data directory (TRACEBLOC_HOST_DATA_DIR, default ~/.tracebloc; the older HOST_DATA_DIR still works) holds the secure environment’s database, which corrupts on network filesystems — the installer fails fast if it is on NFS/CIFS/SMB. To keep large datasets on a network mount, set TRACEBLOC_HOST_DATASET_DIR to it together with TRACEBLOC_STORAGE_MODE=hostpath (with the default node-local storage the installer stops): only the dataset volume moves there, while the database stays local. See Configuration.

​
GPU support

A GPU is optional: every secure environment can train on CPU. Two kinds of GPU train:
  • an NVIDIA GPU of the Turing generation or newer, with NVIDIA driver 580 or newer, on an x86_64 (amd64) machine running Linux or Windows;
  • the GPU of a Mac with Apple silicon, on the current update of its macOS and with 16 GB of memory or more (see Apple GPU).
Anything else trains on CPU.

​
At a glance

​
NVIDIA GPU generations

The training images carry kernels for the generations below. The list is the architecture set of the PyTorch build the images ship, torch==2.14.1 from the cu130 wheel index, as of 2026-10-18. The generation decides support, not the product line: a consumer GeForce card trains the same way as a data-centre card of the same generation. What differs is memory (see GPU memory). Grace Hopper (GH200) and Grace Blackwell (GB200) systems have a supported GPU but an arm64 CPU. The GPU training images are built for x86_64 only, so these machines train on CPU. From the installer release after v1.9.200, the installer leaves an NVIDIA GPU on an arm64 machine out: it installs no driver, container toolkit or device plugin, installs CPU-only and prints why. Re-running it on an arm64 machine an older installer set up with the GPU, on Linux or Windows, switches that machine to CPU. The secure environment’s page in the web app then shows that the GPU isn’t supported. Older GPUs install CPU-only. A card older than Turing (compute capability below 7.5, for example GTX 10xx, GT 710, V100, P100) has no kernels in the training images. The installer leaves the GPU out, installs the secure environment CPU-only and prints why. The secure environment’s page in the web app then shows that the GPU isn’t supported and that training runs on CPU.

​
NVIDIA driver and CUDA

The training images bring their own CUDA libraries: PyTorch 2.14.1 built for CUDA 13.0, with the CUDA 13.0 runtime, cuDNN 9 and NCCL from PyTorch’s own packages. The host only needs the NVIDIA driver. Don’t install the CUDA toolkit or cuDNN on the host for tracebloc. A driver runs these images when it supports CUDA 13: the R580 driver series and newer, on Linux and on Windows (NVIDIA’s CUDA Toolkit release notes). An older driver can’t run them, so the installer has one floor, 580, and no range in which it warns and keeps the GPU. The installer reads the driver version from nvidia-smi before it sets up the GPU:

​
Platforms

On Linux, the installer also installs the NVIDIA Container Toolkit and the Kubernetes device plugin. After it installs a driver, reboot and re-run the installer. For the Kubernetes settings, see Configuration.
AMD GPUs can’t train today. The training images are built for CUDA, and there are no ROCm images. From the installer release after v1.9.200, the installer leaves an AMD GPU out on every platform: it installs no ROCm and no device plugin, installs the secure environment CPU-only and prints why. Re-run the installer on a machine set up by an older installer, and it switches the secure environment to CPU; ROCm stays installed, and you can remove it yourself. With an older installer, run tracebloc resources set --gpus 0 to train on CPU.
On a Mac, the cluster runs in a Linux VM, and a Linux VM gets no GPU. GPU training on a Mac therefore runs beside the VM, on the Mac itself; see Apple GPU.

​
Apple GPU

A Mac with Apple silicon trains on its GPU. The installer sets up the tracebloc runner, part of the tracebloc CLI, beside the k3s node. The runner joins your cluster as a second node, apple-gpu, which only GPU training is sent to. It runs each GPU training as a process on the Mac rather than in the VM, inside a macOS sandbox of its own, with PyTorch on Apple’s GPU (the mps device, through Metal). The engine it runs is a signed build tracebloc publishes with each release, which the runner downloads and checks before it uses it: about 460 MB to download and about 1.7 GB on disk. The GPU is on by default on a Mac that meets all of these:
  • Apple silicon (M1 or later) and macOS 26 or later, on its current update. Once Apple has posted a newer update of the same macOS for 7 days, the Mac trains on its CPU until you install it. A beta of the next macOS gets no GPU, and neither does macOS in a virtual machine.
  • 16 GB of memory or more. A GPU training may use at most half the Mac’s memory, GPU memory included, and always leaves the VM and 8 GB for macOS and you. On a 16 or 24 GB Mac, where a GPU training beside a CPU training would get less than 8 GB, the Mac trains one experiment at a time, on its CPU or its GPU; the other waits. An 8 GB Mac trains on its CPU.
  • A GPU test. When the runner starts, and each time you turn the GPU on, it runs a small Metal program on the GPU and takes GPU trainings only when the program gives the right answer.
  • Network access to gdmf.apple.com, Apple’s public list of macOS releases, and ghcr.io, for the GPU engine. When the list cannot be read, the last answer holds for 7 days; after that the GPU stays off until the list can be read again.
What the requirements are, and the reason a Mac names when it trains on its CPU, are in Mac prerequisites. Limits. They protect the Mac you work on:
  • One GPU training at a time by default. tracebloc resources set --gpu-jobs lets more share the GPU, splitting its memory between them; --gpu-memory lowers what each may use, and never raises it. tracebloc resources set --gpus 0 turns the GPU off, and --gpus 1 turns it back on.
  • Mains power. A GPU training starts only on mains power and out of Low Power Mode. It pauses on battery, and ends after 30 minutes on battery or below 30 % charge.
  • Heat and time. No new GPU training starts while macOS reports its thermal state as fair or worse; a running one pauses at serious and ends at critical. A GPU training ends after 24 hours, or after 10 minutes without progress.
  • Models that don’t fit the GPU. Where a batch does not fit the GPU training’s memory, the engine splits it into micro-batches and adds up their gradients, so the effective batch size stays the same. A GPU training that still runs out of memory early restarts once with twice as many micro-batches, and then moves to the CPU. A model the GPU can’t train correctly, or that the engine trains on the CPU by policy, moves to the CPU as well. Every one of these still trains: only the device changes.
  • PyTorch only, as on NVIDIA: scikit-learn, lifelines and scikit-survival models train on the CPU.

​
Multi-GPU

Each experiment uses one GPU by default. On a machine with several GPUs, give each experiment more of them:
The setting applies from the next experiment. A PyTorch experiment spreads across those GPUs with DistributedDataParallel. Test and inference runs use one GPU. Not supported:
  • One experiment across several machines. An experiment’s GPUs all come from one machine (one Kubernetes node).
  • MIG partitions. Training pods request whole GPUs (nvidia.com/gpu), never a MIG profile.

​
GPU memory

There is no minimum GPU memory: what fits depends on the model and its batch size. When a PyTorch run hits a CUDA out-of-memory error, it retries the failing batch before it gives up: first with a paged optimizer, then with half-size micro-batches (the effective batch size stays the same), then with activation checkpointing. If the batch still doesn’t fit, the run fails with the out-of-memory error. Use a smaller model or batch size, or a GPU with more memory.

​
Check your machine

This prints each GPU’s name, driver version, compute capability and memory. Compare them with the tables above. On a Mac, tracebloc resources shows whether the Apple GPU takes trainings and, when it doesn’t, the reason.
  • At the end of the install, the installer prints the secure environment’s mode: GPU or CPU. If it installs CPU-only on a GPU machine, it prints why.
  • tracebloc resources shows how many GPUs the machine has and how many each experiment may use.
  • tracebloc doctor warns when experiments ask for a GPU that no node can give them.
  • If a GPU can’t train, the experiment fails at start with a message such as GPU not usable: <GPU> (compute capability <X.Y>, driver <version>); supported: Turing (7.5) or newer.

​
1. Create an Account

Sign up at ai.tracebloc.io. Free to get started — no credit card required.

​
2. Deploy

One command sets up your entire secure environment on any machine — macOS, Linux, or Windows. The installer is idempotent: it detects what’s already installed and skips it, so it’s safe to re-run at any time.
What it changes on Linux: native k3s, Helm, the tracebloc CLI and ~/.tracebloc, and kubectl’s current context becomes k3s-tracebloc (the full list is in Linux prerequisites). What it changes on a Mac: Apple’s container runtime and its node, with no Docker, and kubectl’s current context becomes k3s-tracebloc (the full list is in Mac prerequisites). What it changes on Windows: the tracebloc WSL distro, with k3s inside it, and no Docker (the full list is in Windows prerequisites).

​
What the Installer Does

The installer runs six labelled steps: a) Checking your machine Checks CPU, memory, disk and network against the requirements above, and detects GPU hardware (falls back to CPU mode if none). b) Installing what tracebloc needs Installs whatever is missing. On Linux that is k3s (a pinned release whose digest it checks), helm and the tracebloc CLI, with administrator rights once. On a Mac it is Apple’s container runtime from its signed package, the kernel and k3s image its node boots, kubectl, helm and the tracebloc CLI, with no administrator rights. On Windows it imports tracebloc’s WSL distro, as you, and installs inside it what native k3s installs on Linux; it installs no Docker Desktop, no winget packages and no k3d. c) Creating your secure environment Provisions a lightweight local Kubernetes cluster: native k3s as a system service on Linux, k3s in a small VM of Apple’s container runtime on a Mac, and k3s in tracebloc’s WSL distro on Windows. First run takes 1–2 minutes to download components. d) Registering this machine Signs you in and registers this machine on your account:
  1. The installer prints a link and a short code. Open the link on any device (this computer or your phone), sign in the way you already do — password, Google, or GitHub — and approve the code. The code is valid for 10 minutes; if it lapses, press Enter for a fresh one.
  2. It asks you to name your secure environment — the name shown on your dashboard. Set TRACEBLOC_CLIENT_NAME before the install command to skip the prompt. The location comes from your system timezone; set TRACEBLOC_CLIENT_LOCATION to a country code such as DE to choose it.
e) Installing tracebloc Installs the tracebloc Helm chart into the cluster with the credential minted in step d. You never see or type it. f) Connecting to the tracebloc network Waits until the services are up and connected, then prints a summary with your secure environment’s name, version and mode (CPU or GPU), and what to do next. Install logs are kept in ~/.tracebloc/ if you need to debug anything.
Browser sign-in needs someone at a terminal. For an unattended install (CI, device management), first create the secure environment on a machine where you’re signed in to the tracebloc CLI (tracebloc login):
This creates the secure environment and writes its Client ID, password and namespace to tb.env. The password is never shown on screen, and on macOS and Linux only you can read the file (mode 0600). Run it on a machine whose kubeconfig reaches no Kubernetes cluster, so not on one where tracebloc is installed: with a cluster in reach, client create ties the secure environment to that cluster, or reuses the one already running there.Copy tb.env to the target machine, load it, and run the install command in the same terminal:
The installer skips browser sign-in and connects with those credentials. If it stops and asks you to restart, load tb.env again in the new terminal before you run the install command again.Run client create once per target machine: with no cluster in reach, running it again creates another secure environment instead of finding this one. After the install, delete tb.env. Don’t commit it or share it.

​
Status reference

Your secure environment moves through these states on your dashboard:
A one-liner install keeps its services current through the hourly auto-upgrade, and tracebloc upgrade brings the CLI to the latest release. To upgrade the services right away, see Operations → Upgrade, which covers the Helm route (helm upgrade <namespace> tracebloc/client -n <namespace> --reset-then-reuse-values; --reset-then-reuse-values keeps the values the installer applied).

​
GPU Support

The installer detects your GPU and configures the cluster:
  • Linux x86_64 (NVIDIA) — drivers, container toolkit, and Kubernetes device plugin are installed automatically. A reboot may be required after driver installation. AMD GPUs, and NVIDIA GPUs on arm64, install CPU-only.
  • macOS — the installer sets up the tracebloc runner, which trains on the Apple GPU of a Mac with the current update of its macOS and 16 GB of memory or more. See Apple GPU.
  • Windows — pre-install NVIDIA drivers before running the installer. The installer detects them via nvidia-smi.
See Configuration > GPU for detailed platform-specific behavior.

​
3. Verify

After the installer finishes, open a new terminal (so the tracebloc command is on your PATH) and run:
tracebloc client status --wait waits until it’s online. Then open ai.tracebloc.io and check that your secure environment shows Online. This confirms it has a secure connection to the tracebloc platform.
Stuck on Offline? Run tracebloc doctor, then see the Troubleshooting page.

​
What’s Next

Your secure environment is running. Here’s where to go from here: Data owners: Ingest your dataset, then create a use case — pick from prepared datasets, define evaluation metrics, and invite peers to submit models. Data scientists: Join a use case — connect to a use case, train models on real data, and submit results. Advanced configuration: Configuration — customize installer options, manage the cluster, configure GPU settings, or deploy manually with Helm.