Installation
Choose the installation method for your operating system. Each method below links to its instructions on this page.
Choose a package
| Operating system | Installation method | Simulation engine |
|---|---|---|
| Apple Silicon · macOS 27 or later | Install from DMG · Install with Homebrew | Native ROS 2 · Gazebo · Metal |
| Ubuntu 26.04 · x86-64 | APT repository · Install from DEB | Linux engine in Docker |
| Windows · x86-64 | Windows installation | Docker Desktop · WSL2 |
Windows installation
Set up WSL2
If WSL is not installed, open Terminal or PowerShell as administrator from the Start menu and run:
wsl --install --no-distribution
Restart the computer when requested. Open a new terminal and run:
wsl --update
wsl --set-default-version 2
wsl --status
Check that the default version is 2. For virtualization errors, check hardware virtualization in your firmware settings and follow Microsoft’s WSL installation guide. Docker Desktop uses its own WSL2 environment. The installed app does not need a separate Ubuntu distribution; add one only if you want a separate ROS environment.
Install Docker Desktop and the app
- Install Docker Desktop. Follow its WSL2 setup and restart your computer if requested. Docker provides the Linux environment used by the simulator.
- Open Docker Desktop and wait until it says the engine is running.
- Download the Windows installer, open it and follow the installer steps. If Windows displays Windows protected your PC, select More info → Run anyway for the official WWW-POSIM download. The current Windows package has no Authenticode signature; its published SHA-256 checksums identify the release file.
- Open WWW-POSIM from the Start menu. If the same first-launch warning appears for the app, select More info → Run anyway again. Sign in and select Start simulator.
- Your browser opens the local simulator. Continue with Workspace basics.
Keep Docker Desktop running while using the app. The app selects and downloads its matching simulator images automatically.
Install from DMG
Use an Apple Silicon Mac with macOS 27 or later. Check Apple menu → About This Mac if you do not know your model or macOS version.
- Download the Mac DMG.
- Open the downloaded file. Drag WWW-POSIM onto Applications.
- Try opening WWW-POSIM from Applications. The app uses an ad-hoc signature and is not Apple-notarized.
- If macOS blocks this first launch, open System Settings → Privacy & Security, scroll to Security, and select Open Anyway beside WWW-POSIM. Select Open in the confirmation and authenticate if macOS asks. This follows Apple's first-launch instructions.
- Sign in and select Start simulator. The first start downloads the matching simulator files in resumable 512 MiB parts, verifies them, then unpacks the engine. Watch download and unpacking progress.
- When your browser opens, continue with Workspace basics.
The Mac app downloads its pinned ROS environment once and uses Metal for graphics. Every installer and data part is below 2 GiB. Downloads and the prepared engine are cached outside the app for later starts.
For a blocked or stalled launch, follow Mac launch recovery.
Install with Homebrew
If Homebrew is not installed, follow its official installation instructions. Then install WWW-POSIM:
brew tap ioes-lab/www-posim
brew trust --cask ioes-lab/www-posim/www-posim
brew install --cask ioes-lab/www-posim/www-posim
The Homebrew trust command permits loading this application's named Cask from the selected tap.
If Homebrew requests packages.arm64_dunno.jws.json and receives HTTP 404, its macOS version table does not recognize macOS 27. Update Homebrew without its package API, then repeat the installation:
HOMEBREW_NO_INSTALL_FROM_API=1 brew update
HOMEBREW_NO_AUTO_UPDATE=1 brew tap ioes-lab/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew trust --cask ioes-lab/www-posim/www-posim
HOMEBREW_NO_AUTO_UPDATE=1 brew install --cask ioes-lab/www-posim/www-posim
These environment variables apply only to each command. See Homebrew’s environment options. If Homebrew still fails, use the DMG above to install the same application.
Open the app and use the same email account as the website.
- Account server: connected automatically
- First run: verified engine parts downloaded, assembled and extracted into Library
- Progress: login, verification, unpacked size / total, percentage and estimated remaining time, then service startup
- Simulation: Gazebo, ROS 2 and Autopilot run on your Mac
- Rendering: local GPU through Metal
- Updates: choose Update to VERSION
You can keep using the installed engine when an update is available. The update notice does not interrupt a running simulation.
To use local ROS code, load the bundled environment in each terminal:
eval "$(/Applications/WWW-POSIM.app/Contents/MacOS/WWW-POSIM --ros-env)"
Continue with Control an installed workspace. The app includes the connector, standard ROS messages and RViz2. Use Open ROS terminal and Open RViz in the app. Add your own algorithm's dependencies to a compatible environment.
Prepare Docker on Ubuntu
Install Docker and the download tools first. After granting your account Docker access, log out and back in.
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
APT repository
Install the signed APT source from the platform's stable address.
SERVER=https://www-posim.vercel.app
curl -fSL "$SERVER/guide/packages/apt/www-posim-archive-keyring.gpg" | \
sudo tee /usr/share/keyrings/www-posim-archive-keyring.gpg >/dev/null
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/www-posim-archive-keyring.gpg] $SERVER/guide/packages/apt stable main" | \
sudo tee /etc/apt/sources.list.d/www-posim.list
sudo apt update
sudo apt install www-posim
www-posim
You can also download the DEB and install it with sudo apt install ./www-posim_*_amd64.deb.
- Docker: available to your user account
- Engine images: selected automatically for the installed app version
- GPU rendering: drivers and container runtime compatible with those images
Install from DEB
The Linux app supports Ubuntu 26.04 on an x86-64 computer. Press Ctrl+Alt+T to open a terminal. Copy this block, paste it into the terminal and press Enter:
sudo apt update
sudo apt install -y docker.io curl
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
mkdir -p ~/Downloads
cd ~/Downloads
curl -fL -o www-posim.deb https://www-posim.vercel.app/guide/packages/latest/linux-amd64.deb
sudo apt install ./www-posim.deb
- Enter your computer's password when
sudoasks. Characters do not appear while you type. - Log out of Ubuntu and log back in. This enables Docker access for your account.
- Open WWW-POSIM from the application menu, or run
www-posimin a new terminal. - Sign in and select Start simulator.
- When your browser opens, continue with Workspace basics.
Does Docker require Ubuntu 26.04?
Docker Engine supports Ubuntu 24.04 and 22.04 as well. The Ubuntu and ROS versions inside a container do not have to match the host. However, the published WWW-POSIM DEB and installation script target Ubuntu 26.04, and the launcher binary has host system-library requirements. This DEB is therefore supported on 26.04. Docker support on an older host does not establish compatibility with the WWW-POSIM installer. See Docker’s supported Ubuntu versions.
Verify your account and start learning
Create your account on Installation. Open the verification email and select Verify email, then sign in to the app. Check spam if the email is missing. The app can save your password in the operating system's credential store after successful verified login.
An internet connection is needed for login and periodic usage permission checks. Prepare disk space for the engine, maps and models.
Next: Workspace basics, then Control an installed workspace. Create Python project adds examples to your saved working directory, initially Documents/WWW-POSIM. Use Open ROS terminal, Open working directory and Open in VS Code to work in that folder with prepared ROS tools.
Select a graphics device
Graphics in local settings defaults to Automatic (recommended). The app checks an actual EGL graphics device inside the engine container. Windows NVIDIA systems use the WSL D3D12 path. If no hardware renderer is available, the app uses CPU rendering and displays the reason.
GPU required stops startup if the GPU check fails. Software (CPU) selects CPU rendering. Linux NVIDIA systems need compatible drivers and NVIDIA Container Toolkit. The default Mac engine uses Metal.
The Windows Docker engine uses the WSL2 backend. The simulator, Open ROS terminal and Open RViz use the app-prepared environment. A separate Ubuntu distribution and ROS installation are needed only for a Connect your ROS environment to a web workspace. Install the NVIDIA driver on Windows.
The installed workspace scene is rendered by local Gazebo Ogre2. Drag to orbit the observer camera and scroll to zoom. The view displays a waiting state when frames are missing or stale.
Accounts and storage
Register with your email on the platform. The installed simulator checks running-time permissions with the account server, so an internet connection is needed for login and periodic renewal. Prepare disk space for the engine, downloaded terrain and custom models. Account upload limits and free space on your computer are separate.
After signing in, select a real region and robot in Workspace basics. Ending the session returns the server slot or stops the local engine.
Updates
When a newer release is available, the launcher and standalone simulator show a red update banner with the installed and available versions. Choose Update now for installation instructions in the simulator, or to start the verified download in the launcher. Close the simulator banner with × to hide it for that browser tab; a newer release appears again.
End the simulation, then update using one of these methods.
- App: Update to VERSION
- Homebrew:
brew upgrade --cask www-posim - APT:
sudo apt update && sudo apt upgrade - Direct installation: download and install the current package
The Mac updater verifies the download and signature before replacement. If the engine matches, only app files are downloaded. Models, terrain caches and projects outside the app are retained.
For a separate ROS workstation, prepare the connector wheel and a compatible ROS environment. See Control an installed workspace.
Release engine images
The app automatically downloads matching engine and workbench images from Docker Hub for its installed version. These public images require no registry login or image URL entry. The native Mac package downloads its matching engine as verified release-file parts; it does not use Docker images. You can also pull the images in advance:
docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker.io/ioeslab/www-posim-web:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-engine:0.6.15-amd64
docker pull docker.io/ioeslab/www-posim-web:0.6.15-amd64
Mac launch recovery
The first-launch warning can appear after downloading or replacing the app because this distribution has no Apple notarization. Use Open Anyway as described above. An unresponsive button or an app that stays in the Dock without opening a window can also require recovery of macOS's app-validation service.
Quit WWW-POSIM before recovery. Use Apple menu → Force Quit for a stuck launcher only when no simulation is running. Restarting your Mac and opening the app again is the simplest recovery option.
For recovery without restarting your Mac, verify that the DMG comes from the official download above and matches its published SHA-256 checksum. Run shasum -a 256 followed by the downloaded DMG's path to calculate its checksum. An ad-hoc signature checks file integrity; it does not establish the publisher's identity.
Download the Mac recovery helper into Downloads. Open Terminal and inspect the installed app:
bash "$HOME/Downloads/recover_macos_launch.command"
The default check verifies the app identity and signature and reports its download quarantine flag. To repair a blocked launch, run:
bash "$HOME/Downloads/recover_macos_launch.command" --repair --restart-validation
Read the prompt and type TRUST WWW-POSIM to allow this app to run despite Apple's verification warning. The helper clears quarantine only from the selected app, restarts macOS's app-validation service and requests launch. Enter your Mac password locally when sudo asks. Gatekeeper stays enabled. Confirm that the launcher window appears; a launch request alone does not establish success.
Use --repair alone if Open Anyway responds normally and the validation service does not need restarting. For the Dev app, add --app "/Applications/WWW-POSIM Dev.app". The DMG also includes the same helper beside its README. You can run that file with bash and its path instead of downloading it.
For manual recovery of the same blocked-launch condition, run these commands in Terminal after quitting the app and checking the official DMG's checksum. Continue past the integrity check only if it succeeds and you trust the app:
codesign --verify --deep --strict "/Applications/WWW-POSIM.app"
xattr -dr com.apple.quarantine "/Applications/WWW-POSIM.app"
sudo /usr/bin/killall -TERM syspolicyd
open -a "/Applications/WWW-POSIM.app"
Restarting the validation service affects pending security checks for other apps, whose launches may need retrying. If recovery fails, restart your Mac. If the signature check fails, download a fresh official installer.