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

# FAQ

> Frequently asked questions about the platform's design and usage

<AccordionGroup>
  <Accordion title="Why can't I just run ray job submit / kubectl / sbatch directly?">
    Cluster credentials live only on the server side: in exchange you get quota enforcement, auditing, unified observability, and traceability. The platform's proxied submission is a functional superset — the only thing you lose is the ability to bypass quotas.
  </Accordion>

  <Accordion title="Why does every submission require a clean git workspace?">
    Every run records the exact commit + config snapshot + recipe digest. When you try to reproduce "that good result" three months later, this is the only reliable path. Use `--allow-dirty` when in a hurry, but understand the cost.
  </Accordion>

  <Accordion title="The lockfile (recipe.lock.json) keeps saying it's outdated — can it auto-upgrade?">
    No — an upgrade may change training behavior (entrypoints, defaults, images), so it must be confirmed explicitly. `sf submit --upgrade-recipe` already compresses that explicit confirmation into a single flag.
  </Accordion>

  <Accordion title="Which framework versions are supported? Do you track new upstream releases?">
    Check `sf methods`: each method lists its published versions (e.g. verl 0.8.0 / 0.9.0). New upstream versions enter the catalog via the [Adoption SOP](/en/ops/upgrades) — in most cases it's just declaring YAML + publishing an image, with no platform code changes.
  </Accordion>

  <Accordion title="How do I run my custom framework / private code?">
    `custom/custom` plus an allowlisted image, with `train.sh` in the experiment. The image needs Python, the framework, and your deps, not the CLI. Catalog custom is `external` observability: pass `--observability-url` and install `starforge-core` in the image if you want console charts. Details: [Custom training](/en/guides/custom-training).
  </Accordion>

  <Accordion title="Where does training data go?">
    Pick one of three: an HF dataset id (public/gated data), a platform dataset (internal data, versioned + auto-distributed), or an absolute path on a shared drive (ad hoc). The first two are recommended — path references cannot be traced to a version.
  </Accordion>

  <Accordion title="How is GPU usage billed/accounted?">
    Every job records gpu\_seconds (GPU occupancy time × GPU count), visible on the console usage page and in daily reports. Queued time is not billed; billing starts once the container is up after PENDING.
  </Accordion>

  <Accordion title="Can I develop/test in an environment without GPUs?">
    Yes. The E2E closed loop runs on GPU-less machines (the GPU simulation switch preserves all scheduling/quota semantics) — see [E2E Closed-Loop Testing](/en/ops/e2e-testing).
  </Accordion>

  <Accordion title="Console screenshots/entries in the docs don't match what I see?">
    Some features are toggled by deployment configuration (HF integration, Playground, plugin hub, MCP write tools). If an entry doesn't appear, that deployment hasn't enabled it — contact an admin.
  </Accordion>
</AccordionGroup>