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

# What is Train?

> Train policies inside a world model, certify them in a frozen physics oracle.

Train is the dream-training API. Where the Play API creates and embeds
playable worlds, Train uses a world model as a *training environment*: your
policy learns inside the dream, then gets examined in a frozen physics exam
it never trains in.

<CardGroup cols={2}>
  <Card title="Train in the dream" icon="brain">
    CMA-ES evolves a compact controller inside the doom world model, the same
    public checkpoint as
    [alakazamworld/doom-dungeon-hg](https://huggingface.co/alakazamworld/doom-dungeon-hg)
    (byte-identical, sha256-verified).
  </Card>

  <Card title="Certify in the oracle" icon="scale-balanced">
    A frozen Webots exam (two physical worlds, fixed contract, anti-exploit
    control arms) is the sole scoreboard. Dream fitness is never a capability
    claim.
  </Card>
</CardGroup>

## The pipeline

One `POST /jobs` runs both stages and leaves a machine-readable `job.json`:

```
spec ──> TRAIN (CMA-ES in the world model) ──> EXAM (frozen Webots oracle) ──> job.json
              │ per-generation metrics,             │ per-episode physics rows,
              │ streamed live                       │ 4-bar verdict + control arm
```

Jobs are asynchronous, kill-tolerant, and append-only. Poll
`GET /jobs/{job_id}` for live progress; never block on the POST.

## Lineage is an explicit input

Warm-start any job from a prior champion with `train.parent` (an inline genome
or a prior `job_id`). Lineage is recorded in the artifacts, so chains are
reproducible with no ambient state. Warm-started jobs reproduce the historical
best-known profile: contact-safe, 0 contacts in 40/40 exam episodes.

## Two ways to train

<CardGroup cols={2}>
  <Card title="Server jobs (this API)" icon="server">
    Submit a spec, get a reproducible, certified result. Best for lineage
    chains and anything you want the oracle's verdict on.
  </Card>

  <Card title="Local gym (your hardware)" icon="laptop">
    The world-model weights are public. Run the dream locally (WebGPU or
    ONNX Runtime) at your own speed, then submit champions to the exam.
    See [Local gym](/train/local-gym).
  </Card>
</CardGroup>

## What's live vs. roadmap

| Surface                                                                   | Status                                                         |
| ------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `POST /jobs`, `GET /jobs/{id}`, `GET /jobs/{id}/log`                      | **Live** (verified end-to-end)                                 |
| Simulation gym `/v1/sim/sessions` (SNN observation contract)              | **Live**, beta, self-hosted runner ([guide](/train/snn-guide)) |
| Local gym on public weights + exam-only certification                     | **Live**                                                       |
| Certify your own policy (sandboxed python module, any architecture)       | **Live** ([guide](/train/own-policy))                          |
| Step-level gym against the *doom dream* over HTTP                         | Design spec, not live                                          |
| SNN-native observation contract + cross-world-model transfer certificates | Planned, not live                                              |

<Note>
  The serving VM sleeps when idle; the first request wakes it. During the boot
  window (4 to 8 min) requests return `503 {"status": "waking"}` with a `phase`
  field; retry the same call until it succeeds. Measured
  wall-times on the serving VM: smoke job 12–17 min, real-scale job 3–4 h, exam
  alone 4–6 min (the VM's CPU generation varies per boot).
</Note>