> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracebloc.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Guide

> Detailed walkthrough for deploying a tracebloc workspace — requirements, installer internals, GPU support, and verification.

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.

<Note>
  The installer deploys a **single-node workspace on one machine** — a local Kubernetes cluster running inside Docker on that host. For multi-node or production deployments, see the [EKS deployment guide](/environment-setup/eks-client-deployment-guide).
</Note>

***

## Requirements

The installer runs on any modern machine (one host per workspace) and **checks these before it starts** — below the minimum it stops on Linux with a clear message (on macOS/Windows it warns; raise Docker Desktop's memory in Settings → Resources). "To run" keeps a workspace online; **training on the same machine needs the headroom** — a single training job alone reserves \~8 GB.

|          | To run the workspace | To train on this machine |
| -------- | -------------------- | ------------------------ |
| **CPU**  | 2 cores              | 4+ cores                 |
| **RAM**  | 5 GB                 | 16 GB                    |
| **Disk** | 10 GB free           | 50+ GB free              |

**Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86\_64 & arm64) · Windows (x86\_64 & arm64)

**Outbound access needed:** The installer pulls container images, the install scripts, and the Helm chart, then connects to the tracebloc platform. Allow traffic to `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`.

<Warning>
  **Storage must be on a local disk.** The data directory (`HOST_DATA_DIR`, default `~/.tracebloc`) holds the workspace 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, point `HOST_DATASET_DIR` at it instead: only the dataset volume moves there, while the database stays local. See [Configuration](/environment-setup/configuration).
</Warning>

***

## 1. Create an Account

Sign up at [ai.tracebloc.io](https://ai.tracebloc.io). Free to get started — no credit card required.

## 2. Register a Client

A **client** is your workspace's identity on the platform. It ties a specific machine to your account and controls what data and use cases are accessible from it.

Open the [client page](https://ai.tracebloc.io/clients) and click **"+"**.

| Field        | What to enter                                 |
| ------------ | --------------------------------------------- |
| **Name**     | A name for your workspace, e.g. `my-team`     |
| **Location** | Where this machine is deployed                |
| **Password** | A secure password (not your account password) |

The client starts as **Pending** while the backend provisions resources. Note the **Client ID** and **password** — you need both in the next step.

<Tip>
  Provisioning usually takes a few seconds. Refresh the page if the status doesn't update.
</Tip>

### Client Status Reference

Your client moves through these states as it goes from registration to running:

| Status      | Meaning                                  |
| ----------- | ---------------------------------------- |
| **Pending** | Registration received, being provisioned |
| **Online**  | Deployed and connected to the platform   |
| **Offline** | Disconnected or not running              |

## 3. Deploy

One command sets up your entire workspace 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.

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    bash <(curl -fsSL https://tracebloc.io/i.sh)
    ```
  </Tab>

  <Tab title="Windows">
    Open **PowerShell as Administrator**:

    ```powershell theme={null}
    irm https://tracebloc.io/i.ps1 | iex
    ```
  </Tab>
</Tabs>

Nothing on your machine is modified outside:

* `~/.tracebloc/` — data and config
* **Docker** — container runtime

### What the Installer Does

The installer runs four clearly labelled steps:

**Step 1/4 — Check system requirements**
Verifies Docker is installed and running, detects GPU hardware (falls back to CPU mode if none), and installs missing system tools (e.g. `conntrack`).

**Step 2/4 — Set up secure compute environment**
Provisions a lightweight local Kubernetes cluster inside Docker. First run takes 1–2 minutes to download components.

**Step 3/4 — Install tracebloc client**
Prompts for a **workspace name** (e.g. `berlin-team`, `vision-lab`, `ml-mardan`). This identifies the client on your machine and becomes the Kubernetes namespace.

**Step 4/4 — Connect to tracebloc network**
Prompts for your **Client ID** and **password** from step 2 above. This links your secure local environment to the tracebloc platform so vendors can submit models for evaluation.

When it finishes you'll see a summary like:

```
tracebloc client installed successfully

Workspace : <workspace>
Mode      : CPU      # or GPU

Logs:       ~/.tracebloc/
Data:       /tracebloc/<workspace>
```

Install logs are kept in `~/.tracebloc/` if you need to debug anything.

<Note>
  To upgrade a one-liner install later, run `helm upgrade <workspace> tracebloc/client -n <namespace> --reset-then-reuse-values` (append `--version <version-number>` to pin). See [Configuration → Upgrade](/environment-setup/configuration#upgrade) for details — `--reset-then-reuse-values` is required so the values applied by the installer are preserved.
</Note>

### GPU Support

The installer detects your GPU and configures the cluster:

* **Linux (NVIDIA/AMD)** — drivers, container toolkit, and Kubernetes device plugin are installed automatically. A reboot may be required after driver installation.
* **macOS** — CPU-only. For GPU workloads, deploy on a Linux machine or use [AWS (EKS)](/environment-setup/eks-client-deployment-guide).
* **Windows** — pre-install NVIDIA drivers before running the installer. The installer detects them via `nvidia-smi`.

See [Configuration > GPU](/environment-setup/configuration#gpu-support) for detailed platform-specific behavior.

## 4. Verify

After the installer finishes, confirm that your workspace is running:

```bash theme={null}
kubectl get pods -n <workspace>
```

You should see two pods in `Running` state:

| Pod                          | Role                                                                   |
| ---------------------------- | ---------------------------------------------------------------------- |
| `mysql-...`                  | Local metadata store — tracks jobs, metrics, and configuration         |
| `tracebloc-jobs-manager-...` | The client — executes training jobs and communicates with the platform |

Then open [ai.tracebloc.io](https://ai.tracebloc.io) and check that your client status shows **Online**. This confirms the client has established a secure connection to the tracebloc backend.

<Tip>
  Stuck on Offline? Check the [Troubleshooting](/environment-setup/troubleshooting) page — most issues resolve with a pod restart or credential check.
</Tip>

***

## What's Next

Your workspace is running. Here's where to go from here:

**Data owners:** [Ingest your dataset](/create-use-case/prepare-dataset), then [create a use case](/create-use-case/prerequisites) — pick from prepared datasets, define evaluation metrics, and invite contributors to submit models.

**Data scientists:** [Join a use case](/join-use-case/join-use-case) — connect to a workspace, train models on real data, and submit results.

**Advanced configuration:** [Configuration](/environment-setup/configuration) — customize installer options, manage the cluster, configure GPU settings, or deploy manually with Helm.