Run POSIM with Docker

1. Understand which image you are using

Status checked 2026-10-01: the images below are public validation candidates, not a POSIM 1.0 release. They come from PR #5, which is still unmerged. They include candidate runtime fixes absent from main and do not include WGPU from PR #6 or WAM-V from PR #7.

These are separate architecture-specific tags, not a single cross-architecture tag. latest, main-amd64, main-arm64-rdp and versioned release tags were not published in this validation. Do not substitute one of those names.

Install Docker using the official instructions for Ubuntu or macOS. Check docker version and docker info before continuing. Use Bash or zsh on the host; on Windows, use a WSL shell with Docker Linux-container support. The Windows host path was not part of the 2026-09-30 native-architecture checks. Docker Desktop on Apple Silicon runs Linux in a VM; it is not native macOS execution and does not expose the Mac's Metal backend to this Linux image.

2. Select one architecture and pull the pinned image

Host terminal: choose only one of the following blocks.

The tag names above are convenient labels. The commands below use immutable registry digests so that you obtain the exact published candidate.

Apple Silicon / Linux ARM64:

export POSIM_PLATFORM=linux/arm64
export POSIM_IMAGE=ioeslab/posim@sha256:72179187c96a801184a15ab9cdaf3ca9714d3717ce04e97cd2ec60f34d83edb8
docker pull --platform "$POSIM_PLATFORM" "$POSIM_IMAGE"

Linux AMD64 / x86-64:

export POSIM_PLATFORM=linux/amd64
export POSIM_IMAGE=ioeslab/posim@sha256:9783525a2a18ecc2e275e9af43e82ccab6202bb99b63790ffd165d8885fa9784
docker pull --platform "$POSIM_PLATFORM" "$POSIM_IMAGE"

Use the native host architecture where possible. AMD64 execution on an ARM64 host requires emulation and is not equivalent to native AMD64 performance. The images are large: check available Docker disk space before pulling.

3. Open an isolated shell

Host terminal: start the container. This terminal becomes Terminal A.

docker run --rm -it --init --name posim-quickstart \
  --platform "$POSIM_PLATFORM" --shm-size=1g \
  --entrypoint bash \
  -e LIBGL_ALWAYS_SOFTWARE=1 -e QT_QPA_PLATFORM=offscreen \
  -e GZ_IP=127.0.0.1 "$POSIM_IMAGE"

If a container named posim-quickstart already exists, choose another name; do not delete an unrelated container. No host directory is mounted, no Docker socket is exposed, and no RDP port is opened by this command. Exiting the shell removes this disposable container, so copy out any files you want to keep first.

Inside the container, load the installed environments explicitly:

source /opt/ros/lyrical/setup.bash
export POSIM_WS="${DAVE_WS:-${DAVE_UNDERLAY:-}}"
if [ -z "$POSIM_WS" ] || [ ! -r "$POSIM_WS/install/setup.bash" ]; then
  echo "POSIM workspace not found. Check the image before continuing." >&2
  exit 1
fi
source "$POSIM_WS/install/setup.bash"
cd /tmp
printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"
gz sim --versions
ros2 pkg prefix dave_demos