Skip to main content
Running Ubuntu natively on an x86_64 machine is the recommended setup for best performance.Pick your Ubuntu version to match the ROS2 distribution you want — each ROS2 release targets exactly one:
Ubuntu 20.04 (Focal) has no supported ROS2 distribution. Humble requires 22.04 and Jazzy requires 24.04; the only distro that shipped for 20.04 was Foxy, which is end-of-life and unsupported. The MuJoCo workflow doesn’t need ROS2 and will still work on 20.04, but every Gazebo/ROS2 path in these docs assumes 22.04 or 24.04.
Use your system terminal (GNOME Terminal, Konsole, any terminal emulator), or the integrated terminal in VS Code or Cursor.

​
Step 1: Install Drift CLI

Once complete, restart your terminal or source your shell config:
Verify the installation:
Download the latest .deb package from the GitHub Releases page and install it with:
Then run drift to start.

​
Step 2: Launch Drift

​
Step 3: Sign in with Google

The first time you run Drift, it prints a Google Sign-In URL. Signing in is required — Drift won’t take a prompt until you do.
  1. Open the URL Drift printed in your browser
  2. Complete Google Sign-In
  3. Drift detects it automatically and drops you at the prompt
Drift waits up to 5 minutes for you to finish. If the link doesn’t open, copy the whole URL into your browser by hand. Once you’re in, you’ll see the interactive prompt:
You can check who you’re signed in as at any time with /profile, and sign in again later with /login. If you ever see “Authentication required”, your session has expired — run /login. See Troubleshooting if the login flow gives you trouble. First time launching from a fresh directory, Drift will nudge you to run /init — that’s the project-context bootstrap (see Step 4).

​
Step 4: Give Drift project context with /init

The single most useful thing you can do before your first real prompt:
Drift scans your workspace (URDFs, package.xml files, launch scripts, scene files, READMEs) and writes a starter DRIFT.md at the project root with:
  • A summary of your robot and project
  • Detected ROS2 packages and dependencies
  • Build and launch conventions
Open it, edit it to taste — add topic names, frame_id conventions, special build flags, your team’s naming rules. Every subsequent prompt will use this file as ground truth, so you stop re-explaining your project on every command.
Already have a CLAUDE.md from Cursor / Claude Code? Drift reads that too — no migration needed.

​
Step 5: Set up your simulator

Pick what you need:
Check what’s installed:
If either is missing, ask Drift to install both:

​
Step 6: Build your first simulation

At the drift> prompt, describe what you want in plain English:
Drift plans and executes each step, printing progress as it goes. If a build step fails, Drift diagnoses the error and retries before surfacing it to you.

​
Step 7: Launch and iterate

Launch the simulation (Gazebo path):
Or open the MuJoCo viewer if you took the MuJoCo path:
Then keep going. Each follow-up triggers only the necessary rebuilds — no starting over:
  • add a lidar sensor to my robot and rebuild
  • add a second obstacle box at (1, -1) in the scene
  • why isn't my camera publishing images?
  • show me the running processes

​
Pro tips

Vague prompts produce generic results. Instead of:
Try:
The more detail about robot type, sensors, environment, and task — the better the output.
Before modifying a simulation, ask Drift to inspect what’s already there:
This helps Drift make targeted changes and avoids unnecessary rebuilds.
When something breaks, describe the symptom directly:
Drift checks topics, logs, URDF / MJCF config, and process state to give you a diagnosis.
If your team has a specific way of tuning SLAM, calibrating an IMU, or writing a Gazebo plugin, write it down as a markdown file and:
Drift will use that skill from then on. See Custom Skills for the full pattern.

​
Useful slash commands

​
What’s next?

Robot Showcase

Full walkthroughs with Unitree Go2, Aloha, and Unitree H1

Your First Simulation

A detailed walkthrough of building a complete simulation from scratch

Project Context

The full DRIFT.md workflow

Custom Skills

Hand your team’s expertise to Drift

​
Getting help