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

# Requirements

> What you need before installing, from a single GPU box to a governed cluster.

TunePlane is designed to work on one GPU server and on a centrally governed multi-node cluster,
without a different product for each. What changes between them is which of the pieces below you
actually need.

## Always

| Piece | Notes |
| - | - |
| Python 3.14 (control plane), 3.12+ (CLI) | The console image ships 3.14. The `tuneplane` CLI and the node daemon still run on 3.12 and later, so upgrading the server does not force an interpreter upgrade on researchers' machines or on GPU nodes. |
| A container runtime | Docker or Podman. Bare-process mode exists for development and isolates nothing |
| Storage | A path the console and every node see identically — see [storage layout](https://docs.tuneplane.ai/en/ops/storage.md) |
| At least one GPU | For anything but the platform's own tests, which run in simulation mode |

## For a team

| Piece | Why |
| - | - |
| **Postgres** | Required for control-plane persistence in every deployment |
| **Redis** | Shared cache, distributed locks, rate limiting, immediate token revocation. Without it, background tasks stop rather than run unsafely across replicas |
| **S3-compatible object storage** | Job packages, artifacts, datasets, archives. Without it everything falls back to shared-filesystem paths |
| **A fixed `TUNEPLANE_WEB_JWT_SECRET`** | Otherwise every restart signs with a new key and logs everyone out |
| **An https domain** | `TUNEPLANE_PUBLIC_URL`. Single sign-on cannot work without it |

> [!NOTE]
>
> **Which psycopg the console uses.** The shipped image compiles `psycopg[c]` against the base
> image's libpq, so TLS to a managed Postgres validates against the certificates the image trusts
> and a libpq security fix arrives with the next image rebuild. `psycopg[binary]` — the same C code
> with its own libpq and its own OpenSSL bundled inside the wheel — is what a development checkout
> gets, because it needs no compiler. Installing the wheel yourself, pick one:
> `tuneplane-server[c]` (needs `libpq-dev` and a compiler) or `tuneplane-server[binary]`. With
> neither, psycopg falls back to a pure-Python binding: slower, never broken.

> [!WARNING]
>
> A deployment with more than one console replica and no Redis has background roles disabled — storage
> accounting, diagnosis, the daily report and the watchdog do not run at all. The
> [scheduled tasks page](https://docs.tuneplane.ai/en/console/tasks.md) says so in a banner, but it is easy to miss.

## Per executor

**local**

One machine. Docker or Podman, and NVIDIA container runtime for real GPU passthrough. Nothing
else. This is the right starting point even for a team — moving to another executor later is a
setting, not a migration.

**node**

Several bare-metal machines, each running `tuneplane-node`. Requires the storage root mounted at the
same path on the console and every node, and a shared bearer token both sides hold. A missing
token refuses startup rather than running unauthenticated.

**kubernetes**

A Kubernetes cluster with the KubeRay operator, a GPU device plugin, and an RWX PVC for the
storage root. An RWO claim does not fail outright — it gives each pod its own volume, so
checkpoint shards split across nodes and the run cannot be resumed.

**slurm**

`slurmrestd` reachable over REST, with a JWT. The control plane never falls back to `sbatch` or
SSH. Container images must be available as SIF or SQSH through
`TUNEPLANE_RUNTIME_REGISTRY_FILE`, and the container runtime profile must be chosen explicitly.

## Network

| Direction | Needed for |
| - | - |
| Users → console | The web console and the API |
| Cluster → console | Ingest. Training reports logs and metrics back, so `TUNEPLANE_INGEST_URL` must be reachable *from inside the cluster* — never `127.0.0.1` |
| Console → executor | The Kubernetes API, slurmrestd, or the Node daemons |
| Cluster → registry | Pulling training images |
| Cluster → model hub | Weights, or an internal mirror — see [air-gapped](https://docs.tuneplane.ai/en/ops/airgapped.md) |

The second row is the one people miss. A console that users can reach is not automatically a console
that a worker node can reach.

## Optional, and what you lose without each

| Missing | Consequence |
| - | - |
| Object storage | No `tp dataset push`, no automatic post-training evaluation |
| An LLM endpoint | No AI diagnosis, no Ask Agent, no LLM judge, no daily report |
| A sandbox image | Environments that run model-generated code are refused rather than falling back to the training container |
| Argilla | No preference annotation loop |
| Hugging Face OAuth | No gated models, no pushing exports |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.