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

# Weights

> Organize, resolve, and ship model weights from local development to production.

Model weights are never baked into the container image. You keep them on disk while you iterate,
ship them to Reactor as a separate artifact when you publish a release, and read them back from the
same `get_weights_path()` call in both places.

## Resolving the weights directory

The runtime exports a single helper for finding weights. Use it everywhere you would otherwise
hard-code a path:

```python theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
from reactor_runtime import get_weights_path


def load(self, config_path: Path | None) -> None:
    weights = get_weights_path()
    self.transformer = AutoModel.from_pretrained(weights / "wan2_2" / "transformer")
    self.vae = load_vae(weights / "wan2_2" / "vae")
```

<Check>
  The same `load()` code runs unchanged from your laptop to production. Only the resolved root path
  changes.
</Check>

`get_weights_path()` returns a `pathlib.Path` to the root directory under which all of your
checkpoints live. You arrange subdirectories under that root however you like; the runtime never
inspects the layout.

### Resolution order

`get_weights_path()` returns `$REACTOR_WEIGHTS_PATH` when it is set, and `~/.cache/reactor_registry`
otherwise.

You rarely set that variable by hand. `reactor run` resolves `runtime.weights_path` from
`reactor.yaml`, mounts it into the container, and sets `REACTOR_WEIGHTS_PATH` to the mount point; in
production Reactor points it at the bundle it mounted for the release.

## Configuring the weights path locally

You'll usually pick one of two ways to point the runtime at your local checkpoints.

<CodeGroup>
  ```yaml reactor.yaml theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  runtime:
    import: model:MyModel
    weights_path: ./weights
  ```

  ```bash env theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
  export REACTOR_WEIGHTS_PATH=/data/weights
  ```
</CodeGroup>

Relative paths in `reactor.yaml` resolve against the workspace root (the directory containing
`reactor.yaml`), so `./weights` always points at `<workspace>/weights` regardless of where you
launch the runtime from. Absolute paths are passed through unchanged.

<Info>
  `reactor run` mounts the resolved path into the container, so weights persist across restarts.
</Info>

## The weights lifecycle

The same `get_weights_path()` call works at every stage of your model's life. You write the code
once and the path resolves to the right place automatically.

<Steps>
  <Step title="Local development">
    Keep your weights anywhere on disk. Point `runtime.weights_path` or `$REACTOR_WEIGHTS_PATH` at the root and arrange checkpoints under it however you like:

    ```
    /data/weights/
    ├── wan2_2/
    │   ├── transformer/...
    │   └── vae/...
    └── tokenizer/...
    ```
  </Step>

  <Step title="Shipping">
    When you're ready to publish, `reactor model publish --weights <path>` uploads the entire subtree as part of the release. Your subdirectory layout is preserved exactly.
  </Step>

  <Step title="Production">
    Reactor mounts the uploaded bundle into your model container and points `get_weights_path()` at it. The same `load()` code keeps working.
  </Step>
</Steps>

## Shipping weights with a release

`reactor model publish` registers the release, builds and pushes the image, and — when you pass
`--weights <path>` — uploads that bundle in the same command. Without the flag the weights step is
skipped and the deploy reuses the previously deployed release's bundle:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model publish --weights ./weights
```

To stage a release before the weights are ready, publish image-only and ship them later with
`reactor weights upload`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}}
reactor model publish
reactor weights upload my-awesome-model:v1.0.0 ./weights/
```

The same `reactor weights upload` command swaps the weights on an existing release without
rebuilding the image. Run `reactor model publish --help` for the full flag list.

## Layout rules

* **Symlinks are rejected**, both at the bundle root and within the tree. Resolve them first with
  `cp -L` or `tar --dereference`.
* **Large bundles are fine.** Hundreds of GB is supported; the upload streams files instead of
  loading them into memory.

## Next

<CardGroup cols={2}>
  <Card title="Model Anatomy" icon="microscope" href="/deploy/development/reactor-model/model-anatomy">
    Where `load()` sits in a model, and what it is handed.
  </Card>

  <Card title="Recording" icon="circle-dot" href="/deploy/development/recording">
    Another `reactor.yaml` knob that follows the same local-to-production lifecycle.
  </Card>
</CardGroup>