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, with no Docker.

Linux

On Linux the installer sets up native k3s: Kubernetes runs on the machine itself as a system service, with no Docker and no k3d. Inside WSL the installer runs only in tracebloc’s own distro, which the Windows installer sets up: in any other distro it stops and says so. 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;
  • only on a machine with AppArmor enabled and kernel.apparmor_restrict_unprivileged_unconfined=1 (the Ubuntu 25.10 and 26.04 default), an AppArmor profile named runc for the runc k3s ships, so that k3s’s containers can signal themselves (without it, MySQL’s first start never ends):
    • the profile, /etc/tracebloc/apparmor-k3s-runc;
    • a k3s drop-in that puts it back in the kernel before every k3s start, /etc/systemd/system/k3s.service.d/tracebloc-apparmor-runc.conf;
    • on a machine with apt, an apt hook that puts it back in the kernel after every package update, /etc/apt/apt.conf.d/99tracebloc-apparmor-runc.
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. A machine that runs tracebloc on k3d. The installer no longer sets up k3d on Linux outside WSL, and it refuses TRACEBLOC_SUBSTRATE=k3d there. k3d is no longer supported: a machine already on k3d keeps running as it is until you move it. Moving a k3d machine to native k3s. The installer does not move it. Run on a machine that runs tracebloc on k3d, it stops before it changes anything, and it asks nothing. It reads what says the machine is on k3d: the install record or its root copy, or, for an install older than the record, the kubeconfig context k3d writes; with none of them, the containers Docker still has for k3d’s cluster. On screen it says one line, then the way out, tracebloc delete:
Moving is a reinstall: tracebloc delete deletes that secure environment and its data, and the machine comes back as a new secure environment. The install log says what said k3d, and the install record and the k3d-tracebloc entries in your kubeconfig to delete if they are still there after the delete. In prepare-host, it names the user it sets the machine up for, here alice, who deletes:
Deleting the file and the context’s entries by hand does not get the installer past a k3d cluster that is still there: while Docker lists that cluster’s containers, stopped ones too, it stops the same way. With no file saying k3d, k3d installed and Docker not answering, it cannot tell, and stops: start Docker, then run it again. When Docker is gone. If the install record or the k3d-tracebloc kubeconfig context says k3d, and Docker cannot be used (there is no docker command, or it fails outright), the old secure environment is out of the installer’s reach, and it does not stop. It removes the k3d-tracebloc context from your kubeconfig and no other (a k3d cluster of your own keeps its context, and your current context stays unless it was k3d-tracebloc), moves the install record aside to install-record.json.k3d-<timestamp> (kept, not deleted), says so in two lines, and continues the install. It touches nothing on the cluster side; the old secure environment shows as Offline on tracebloc. With Docker usable, or a docker that does not answer in time (it may be a live cluster behind a stuck Docker), the stop and its way out above stay: there is no moving a k3d machine. 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 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. It is the one runtime the installer sets up on a Mac: any other TRACEBLOC_SUBSTRATE stops it before it changes anything. 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-runti… (Apple’s container-runtime-linux; the dialog shows the shortened name) 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. A Mac that runs tracebloc on k3d. k3d is no longer supported. The installer does not move such a Mac, and never sets up the node beside it. Run on such a Mac, it stops before it changes anything, and it asks nothing. It reads what says the Mac is on k3d (the install record, or, for an install older than the record, the kubeconfig context k3d writes; with neither, the containers Docker still has for k3d’s cluster), then prints the way out:
With Docker gone (no docker command, or one that fails outright), a Mac whose install record or k3d-tracebloc kubeconfig context says k3d is cleared the same way as on Linux: its k3d-tracebloc context is removed, the record is moved aside, one line says so, and the install continues. With Docker usable, or one that does not answer in time, the stop above stays. A Mac the table above rules out (an Intel Mac, or an older macOS) is stopped by that first. Until the Mac moves, neither the installer nor tracebloc upgrade updates its secure environment. 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.

GPU training on a Mac

A Mac that meets the table below also trains on its GPU. Beside the node, the installer sets up the tracebloc runner, part of the tracebloc CLI:
  • a second login item, io.tracebloc.runner, that keeps the runner going beside io.tracebloc.node;
  • a second Kubernetes node, apple-gpu, which the runner registers in your cluster. Only GPU training is sent to it, and it advertises the GPU as tracebloc.io/apple-gpu. kubectl --context k3s-tracebloc get nodes lists it beside the k3s node.
The runner 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 the GPU (mps). A training the GPU cannot take trains on the CPU instead, in the VM, so a Mac without its GPU still takes every training. tracebloc resources set --gpus 0 turns the GPU off. --gpu-jobs sets how many GPU trainings may share it at once (one by default), and they split the memory a GPU training may use. --gpu-memory lowers what each GPU training may use; it never raises it. A GPU training starts only on mains power; the other limits are under Apple GPU. Why a Mac trains on its CPU. When the GPU takes no trainings, the runner names one reason. tracebloc resources shows it, and the dashboard says it in words. A GPU training’s log is on the Mac, not in its pod: kubectl logs can’t read it. Where it is, is in Troubleshooting.

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. This installer no longer sets up tracebloc on Docker Desktop with k3d, nor moves a machine off it. On such a machine it stops before WSL is touched, names the secure environment it found, and changes nothing on this machine. It finds one from the files that install left, or, with none of them, from the containers Docker still has for its cluster; with no file saying k3d, k3d installed and Docker not answering, it cannot tell, and stops. When the install record or the k3d-tracebloc kubeconfig context says k3d and Docker cannot be used (no docker command, or one that fails outright), it does not stop: it removes the k3d-tracebloc context from the kubeconfig and no other, moves the install record and install-state.json aside, each to <its name>.k3d-<timestamp>, says so in two lines and continues; the old secure environment shows as Offline on tracebloc. With an install record that says k3s and the k3d-tracebloc context still in your kubeconfig, it stops whatever Docker says, and names that context’s entries to delete. With Docker usable, or one that does not answer in time, it stops, and to move the machine, delete that secure environment with tracebloc delete. Then delete %USERPROFILE%\.tracebloc\install-state.json and the k3d-tracebloc entries from your kubeconfig if they are still there, and run this installer again. Moving 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. 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.

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. On a Mac, the Apple GPU trains through the tracebloc runner (see GPU training on a Mac). AMD and Intel 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 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: they then live under the data directory (TRACEBLOC_HOST_DATA_DIR, default ~/.tracebloc). 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. The local cluster is always one node, on this machine.
  • For multi-node high availability, use bare-metal or a managed cloud instead.