Quick Start

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: native k3s on Linux, k3s in Apple’s container runtime on a Mac, and k3s in tracebloc’s own WSL distro on Windows, all with no Docker at all. You just need a machine.

Before you start

You need	Minimum
A machine	macOS 26 or later (Apple silicon), Linux, or Windows 11 · 2 CPU · at least 7.0 GB RAM on Linux and 8 GB in WSL’s VM on Windows (a Mac: see below) · 10 GB free disk (30 GB on Windows)
A tracebloc account	Sign up free — no credit card
To train on this machine	4 CPU · 16 GB RAM · 50 GB disk, and 10 GB of memory for the platform and the smallest experiment: the machine’s own on Linux, the node’s VM on a Mac, and WSL’s VM on Windows (see below)

On Linux: what the machine needs (native k3s, no Docker)

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 machine needs
Processor	64-bit: `amd64` or `arm64`
Administrator rights	Once, as `sudo` or root, because k3s runs as root. Or an administrator prepares the machine for you once, and you install with no `sudo` (see below).
Memory	At least 7.0 GB: the installer stops below that, because a smaller machine cannot fit one training run beside the platform. 10 GB fits the smallest training run as installed, and 16 GB is recommended. An 8 GB machine trains too, once `tracebloc resources set max` has sized training to what is free beside the platform (tracebloc CLI 0.10.93 or later).
Disk	At least 10 GB free, and 20 GB recommended. This applies both where k3s keeps its data (`/var/lib/rancher/k3s`) and where your data is kept (`/var/lib/rancher/k3s/storage`, or the directory you set with `TRACEBLOC_HOST_DATA_DIR`). The installer stops below 10 GB.
CPU	2 cores, 4 recommended
Network	Outbound HTTPS (port 443) to the hosts below

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:

sudo ubuntu-drivers install --gpgpu nvidia:580-server

Without administrator rights. An administrator runs this once, with your user name in place of <user>:

export TRACEBLOC_SUBSTRATE=k3s TRACEBLOC_PREPARE_USER=<user> && curl -fsSL https://tracebloc.io/i.sh | bash -s -- prepare-host

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:

✖ This machine runs an older tracebloc install


─────────────────────────────────────────────

✖ Setup didn't finish

Deleting it keeps your use cases and models on tracebloc; its datasets must be ingested again.
To install, delete it first:
  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:

✖ alice runs an older tracebloc install on this machine


─────────────────────────────────────────────

✖ Setup didn't finish

Deleting it keeps alice's use cases and models on tracebloc; its datasets must be ingested again.
To prepare this machine, delete it first as alice:
  tracebloc delete

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.

Host	Why	Needed
`registry-1.docker.io`, `auth.docker.io`	Docker Hub	every run
`ghcr.io`	the tracebloc images	every run
`api.tracebloc.io`	the tracebloc API	every run
`tracebloc.github.io`	the tracebloc Helm charts	every run
`rpm.rancher.io`	k3s’s SELinux policy, on an SELinux-enforcing RHEL, Fedora or SUSE machine	every run
`github.com`, `release-assets.githubusercontent.com`	the k3s release	until k3s is installed, and on a run that upgrades it
`get.helm.sh`	Helm	until Helm is installed

On a Mac: what the Mac needs (Apple's container runtime, no Docker)

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 Mac needs
Processor	Apple silicon (M1 or later). The installer stops on an Intel Mac.
macOS	26 or later. The installer stops on an older version.
Administrator rights	None.
Memory	16 GB recommended. The node is a VM that holds part of the Mac’s memory while it runs: 6 GB of an 8 GB Mac, 10 GB of a 16 GB Mac, 12 GB of a 24 GB Mac, and 16 GB of a Mac with 32 GB or more. 10 GB fits the smallest training run. On a smaller Mac, the installer stops before it creates the node if a training run would not fit beside the platform.
Disk	At least 10 GB free, and 20 GB recommended, on the disk that holds `~/Library/Application Support/tracebloc/container`, where the node’s images and its volume are kept. The installer stops below 10 GB. The volume grows as data is written, up to 64 GB. The installer checks the disk that holds your job data too.
CPU	2 cores, 4 recommended. The node gets all but one of them.
Network	Outbound HTTPS (port 443) to the hosts below

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:

✖ This machine runs an older tracebloc install


─────────────────────────────────────────────

✖ Setup didn't finish

Deleting it keeps your use cases and models on tracebloc; its datasets must be ingested again.
To install, delete it first:
  tracebloc delete

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.

Host	Why
`registry-1.docker.io`, `auth.docker.io`	Docker Hub: the k3s node image
`ghcr.io`	the tracebloc images and the node’s kernel
`api.tracebloc.io`	the tracebloc API
`tracebloc.github.io`	the tracebloc Helm charts
`dl.k8s.io`	kubectl
`github.com`, `release-assets.githubusercontent.com`	Apple’s `container` runtime, its signed package
`get.helm.sh`	Helm

On Windows: what the machine needs (tracebloc's WSL distro, no Docker)

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.

	What the machine needs
Windows	Windows 11 (build 22000 or later). The installer stops on an older Windows.
Processor	64-bit `amd64` (x64): tracebloc’s distro image is built for it
WSL	2.5 or later. If it is missing or older, an administrator turns it on once (see below).
Administrator rights	Once, for that step. Everything after it runs as the signed-in user, and the installer refuses to run as the SYSTEM account.
Memory	At least 8 GB in WSL’s VM: the installer warns below that, because a smaller VM cannot fit one training run beside the tracebloc platform. 10 GB in the VM fits the smallest training run, and 16 GB is recommended. WSL gives its VM half of the machine’s memory by default; `memory=` under `[wsl2]` in `%UserProfile%\.wslconfig`, WSL’s own setting, changes that. When a `memory=` set there leaves Windows too little memory, the installer warns, says how much is left, and goes on: lower the value, then run `wsl --shutdown`.
Disk	At least 30 GB free on the drive that holds the distro. The distro’s disk is capped at what is free there, less 20 GB that is left to Windows. The installer stops if that leaves less than 10 GB for the distro.
CPU	2 cores, 4 recommended
Network	Outbound HTTPS (port 443) to the hosts below

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:”

wsl --install --no-distribution

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.

Host	Why
`registry-1.docker.io`, `auth.docker.io`	Docker Hub
`ghcr.io`	the tracebloc images
`api.tracebloc.io`	the tracebloc API
`tracebloc.github.io`	the tracebloc Helm charts
`github.com`, `release-assets.githubusercontent.com`	the k3s release
`get.helm.sh`	Helm

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 about 10 GB of memory. The installer checks it for you:

Linux: the machine’s own memory counts, and the installer stops below the minimum in the Linux prerequisites above.
A 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).
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.

Run the installer

macOS / Linux
Windows (PowerShell)

curl -fsSL https://tracebloc.io/i.sh | bash

irm https://tracebloc.io/i.ps1 | iex

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 Linux the cluster is native k3s, and it asks for your password once (sudo), because k3s runs as root. On a 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). Safe to re-run anytime. On a machine an older installer set up on k3d, moving to k3s is a reinstall: see the prerequisites above.

Prefer to read the script before running it?

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:

curl -fsSL https://github.com/tracebloc/client/releases/latest/download/install.sh -o install.sh   # silent download — no output means it worked
less install.sh        # review it (q to quit)
bash install.sh        # run it

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.

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.

Verify it's connected

Open a new terminal (so the tracebloc command is on your PATH), then run:

tracebloc client status    # should print: online
tracebloc doctor           # checks connection and training readiness, says what to fix

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 Linux: 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 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). 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.

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Before you start

Locked-down environment?

What’s next

Stage a dataset

Create a use case