Skip to main content
A running secure environment in about 10 minutes, with one command. Deploying on a specific environment instead (EKS, AKS, bare-metal, OpenShift)? See Deployment environments.
No Docker or Kubernetes knowledge needed. The installer sets up the whole stack for you. On a new Linux machine that is native k3s, on a new Mac it is k3s in Apple’s container runtime, and on Windows it is k3s in tracebloc’s own WSL distro, all with no Docker at all. Where it sets up k3d instead, it even installs Docker if it’s missing. You just need a machine.

​
Before you start

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.
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.
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.
On a Mac on k3d, use an administrator account. The installer asks for your password once and stops with “Administrator rights required” on a standard account, unless Docker is already installed and running. A new Mac, on Apple’s container runtime, needs no administrator rights. The minimum is enough to keep your secure environment online. Training needs more: even the smallest experiment (4 GiB) only fits beside the platform’s own services in an 11 GB Docker budget. On a Mac on k3d, Docker runs in a VM with its own memory limit, which is often 8 GB by default, and on Windows the platform runs in WSL’s VM. The installer checks it for you:
  • A Mac on k3d: it offers to raise Docker Desktop’s memory for you, which restarts Docker Desktop. If you decline, set it in Docker Desktop → Settings → Resources → Memory.
  • Windows: the platform runs in tracebloc’s WSL distro, so WSL’s VM is its budget. The installer warns below 9 GB in that VM, because a smaller one cannot fit one experiment beside the platform; 11 GB fits the smallest experiment, and 16 GB is recommended. Set memory= under [wsl2] in %UserProfile%\.wslconfig, then run wsl --shutdown.
  • Below 5 GB for Docker, it stops on a Mac on k3d and on Linux with k3d. On native k3s there is no Docker budget: the machine’s own memory counts (see the Linux prerequisites above). On a new Mac the node is a VM that takes its share of the Mac’s memory, and the installer stops before it creates the node if an experiment would not fit beside the platform (see the Mac prerequisites above).
On a Mac on k3d the installer can’t see Docker Desktop’s disk, so check the Disk usage limit under Docker Desktop → Settings → Resources yourself: at least 20 GB, and 50 GB to train.
1

Run the installer

What to expect: about 5 minutes. It checks your machine, installs a local Kubernetes cluster and the tracebloc CLI, then registers this machine with your account. On a new Linux machine the cluster is native k3s, and it asks for your password once (sudo), because k3s runs as root. On a new Mac it is k3s in Apple’s container runtime, with no password: when the node first starts, macOS asks whether container-runtime-linux may find devices on your local network, and you click Allow. On Windows it is k3s in tracebloc’s WSL distro, which it imports as you, with no administrator rights. If WSL 2.5 or later is missing, it stops once and names the one command your IT team runs (see the Windows prerequisites above). Elsewhere it is k3d, and it installs Docker if it’s missing. Safe to re-run anytime.On a Mac on k3d without Docker, the installer opens Docker Desktop for the first time. In the Docker window, approve the privileged-helper prompt (your admin password) and accept the license agreement. The installer then continues by itself.
Every install script is open source. i.sh is a short wrapper that downloads and runs the installer from the latest release, so read that installer instead:
The installer pins itself to its release and cosign-verifies every script it fetches before running it. All files are on the latest release page.
2

Sign in and name this machine

Partway through, 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, the installer offers a fresh one.Then it asks you to name your secure environment — the name shown on your dashboard. To skip the prompt, set TRACEBLOC_CLIENT_NAME before the install command. The installer sets the secure environment’s location from your system timezone; to choose it, set TRACEBLOC_CLIENT_LOCATION to a country code such as DE.The installer registers this machine on your account itself. For an install with no one at a terminal (CI, device management), see unattended install.
3

Verify it's connected

Open a new terminal (so the tracebloc command is on your PATH), then run:
tracebloc client status --wait waits until it’s online. On My Secure Environment, your secure environment then reads Active now under its name.
What changed on your machine — On a new Linux machine: native k3s, Helm, the tracebloc CLI and ~/.tracebloc (the full list is in the Linux prerequisites above), and kubectl’s current context becomes k3s-tracebloc. On a new Mac: Apple’s container runtime and the node it runs, the login item io.tracebloc.node that brings the node back when you log in, kubectl and helm in ~/.local/bin, the tracebloc CLI and ~/.tracebloc (the full list is in the Mac prerequisites above), and kubectl’s current context becomes k3s-tracebloc. On Windows: the tracebloc WSL distro, with k3s inside it, and no Docker (the full list is in the Windows prerequisites above). Everywhere else: Docker (if it was missing), Homebrew on macOS (if it was missing and Docker was not already running), a local cluster named tracebloc, kubectl, k3d and helm, the tracebloc CLI (plus a PATH line in your shell profile, if needed), and ~/.tracebloc. On a Mac on k3d it also registers a launch agent that restarts the secure environment after a reboot. The installer also switches kubectl’s current context to k3d-tracebloc; if you work with other clusters, switch back with kubectl config use-context <your-context>.To remove tracebloc from this machine, run tracebloc delete — see Uninstall.

​
Locked-down environment?

If your security policy forbids piping scripts from the internet, skip the one-liner and deploy with Helm instead — same result, full control over every step.

​
What’s next

Stage a dataset

Ingest data so peers can build models against it.

Create a use case

Define a task and invite peers.