Skip to main content
When to pick it — A single machine you own: a laptop to try things, or an on-prem server you run in production. The installer brings up a self-contained Kubernetes cluster, so you don’t need a cluster of your own. Which one a machine gets, and what it needs, is under Prerequisites below.

​
Prerequisites

A tracebloc account. The installer signs you in through your browser and registers this machine for you. No Docker or Kubernetes knowledge is needed: the installer sets up the cluster for you, and wherever it sets up k3d, it sets up Docker as well.

​
Linux

On a new Linux machine the installer sets up native k3s: Kubernetes runs on the machine itself as a system service, with no Docker and no k3d. A new machine is one outside WSL with no tracebloc install, no k3d, and no k3d cluster in Docker. Every other Linux machine keeps k3d, and so does WSL. When it keeps k3d, the installer says why in one line. What the installer puts on the machine:
  • k3s, a pinned release downloaded from GitHub, whose digest the installer checks;
  • Helm;
  • the firewall tool k3s needs (nftables);
  • the tracebloc CLI;
  • on an NVIDIA machine, the driver and the NVIDIA container toolkit.
kubectl comes with k3s. The installer installs no Docker and no k3d. k3s lives in /usr/local/bin/k3s, /etc/rancher/k3s and /var/lib/rancher/k3s, and runs as the k3s service. tracebloc delete removes them. An NVIDIA GPU. GPU training needs NVIDIA driver R580 or newer (CUDA 13). With an older driver the installer sets the machine up in CPU mode. To use the GPU, update the driver, reboot, and run the installer again. On Ubuntu, this command updates it:
Without administrator rights. An administrator runs this once, with your user name in place of <user>:
This sets up k3s and adds you to the tracebloc group. Log out and back in, then run the installer with no sudo. To list the commands it would run as root, without running any, add --print after prepare-host. Keeping k3d. To install on k3d instead, set TRACEBLOC_SUBSTRATE=k3d; the installer then sets up Docker as well. A machine that already runs tracebloc on k3d stays on k3d through every upgrade. Moving a k3d machine to native k3s. Re-run the installer with TRACEBLOC_SUBSTRATE=k3s. This is a reinstall:
  • the machine’s secure environment and its data are deleted;
  • its datasets must be ingested again;
  • it comes back as a new secure environment.
Your use cases and models stay on tracebloc. To confirm, the installer asks you to type the secure environment’s name, or reads it from TRACEBLOC_REINSTALL_CONSENT=<name>. Hosts. Before a run changes anything, the installer checks each host that run needs. The last column says which runs need it.

​
macOS

On a new Mac with Apple silicon and macOS 26 or later, the installer sets up k3s in Apple’s container runtime. Kubernetes runs in a small Linux VM that Apple’s runtime starts from your own user folder, with no Docker, no k3d and no administrator rights. A new Mac is one with no tracebloc install, no k3d, and no k3d cluster in Docker; a Docker that is installed but not running counts as none, since every k3d install leaves k3d itself behind. Every other Mac keeps k3d, which the local deployment guide covers, and the installer says why in one line. To keep k3d on a new Mac, set TRACEBLOC_SUBSTRATE=k3d. What the installer puts on the Mac:
  • Apple’s container runtime, from its signed package, in ~/Library/Application Support/tracebloc/container;
  • the Linux kernel the node boots (ghcr.io/tracebloc/apple-container-kernel) and the k3s node image (rancher/k3s, by digest);
  • a login item, io.tracebloc.node, that keeps the node running and brings it back when you log in again;
  • a folder for your job data, ~/.tracebloc/job-data: the datasets, logs and resume points training uses. Only you can open it.
  • kubectl and Helm in ~/.local/bin;
  • the tracebloc CLI.
The installer installs no Docker, no colima, no Homebrew and no k3d. tracebloc delete removes the node, its login item, the runtime and your job data. The one prompt. When the node first starts, macOS asks whether container-runtime-linux may find devices on your local network. It is part of Apple’s runtime, and it makes the cluster’s API reachable from this Mac only. Click Allow. The installer waits up to 2 minutes for your answer. Without it, the installer stops and says where to allow it: System Settings › Privacy & Security › Local Network. Hosts. The installer checks each of these before it starts. The first five rows are always needed. The rest are needed only until Apple’s runtime or Helm is installed.

​
Windows

On Windows, the installer sets up k3s in tracebloc’s own WSL distro. This is native k3s, as on Linux, inside a WSL 2 distro named tracebloc that belongs to the signed-in user, with no Docker Desktop and no k3d. It is the one runtime the installer sets up on Windows: any other TRACEBLOC_SUBSTRATE stops it before it changes anything. The one administrator step. When WSL 2.5 or later is missing, the installer stops and says: “Ask your IT team to run this once in an administrator PowerShell, then restart Windows if it asks:”
If you are an administrator yourself, Windows asks you once to allow it, and that command is the only thing the installer runs elevated. Where wsl --install cannot run, for example from a deployment tool running as SYSTEM, IT can instead turn on the Windows features Microsoft-Windows-Subsystem-Linux and VirtualMachinePlatform, install WSL’s own package, and restart. If Windows asks for a restart, the installer says: “Restart Windows, then run the same install command again: it continues from here.” What the installer puts on the machine:
  • the tracebloc WSL distro in %LOCALAPPDATA%\tracebloc\wsl, the signed-in user’s own folder, imported from tracebloc’s image on ghcr.io, a download of about 126 MB: Ubuntu 24.04.5 with ca-certificates, curl, dbus, nftables, systemd and systemd-sysv, and k3s;
  • inside the distro, what native k3s puts on a Linux machine, as the Linux section above lists it;
  • the tracebloc CLI, for the signed-in user only, in %LOCALAPPDATA%\Programs\tracebloc unless TRACEBLOC_INSTALL_PREFIX names another folder;
  • the install record %USERPROFILE%\.tracebloc\install-record.json, where tracebloc delete finds what to remove;
  • the logon task tracebloc-keepalive, the signed-in user’s own, set up without administrator rights. At each sign-in it starts the distro, with no window, and keeps it running.
The installer installs no Docker Desktop, no winget packages and no k3d. tracebloc delete removes the logon task, then the distro, with everything inside it. After a restart. The secure environment runs while you are signed in. After Windows restarts, it starts again when you sign in. A machine that runs tracebloc on k3d. The installer never sets up the distro beside a live k3d cluster. Moving the machine is a reinstall: its secure environment and that environment’s data are deleted, its datasets are ingested again, and it comes back as a new secure environment. Your use cases and models stay on tracebloc. The installer offboards the old environment only after you type its name when asked, or set TRACEBLOC_REINSTALL_CONSENT to it. A k3d cluster that is not tracebloc’s stops the installer, which never removes it. A proxy. Set HTTPS_PROXY, and HTTP_PROXY and NO_PROXY if your network needs them, in Windows’ environment before the install. The installer stops before it sets up the distro if a proxy variable holds a value the cluster could not use. Windows’ own downloads use HTTPS_PROXY. The installer hands these variables into the distro, and k3s gets them there. A proxy that inspects TLS. Its root certificate needs no extra step. The installer copies this computer’s trusted root certificates, the machine’s and the signed-in user’s, into the distro before its first download there. It stops if the distro’s trust bundle does not hold every one, and restarts k3s if it already runs, so k3s reads them too. An NVIDIA GPU. GPU training needs NVIDIA driver R580 or newer (CUDA 13), from NVIDIA’s download page, https://www.nvidia.com/Download/index.aspx. With an older driver the installer sets the machine up in CPU mode. To use the GPU, update the driver, reboot, and run the installer again. Hosts. Windows downloads the installer and the tracebloc CLI from github.com, whose release files come from release-assets.githubusercontent.com, and the distro’s image from ghcr.io. Inside the distro, the installer checks each of these before it starts. The first four rows are always needed. The distro’s image carries k3s, so the k3s release is needed only on a run that upgrades it. Helm is needed until Helm is installed.

​
Every other machine (k3d)

A machine on k3d, inside Docker, needs 2 CPU · 5 GB RAM · 10 GB free disk to run (4 CPU · 16 GB · 50 GB to train on it, with 11–14 GB of memory for Docker).

​
Install

See Quick Start for the full walkthrough, including the inspect-first option.

​
Verify

On My Secure Environment, your secure environment should also read Active now under its name.

​
Environment-specific config

Set these as environment variables before the install command (full list in Configuration):
NVIDIA GPUs are auto-detected on Linux — drivers, container toolkit, and device plugin are installed for you. AMD, Intel and Apple GPUs don’t train; see GPU support for supported GPUs and drivers.

​
Production notes

  • Local is production-capable. Point it at a server rather than a laptop and it’s a real deployment.
  • Where your datasets live. On macOS and Linux, datasets are stored inside the cluster node by default. On native k3s the node is this machine, so they are directories k3s keeps in its storage directory (see Linux). On a new Mac they are in ~/.tracebloc/job-data, a folder on the Mac that only you can open (see macOS). They survive stop/start cycles (see Operations) but are wiped when the cluster is deleted, including by tracebloc delete. To keep them on the host instead, install with TRACEBLOC_STORAGE_MODE=hostpath (the older TB_STORAGE_MODE works until 2026-12-31): they then live under the data directory (TRACEBLOC_HOST_DATA_DIR, default ~/.tracebloc; the older HOST_DATA_DIR works until 2026-12-31). On Windows, tracebloc’s WSL distro keeps them inside its node, on the distro’s own disk, and TRACEBLOC_STORAGE_MODE is not used there.
  • Need more headroom? Re-run the installer on a bigger machine. Extra k3d nodes don’t add capacity: they all share this one machine. Native k3s is always one node.
  • For multi-node high availability, use bare-metal or a managed cloud instead.