> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/aerial/aodt/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/aerial/aodt/_mcp/server.

# Client Installation

The AODT client provides C++ and Python libraries for configuring and running simulations over gRPC. It supports remote data transfer over gRPC and optional CUDA IPC for fast local GPU transfers when the client and worker are colocated.

## Transport mode

Transport mode defines how the client and worker exchange simulation data.

In [Interactive Mode](/quickstart), channel impulse responses (CIRs) can be read directly from GPU memory through the client APIs. This requires the client and worker to run on the same machine with a shared GPU. AODT refers to this configuration as LOCAL\_IPC.

In non-colocated deployments, CIRs are copied from GPU memory to host memory on the worker, then transferred to the client over gRPC. This configuration is referred to as REMOTE.

## Platform support

| Platform            | CUDA | gRPC | Transport mode                   |
| ------------------- | ---- | ---- | -------------------------------- |
| Linux with GPU      | yes  | yes  | LOCAL\_IPC (colocated) or REMOTE |
| WSL2 with GPU       | yes  | yes  | LOCAL\_IPC (colocated) or REMOTE |
| Linux / WSL2 no GPU | no   | yes  | REMOTE (CPU only)                |
| macOS               | no   | yes  | REMOTE (CPU only)                |
| Windows (MSVC)      | no   | yes  | REMOTE (CPU only)                |

CUDA is detected automatically at configure time. When CUDA is unavailable, the client still works over gRPC in `REMOTE` mode.

## Prerequisites

Complete the [Prerequisites](/prerequisites) for your deployment type before continuing:

* **Colocated** — Client and worker run on the same machine. Install GPU drivers, Docker, and the NVIDIA Container Toolkit as described on the prerequisites page.
* **Non-colocated** — Client and worker run on different machines. The client does not require a GPU. Install the OS-specific build dependencies listed in the platform sections below.

## Clone the AODT repository

Clone AODT 1.5.0 from GitHub:

```bash
git clone https://github.com/NVIDIA/aerial-omniverse-digital-twin.git aodt_1.5.0
```

This creates an `aodt_1.5.0` directory at the clone path. All commands in this documentation use `aodt_1.5.0` as the package root, with component paths underneath it:

```
aodt_1.5.0/
├── client/    # Client library and examples
├── worker/    # Worker stack and Docker Compose files
└── viewer/    # Web viewer application
```

Note the full path to `aodt_1.5.0` on your system — subsequent commands assume you are working from that package root or its subdirectories.

## Choose an installation path

| Path             | Best for                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Container**    | Fastest setup on Linux or WSL2 when Docker is available                                                             |
| **Source build** | Native Linux, macOS, or Windows installs, custom integration, development workflows, or environments without Docker |

Use a source build if any of the following apply:

* You are installing the client natively on macOS or Windows
* Docker is not available on your system
* You are integrating AODT into your own application
* You need a development environment for modifying client code

If you need a source build, skip to [Source build on Linux](#source-build-on-linux) or the section for your platform.

## Quickstart via container

On Linux or WSL2, the development container is the fastest way to build and run the client when Docker is available. The image includes all build and runtime dependencies.

```bash
cd aodt_1.5.0

# Open an interactive shell inside the container
./container/run.sh

# Or build the client directly
./container/run.sh cmake -B client/build -DCMAKE_BUILD_TYPE=Release client/
./container/run.sh cmake --build client/build -j$(nproc)
```

No additional client setup is required after a successful container build.

### Verify the container installation

The client cannot be exercised until the worker is running. After completing [Worker Installation](/worker-installation), follow [Verify Installation — colocated container test](/verify-installation#1-colocated-container-test).

## Source build on Linux

Use this path to install the client directly on your system. It is the recommended approach for development workflows.

### Install dependencies

From the `client/` directory:

```bash
sudo apt-get update
sudo apt-get install -y cmake protobuf-compiler-grpc libgrpc++-dev pkg-config python3-dev python3-venv
python3 -m venv .venv
source .venv/bin/activate
pip install pybind11 pyyaml omegaconf pytest numpy
```

### Optional: CUDA toolkit

CUDA is optional. When present, it enables CUDA IPC for colocated `LOCAL_IPC` transport. Without CUDA, the client remains fully usable over gRPC.

To enable CUDA for colocated deployments:

```bash
# Install NVIDIA driver (skip if already installed — check with nvidia-smi)
# Use apt-cache search nvidia-driver to list available versions.
# Install using the driver series number (e.g. nvidia-driver-535).
# Do NOT supply a patch-level version number like 590.48.01.
sudo apt-get install -y nvidia-driver-<driver-series>
sudo reboot
```

```bash
# Install CUDA Toolkit (example for Ubuntu 22.04)
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install -y cuda-toolkit
```

Verify with `nvidia-smi` and `nvcc --version`. See the [CUDA compatibility guide](https://docs.nvidia.com/deploy/cuda-compatibility/) for driver and toolkit version requirements.

### Build

From the `client/` directory:

```bash
source .venv/bin/activate
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
cmake --build build -j$(nproc)
```

The configure step prints a summary of detected features:

```
=== Digital Twin Client Build Configuration ===
  CUDA:       YES
  Compiler:   GNU
  Platform:   Linux
===============================================
```

### Use the Python client

You can run the Python bindings in two ways:

**Option 1 — Without installing (development)**

```bash
source .venv/bin/activate
export PYTHONPATH=build/:build/config/
python3 examples/example_client.py
```

**Option 2 — System-wide install**

```bash
sudo cmake --install build
```

After installation, `import dt_client` and `import _config` work from any directory without setting `PYTHONPATH`.

### Use the C++ client

From the `client/` directory:

```bash
./build/dt_client_example --server localhost:50051
```

Replace `localhost:50051` with the worker address for non-colocated deployments.

### Verify the installation

The worker must be running before you test the client. Follow [Verify Installation — colocated source build test](/verify-installation#2-colocated-source-build-test).

## Source build on WSL2

WSL2 follows the same build steps as Linux.

### Install dependencies

From the `client/` directory inside WSL2:

```bash
sudo apt-get update
sudo apt-get install -y cmake protobuf-compiler-grpc libgrpc++-dev pkg-config python3-dev python3-venv
python3 -m venv .venv
source .venv/bin/activate
pip install pybind11 pyyaml omegaconf pytest numpy
```

No WSL2-specific transport configuration is required beyond network reachability to the worker address.

### Build and run

```bash
source .venv/bin/activate
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
cmake --build build -j$(nproc)

export PYTHONPATH=build/:build/config/
python3 examples/example_client.py
```

## Source build on macOS

### Install dependencies

```bash
brew install grpc protobuf cmake pkg-config
python3 -m venv .venv
source .venv/bin/activate
pip3 install pybind11 pyyaml omegaconf pytest numpy
```

### Build and run

From the `client/` directory:

```bash
source .venv/bin/activate
cmake -B build -DCMAKE_BUILD_TYPE=Release -DPython3_EXECUTABLE=$(which python3) .
cmake --build build -j$(nproc)

export PYTHONPATH=build/:build/config/
python3 examples/example_client.py
```

macOS uses gRPC for request, control, and remote memory transfer. CUDA IPC and `LOCAL_IPC` mode are not supported.

## Source build on Windows (MSVC)

### Install dependencies

* **Visual Studio 2022** with the "Desktop development with C++" workload, or **Visual C++ Build Tools** from [visualstudio.microsoft.com/visual-cpp-build-tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
* **CMake** from [cmake.org/download](https://cmake.org/download/) — select "Add CMake to system PATH" during installation
* **Git** from [git-scm.com/download/win](https://git-scm.com/download/win)

Install vcpkg and C++ dependencies:

```powershell
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
.\vcpkg install grpc protobuf yaml-cpp pybind11
```

Set up Python. vcpkg installs its own Python — the built modules are only compatible with that Python:

```powershell
<vcpkg-root>\installed\x64-windows\tools\python3\python.exe -m ensurepip --upgrade
<vcpkg-root>\installed\x64-windows\tools\python3\python.exe -m pip install pyyaml omegaconf pytest numpy
```

Add vcpkg's Python to your PATH:

```powershell
$env:PATH = "<vcpkg-root>\installed\x64-windows\tools\python3;<vcpkg-root>\installed\x64-windows\tools\python3\Scripts;$env:PATH"
```

### Build and run

From the `client/` directory:

```powershell
cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>\scripts\buildsystems\vcpkg.cmake -DCMAKE_PREFIX_PATH=<vcpkg-root>\installed\x64-windows .
cmake --build build --config Release
```

```powershell
$env:PATH = "..\vcpkg\installed\x64-windows\tools\python3;$env:PATH"
$env:PYTHONPATH = "build\Release;build\config\Release"
python examples\example_client.py
```

Windows uses gRPC for request, control, and remote memory transfer. CUDA IPC and `LOCAL_IPC` mode are not supported.

## Next steps

After the client is installed and verified:

1. Complete [Worker Installation](/worker-installation) if you have not already started the worker.
2. Install the [Viewer](/viewer-installation) to visualize simulation results.
3. Follow the [Quickstart](/quickstart) guide to run your first simulation.