Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation — Docker (Recommended)

Using SRB inside Docker is recommended for most users, as it provides an isolated, reproducible environment that is fully pre-configured.

1. Clone the Repository

First, clone the SRB repository with all submodules:

git clone --recurse-submodules https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench

If you prefer not to use git submodules, you can clone normally and then initialize asset repos from a Hugging Face mirror:

git clone https://github.com/AndrejOrsula/space_robotics_bench.git
cd space_robotics_bench
./assets/update.bash --source hf --repo-id <owner>/<repo>
./assets/update.bash --source hf --repo-id <owner>/<graphics-repo> --path docs/src/_graphics

2. Install Docker Engine & NVIDIA Container Toolkit

  1. Official instructions: Install Docker Engine
  2. Official instructions: Linux post-installation steps for Docker Engine
  3. Official instructions: Installing the NVIDIA Container Toolkit

For the standard interactive SRB workflow, your host should also have:

  • a working NVIDIA driver with nvidia-smi
  • xauth installed if you want Isaac Sim GUI forwarding (sudo apt-get install -y xauth)
  • an X11 session with DISPLAY set if you want GUI windows from the container

Install Docker Engine and NVIDIA Container Toolkit either by following the official instructions above or using the provided convenience script:

./.docker/host/install_docker.bash

If the installer adds your user to the docker group, start a new login session before relying on passwordless docker commands. Until then, the SRB helper scripts automatically fall back to sudo docker ... when needed.

3. Run

Build the repository’s local image, then run it with the provided script:

./.docker/build.bash
./.docker/run.bash

The normal runner resolves the local tag to its immutable image ID. It does not fall back to a remote tag. The default safe profile starts an interactive container with isolated networking and IPC, dropped capabilities, no host devices, and no host mounts. This profile is suitable for lightweight commands that do not need Isaac Sim host integration:

DOCKER_TTY=false ./.docker/run.bash srb --help

To use an already reviewed remote release, supply its complete registry digest; mutable tags are rejected:

SRB_DOCKER_IMAGE='<registry>/<image>@sha256:<64-hex-digest>' ./.docker/run.bash srb --help

Isaac Sim development needs host-adjacent access. Select that trust boundary explicitly:

SRB_DOCKER_PROFILE=trusted-simulator ./.docker/run.bash

The trusted simulator profile enables privileged mode, host networking and IPC, /dev, writable simulator caches, GUI forwarding, command history, and a writable /root/ws source mount by default. Use it only with a locally trusted image or an authenticated digest.

Useful variants:

# Headless trusted simulator session
SRB_DOCKER_PROFILE=trusted-simulator WITH_GUI=false ./.docker/run.bash

# CPU / non-GUI trusted development path
SRB_DOCKER_PROFILE=trusted-simulator WITH_GPU=false WITH_GUI=false ./.docker/run.bash

# Trusted simulator without writable source or shell history
SRB_DOCKER_PROFILE=trusted-simulator WITH_DEV_VOLUME=false WITH_HISTORY=false ./.docker/run.bash

# Force-enable NVIDIA runtime detection if host probing is incomplete
SRB_DOCKER_PROFILE=trusted-simulator WITH_GPU_FORCE_NVIDIA=true ./.docker/run.bash

# Non-interactive command execution, for CI/log capture/agent smoke tests
DOCKER_TTY=false ./.docker/run.bash bash -lc "srb --help"

To attach from another terminal while the container is still running:

./.docker/join.bash

Both run.bash and join.bash also accept a trailing command. Example:

SRB_DOCKER_PROFILE=trusted-simulator ./.docker/run.bash latest bash
./.docker/join.bash 0 fish

4. Verify Installation

Once you enter the Docker container, verify that everything works as expected. If you encounter any issues, please refer to the Troubleshooting guide.

Isaac Sim

Confirm that the container sees your GPU:

nvidia-smi

Confirm that you can launch Isaac Sim:

"$HOME/isaac-sim/isaac-sim.sh"

Note: The first launch might take a while because Isaac Sim needs to compile shaders and prepare the environment.

Space Robotics Bench

Verify that the srb command is available:

srb --help
srb cache update

GUI Forwarding

If you expect GUI access, also verify:

echo "$DISPLAY"
test -n "$XAUTHORITY" && ls -l "$XAUTHORITY"

… continue with Basic Usage

Extras

Build a New Docker Image

If you want to build a custom Docker image, you can use the provided script:

./.docker/build.bash

Join a Running Container

To join a running container from another terminal, use the provided script:

./.docker/join.bash

Development

The repository workspace is mounted by the explicit trusted simulator and development profiles, so edits made there persist on the host. The safe profile does not mount the checkout.

To improve your development experience, you can open the project as a Dev Container (guide).

For extra development-only environment variables or additional bind mounts, use ./.docker/dev.bash, which wraps ./.docker/run.bash and explicitly selects trusted-simulator. It prints a security warning before launch. The development wrapper defaults to LOG_LEVEL=info to keep Isaac and SimForge startup logs readable; use LOG_LEVEL=debug ./.docker/dev.bash ... when you need verbose diagnostics.

The development wrapper also persists Rust build caches across disposable containers. By default, host-side Cargo registry, git, and target caches live under ~/.cache/space_robotics_bench/docker, while container builds use CARGO_TARGET_DIR=/root/.cache/srb/cargo-target so prebuilt image artifacts in /root/.cargo/target remain visible. Override the host cache root with SRB_DOCKER_CACHE_DIR=/path/to/cache ./.docker/dev.bash ...; override the in-container target path with SRB_CARGO_TARGET_DIR=/path/in/container ./.docker/dev.bash ..., but do not set it to /root/.cargo/target.