# Hydra Configuration (/en/docs/configuration/hydra)

> How UniRL composes, validates, and overrides runtime configuration.

UniRL uses Hydra. Recipes are self-contained YAML files under `examples/`, bucketed by trainer domain (`diffusion/`, `vlm/`, `llm/`, `pe/`, `unified_model/`); each training run selects one with `--config-name`:

```bash
python -m unirl.train_diffusion --config-name=<domain>/<recipe>
```

## Composition [#composition]

A recipe instantiates each runtime component directly by `_target_` (FSDP backend, train stack, rollout engine, reward service, algorithm, data source, …). Config classes are plain `@dataclass`es defined next to the code that consumes them — there is no ConfigStore and no registration decorator. A recipe wires a component by pointing its `_target_` at the class and nesting the component's `config:` block (also a `_target_`). Use the generated [Config Package README](/en/docs/configuration/readme-config-package) for the instantiation and validation contracts.

## Where Knobs Belong [#where-knobs-belong]

Keep recipe-defining choices in `examples/<domain>/<recipe>.yaml`. Keep cluster-local paths, model mounts, output directories, and WandB identity in launcher environment variables or CLI overrides (recipes interpolate them with `${oc.env:...}`). A new typed runtime component should define its config `@dataclass` next to the implementation; a recipe then references it by `_target_` (no registration step).

Override precedence is:

```text
CLI Hydra override > launcher env var > YAML default
```

## Runtime Contracts [#runtime-contracts]

Cross-component validators run before Ray worker creation. The implementation details and validator list live in the generated [Config Package README](/en/docs/configuration/readme-config-package).

`sync` and the tensor transport solve different problems. `sync` (`cfg.sync`) sends trainer weights back to dedicated rollout engines, while the tensor transport (`unirl/distributed/tensor/`) is the data plane for moving bulky rollout outputs between workers.

Use a compose check before launching a large job:

```bash
python -m unirl.train_diffusion --config-name=<domain>/<recipe> --cfg job --resolve
```