Skip to main content
Running Ubuntu natively on an x86_64 machine is the recommended setup for best performance.Supported versions:
  • Ubuntu 20.04 (Focal)
  • Ubuntu 22.04 (Jammy) — recommended
  • Ubuntu 24.04 (Noble)
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

You’ll see the welcome screen with an interactive prompt:
First time launching from a fresh directory, Drift will nudge you to run /init — that’s the project-context bootstrap (see Step 3).

​
Step 3: 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 4: Set up your simulator

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

​
Step 5: 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 6: 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