Setup

Get the simulator running on macOS, Linux, or Windows

You need two tools installed; everything else (world geometry, the Docker image, the ROS build) is provisioned automatically on first start:

• Docker — runs the robot’s software stack in a container.
• uv — runs the physics world natively on your machine (./innate-sim setup offers to install this one for you).

A machine with 4 CPU cores and 8 GB of RAM is comfortable. The first start downloads and builds a few GB, so it takes a while; later starts take seconds.

Install the prerequisites

macOS

Install Docker Desktop and start it:

brew install --cask docker

(or download it from docker.com).

Linux (Ubuntu / Debian / Raspberry Pi OS)

Use Docker’s own install script — it sets up the official apt repo and installs Docker plus the Compose v2 plugin, the same way on every Debian-family distro:

curl -fsSL https://get.docker.com | sudo sh

Then let your user talk to Docker:

sudo usermod -aG docker $USER && newgrp docker

Install the rendering libraries. On a headless server or VM these provide offscreen rendering; on a desktop with working OpenGL they’re mostly already present, and the extra software-rendering library is harmless — so it’s safe to run either way:

sudo apt install libegl1 libgl1 libopengl0 libosmesa6

Windows (WSL2)

The simulator runs inside WSL2. In PowerShell:

wsl --install -d Ubuntu

then open the Ubuntu terminal and follow the Linux tab inside it. WSLg (included in current WSL) gives the simulator GPU-accelerated rendering automatically.

Use exactly one Docker — either Docker Desktop (with WSL integration enabled) or docker.io installed inside WSL. Having both installed makes the docker command hang in confusing ways.

Start the simulator

1. Clone innate-os

   git clone https://github.com/innate-inc/innate-os.git
   cd innate-os
   
2. Run setup once

   ./innate-sim setup
   

   This checks the prerequisites (and offers to install uv if it is missing), then asks which brain — the robot’s AI agent — to run. The agent is the open-source innate-cloud-agent; the choice is only about where it runs:

   • Local brain (Gemini) — the default. Clones innate-cloud-agent and runs it on your machine against a Gemini API key. Everything works except voice: the web app’s speak bar is disabled without a service key.
   • Hosted Innate brain — the same agent, run on Innate’s servers with your Innate service key (it ships with a MARS robot). The full experience, including voice — the robot speaks.
   • None — no agent; you can still drive, navigate, and trigger skills manually.

   Rerun ./innate-sim setup anytime to switch.

3. Bring it up

   ./innate-sim up
   

   The first run provisions everything and shows its progress; leave the live dashboard open. Later runs start in seconds.

4. Open the web app

   Go to https://localhost and accept the self-signed certificate. This is the robot’s own web app — the same one a physical MARS serves.

   

Everyday commands

./innate-sim status      # startup checks + health snapshot
./innate-sim logs        # startup logs; `logs os` / `logs agent` follow live
./innate-sim sh          # shell into the container
./innate-sim down        # stop the container + world server (keeps data)
./innate-sim clean       # remove containers/volumes (keeps .env + config)

If something goes wrong

Every error the launcher prints is written to tell you exactly what to do next — missing packages come with the install command, a wedged Docker names itself, and the startup checks end with a health panel that includes the world server and its measured render speed. If you get stuck anyway, ask on Discord — setup reports from new machines are how the rough edges get fixed.

Next step

Building with the Simulator

Write your first skill, hand it to an agent, and iterate against the simulated MARS.