> ## 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.

# How TunePlane fits together

> Submission, execution control and telemetry have separate contracts and resource budgets.

TunePlane separates submission, workload control and telemetry. The training framework owns training; the platform owns admission, placement, execution identity and observation.

## Control and data paths

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
flowchart LR
  CLI[CLI / Console] --> API[Python control plane]
  API --> DB[(PostgreSQL)]
  Node[Node daemon] <-->|TLS + gRPC| Control[Node control gateway]
  Control --> DB
  Node --> Job[Training workload]
  Job --> Files[TensorBoard / JSONL]
  Files --> Collector[Rust collector]
  Collector -->|TLS + gRPC| Telemetry[Telemetry gateway]
  Telemetry --> DB
  API --> UI[Console queries and charts]
```

The Node opens the control connection outbound. Training metrics travel through the independent telemetry listener; they do not relay through the Node control channel. Both gateways currently run as separate **Python processes**. The independent collector is **Rust**. A future Rust gateway or LLM API proxy is an architectural extension, not a shipped inference-routing capability.

## What happens when you submit

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp submit my-grpo --profile h200:8 --preview
tp submit --commit .tuneplane-data/submissions/<preview-id>.json
```

1. The CLI or console supplies recipe, source-archive or image-and-command input.
2. The server validates and resolves the JobSpec, integration artifact, runtime image, resources, storage and policy. The immutable preview creates no Job.
3. Confirmation supplies the preview ID, digest and stable retry key. Repeating the same confirmation returns the same Job receipt; editing the intent requires a new preview.
4. The admitted Job waits for resources. A durable launch reservation owns the whole resource envelope before execution starts.
5. The backend materializes the verified Job Capsule and completed inputs. On Node, all members Prepare before the durable Commit decision. Cold image preparation is asynchronous; uncertain ownership is reconciled before resources are released.
6. The runner validates the pinned runtime and executes the integration artifact. Framework-specific code stays outside the control plane.
7. Native TensorBoard/JSONL output can be collected independently. The configured SDK reporting path also remains available. The console reads bounded metric queries; completed artifacts carry verifiable manifests.

A lost connection is not proof that a workload stopped. Metrics, lifecycle and artifact completion have different acceptance requirements. See [submission](https://docs.tuneplane.ai/en/cli/submit.md), [Node execution](https://docs.tuneplane.ai/en/ops/executor-node.md) and [native telemetry](https://docs.tuneplane.ai/en/ops/telemetry.md).

## Backend execution

| Backend | Execution | Resource pools |
| - | - | - |
| Local | Docker or Podman on the console host | One pool |
| Node | Outbound authenticated TLS/gRPC; durable member journal on each machine | One homogeneous pool, at most 32 members; multi-machine GPU process-group or Ray workloads |
| Kubernetes | Native Job or RayJob selected by the runtime contract; Kueue admission | Multiple pools where supported by the runtime |
| Slurm | slurmrestd allocation and srun; process-group, Ray or CPU execution according to the runtime contract | Multiple pools through heterogeneous allocation |

No backend fallback is implicit. A supported software contract is not proof of a certified GPU, network or storage deployment. Peer networking and shared output storage must be validated separately from the control connection.

## Identity and storage

Nodes hold private, rotating control credentials outside workload mounts. Collectors receive separate, narrowly scoped run/attempt/member credentials. Workloads do not receive cluster administrator credentials. Server TLS verification stays enabled; ordinary deployments do not require per-Node client certificates or a separate PKI service.

Source logs may use shared storage; the collector's durable spool requires private host-local storage. Shared mounts and object delivery are explicit backend capabilities. Object Capsule delivery does not remove the shared output/cache requirements of every backend. See [storage](https://docs.tuneplane.ai/en/ops/storage.md).

## Console workflow

The Fleet page separates scheduling state from control connectivity and shows reported CPU/memory capacity. The submission dialog summarizes the resolved Fleet, backend and GPU request before confirmation. Job Charts supports canonical metrics and an attempt/source-specific raw scalar inspector. Plugins use purpose groups while keeping capabilities and execution location explicit.

See [Fleets](https://docs.tuneplane.ai/en/ops/fleets.md), [observability](https://docs.tuneplane.ai/en/ops/observability.md) and [plugins](https://docs.tuneplane.ai/en/console/plugins.md).


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