# Onboarding

Alpasim depends on access to the following:

- Hugging Face access
  - Used for downloading simulation artifacts
  - Data is
    [here](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles-NuRec/tree/26.01/sample_set/26.01_release)
  - See info on data
    [here](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles-NuRec/blob/main/README.md#dataset-format)
    for more information on the contents of artifacts used to define scenes
  - You will need to create a free Hugging Face account if you do not already have one and create an
    access token with read access. See [access tokens](https://huggingface.co/settings/tokens).
  - **You must also request access** to the gated dataset at
    [nvidia/PhysicalAI-Autonomous-Vehicles-NuRec](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles-NuRec).
    Without this, scene downloads will fail with a `GatedRepoError`.
  - Once you have the token, set it as an environment variable: `export HF_TOKEN=<token>`
- `uv` version `0.9.17` or newer installed (see [here](https://docs.astral.sh/uv/getting-started/installation/))
  - Example installation command for Ubuntu: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
  - If `uv` is already installed, you can upgrade it with `uv self update`.
- Rust toolchain (`cargo`) for building `utils_rs`, a compiled extension that accelerates trajectory
  transformations and interpolations in the runtime. Install via
  [rustup](https://rustup.rs/) or interactively let `setup_local_env.sh` install it for you.
- Docker installed (see [setup instructions](https://docs.docker.com/engine/install/ubuntu/))
- Docker compose installed (see
  [setup instructions](https://docs.docker.com/compose/install/linux/))
  - The wizard needs `docker`, `docker-compose-plugin`, and `docker-buildx-plugin`
  - Docker needs to be able to run without `sudo`. If you see a permission error when running
    `docker` commands, add yourself to the docker group: `sudo usermod -aG docker $USER`
- CUDA 12.8 or greater installed (see [here](https://developer.nvidia.com/cuda-downloads) for
  instructions)
  - The NRE container uses CUDA 12.8, so your host NVIDIA driver must support it (driver version >=
    570.x).
- Install the NVIDIA Container Toolkit (see
  [here](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html))

## Optional: OmniDreams video-model renderer

The default AlpaSim tutorial uses NuRec. To use
[OmniDreams](https://github.com/nv-tlabs/omni-dreams) as the renderer backend, follow the
[Video Model Renderer guide](VIDEO_MODEL.md) after completing the base setup above.

Additional requirements for this path:

- A [FlashDreams](https://github.com/NVIDIA/flashdreams) checkout and a locally built
  `flashdreams-alpasim:local` image for `deploy=managed_flashdreams`, or access to an external
  OmniDreams gRPC server for `deploy=external_video_model`.
- Hugging Face authentication for any gated OmniDreams, FlashDreams, driver, or scene assets needed
  by the selected run.
- Enough GPU memory for both the renderer and the selected driver. The managed FlashDreams preset
  currently requires about 48 GB VRAM with the lightweight public single-view driver preset and
  about 96 GB VRAM with the Alpamayo1.5 single-camera preset.

## Dependency management

The repo is a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/). All packages under `src/` and `plugins/` are workspace members sharing a single lockfile (`uv.lock`). The root `pyproject.toml` has empty `dependencies`, so a bare `uv sync` installs nothing -- this is intentional to avoid pulling heavy dependencies (torch, warp-lang) by default.

Each workspace member is exposed as a named optional dependency extra, enabling composable installs from the repo root:

```bash
# Recommended for local development (compiles protos, installs all core + transfuser_driver plugin)
source setup_local_env.sh

# Or install selectively:
uv sync --extra wizard                           # wizard + transitive deps only
uv sync --extra all                              # all core packages
uv sync --extra all --extra transfuser_driver    # core + transfuser_driver plugin

# Single-package install from a subdirectory also works:
cd src/wizard && uv sync
```

Use `uv run` to execute commands in the workspace environment:

```bash
uv run pytest                                # run tests
uv run alpasim_wizard deploy=local topology=1gpu driver=vavam ...  # run the wizard
uv run --project src/runtime python -c "..." # run in a sub-project context
```

All members share one dependency resolution; there is no per-member version isolation. See [Plugin System](PLUGIN_SYSTEM.md) for how plugins integrate with the workspace.

## Troubleshooting

**`CUDA_ERROR_UNSUPPORTED_PTX_VERSION` during NRE warmup**
Your NVIDIA driver is too old for the CUDA version in the NRE container. Upgrade to driver >= 570.x
(CUDA 12.8 support). Check your current version with `nvidia-smi`.

**`GatedRepoError` when downloading scenes**
You need to request access to the gated HuggingFace dataset. Visit
[nvidia/PhysicalAI-Autonomous-Vehicles-NuRec](https://huggingface.co/datasets/nvidia/PhysicalAI-Autonomous-Vehicles-NuRec)
and request access.

**`HF_TOKEN` not set / authentication failures**
Set your HuggingFace token: `export HF_TOKEN=<your-token>`. You can create a token at
[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).

**gRPC connectivity errors between services**
Ensure Docker networking is working and all containers are on the same network. Check
`docker compose logs` for port binding conflicts. If using `debug_flags.use_localhost: true`,
ensure no other process is using the assigned ports.

**`setup_local_env.sh` fails silently in non-interactive environments**
The script only installs Rust when a TTY is detected. To install Rust manually,
use: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y`

**`uv` parse error on `exclude-newer = "3 days"`**
Your `uv` is older than 0.9.17 and can't parse the relative cooldown in the root
`pyproject.toml`. Don't delete the line (it's an intentional supply-chain
safeguard); upgrade instead with `uv self update`.

**`ModuleNotFoundError` (e.g. `alpasim_grpc.v0.*_pb2`) in the service containers**
The git-ignored gRPC stubs are missing on the host, and the volume-mounted source
tree shadows the stubs baked into the images. Run `source setup_local_env.sh` (or
`cd src/grpc && uv run compile-protos`) to generate them.

## Next steps

Once you have access to the above, please follow instructions in the [tutorial](TUTORIAL.md)
to get started running Alpasim.