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

# FAQ

> The questions people ask in the first week, with the shortest true answer to each.

## Why not just run `ray job submit`, `kubectl` or `sbatch`?

You can, if you have the credentials. TunePlane holds them instead, and in exchange the run gets
quota enforcement, an audit trail, one place its metrics land, and a record of the commit it came
from. The only thing the proxied path takes away is the ability to skip a quota.

## Why does a submission need a clean working tree?

Every run records its commit, a config snapshot and the recipe digest. Three months later, that
is the only reliable way to reproduce the good result.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp submit my-grpo --profile h200:8 --allow-dirty
```

is there for when you accept the cost. A project with no git repository is not blocked at all: it
submits with no provenance recorded. The clean-tree rule is about a repository that *could* answer
the question and was not asked to.

## Can the lock file upgrade itself?

No. An upgrade can change entrypoints, defaults and images, so it has to be a decision somebody
made.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp submit my-grpo --profile h200:8 --upgrade-recipe
```

compresses that decision into one flag.

## Which framework versions can I use?

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
tp methods
```

Each method lists the versions your deployment has published. A new upstream release enters the
catalogue as a manifest and an image, usually with no platform code change — see
[upgrades](https://docs.tuneplane.ai/en/ops/upgrades.md).

## How do I run my own framework or private code?

`custom/custom` with an allowlisted image and a `train.sh` in the experiment. The image needs
Python, your framework and your dependencies — not the CLI.

The published custom recipe declares `external` observability, so pass `--observability-url` and
install the `tuneplane` wheel if you want console charts. See
[custom training](https://docs.tuneplane.ai/en/guides/custom-training.md).

## Where should training data live?

Three options, in order of preference:

| Option | Use it for |
| - | - |
| A [platform dataset](https://docs.tuneplane.ai/en/guides/datasets.md) | Internal data. Versioned, distributed to the cluster automatically |
| A hub id | Public or gated data. `hf:nvidia/OpenMathInstruct-2` |
| An absolute path on a shared drive | Ad hoc work. A path cannot be traced to a version |

For material a job may read but nobody may download, use a [Volume](https://docs.tuneplane.ai/en/guides/volumes.md).

## How is GPU time counted?

Every job records `gpu_seconds`, which is wall time holding cards times the card count. Queued
time is free; counting starts when the container is up. It shows on the console's Usage page.

## Can I work on a machine with no GPU?

Yes, for everything except training. `tp init`, `tp new`, `tp validate`, `tp methods` and
`tp job logs` are all local or read-only. A whole submit-to-ingest loop runs without a GPU too,
with scheduling and quota semantics intact — see [smoke-testing](https://docs.tuneplane.ai/en/ops/smoke-test.md).

## The console does not match this documentation

Several features are switched on per deployment: the Hugging Face integration, the Playground,
the plugin shelf, MCP, teams and approvals. A missing sidebar entry means your deployment has not
enabled it. Ask an administrator.

## Why is my job's team not the team I am in?

A run's team comes from its **project**, not from you. A person can be in several teams, so
charging a run to all of them would count it several times. See [teams](https://docs.tuneplane.ai/en/guides/teams.md).

## Next

[Troubleshooting](https://docs.tuneplane.ai/en/troubleshooting.md) · [Glossary](https://docs.tuneplane.ai/en/concepts/glossary.md) ·
[Job states](https://docs.tuneplane.ai/en/concepts/job-lifecycle.md)


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