> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godrift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Go from zero to a running robotics simulation in under 5 minutes

### Recommended setup

<Tabs>
  <Tab title="Ubuntu (Native)">
    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.
  </Tab>

  <Tab title="macOS (via VMware)">
    Drift runs on Ubuntu only, but macOS users can run it inside a Ubuntu virtual machine using [VMware Fusion](https://www.vmware.com/products/fusion.html).

    **Setup steps:**

    1. Download and install [VMware Fusion](https://www.vmware.com/products/fusion.html) (free for personal use)
    2. Create a new VM with **Ubuntu 22.04** (x86\_64 image)
    3. Allocate at least **8GB RAM** and **4 CPU cores** for the simulator to run smoothly
    4. Install ROS2 and Gazebo (and/or MuJoCo) inside the VM following the official guides
    5. Follow the Drift install steps below inside the VM terminal

    <Note>
      On Apple Silicon (M1/M2/M3), VMware Fusion runs an ARM Ubuntu image by default. Select an **x86\_64 Ubuntu image** when creating the VM so Drift's binary is compatible.
    </Note>
  </Tab>
</Tabs>

## Step 1: Install Drift CLI

```bash theme={null}
curl -fsSL https://godrift.ai/install | bash
```

Once complete, restart your terminal or source your shell config:

```bash theme={null}
source ~/.bashrc  # or ~/.zshrc
```

Verify the installation:

```bash theme={null}
drift --help
```

<Accordion title="Prefer a manual install?">
  Download the latest `.deb` package from the [GitHub Releases page](https://github.com/godrift-ai/drift-releases/releases) and install it with:

  ```bash theme={null}
  sudo dpkg -i drift-cli_*_amd64.deb
  ```

  Then run `drift` to start.
</Accordion>

## Step 2: Launch Drift

```bash theme={null}
cd your-project
drift
```

You'll see the welcome screen with an interactive prompt:

```
🚀 Welcome to Drift CLI

   Your copilot for robotics simulations

drift>
```

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 theme={null}
/init
```

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.

<Tip>
  Already have a `CLAUDE.md` from Cursor / Claude Code? Drift reads that too — no migration needed.
</Tip>

## Step 4: Set up your simulator

Pick what you need:

<Tabs>
  <Tab title="Gazebo Harmonic (for ROS2)">
    Check what's installed:

    ```bash theme={null}
    ros2 --version
    gz sim --version
    ```

    If either is missing, ask Drift to install both:

    ```drift theme={null}
    install ROS2 Humble and Gazebo Harmonic, then verify they work
    ```
  </Tab>

  <Tab title="MuJoCo (for fast, scriptable sims)">
    MuJoCo is great when you want a fast, headless-friendly simulator that doesn't require ROS2 in the loop — robotics RL training, contact-rich tasks, pure dynamics work.

    ```bash theme={null}
    pip install mujoco
    python3 -c "import mujoco; print(mujoco.__version__)"
    ```

    Drift supports MuJoCo 3.8.1+. If you don't have it, ask Drift to set it up:

    ```drift theme={null}
    install MuJoCo and verify it imports
    ```
  </Tab>
</Tabs>

## Step 5: Build your first simulation

At the `drift>` prompt, describe what you want in plain English:

<Tabs>
  <Tab title="Gazebo">
    ```drift theme={null}
    create a pick-and-place robot simulation in Gazebo
    ```
  </Tab>

  <Tab title="MuJoCo">
    ```drift theme={null}
    set up a Unitree Go2 from mujoco_menagerie on a flat floor scene,
    write a PD controller that holds the default standing keyframe on
    all 12 joints, run 5 seconds headless, and log joint positions,
    IMU, and foot contacts to a CSV
    ```

    Drift will clone Menagerie if you don't have it. See the [Robot Showcase](/showcase/quadruped-go2) for the full Go2 walkthrough.
  </Tab>
</Tabs>

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):

```drift theme={null}
launch my robot with the world file
```

Or open the MuJoCo viewer if you took the MuJoCo path:

```drift theme={null}
open the scene I built in the MuJoCo viewer
```

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

<AccordionGroup>
  <Accordion title="Be specific in your prompts">
    Vague prompts produce generic results. Instead of:

    ```drift theme={null}
    make a robot
    ```

    Try:

    ```drift theme={null}
    create a 6-DOF manipulator arm with a two-finger gripper, a table
    workspace, and a depth camera mounted on the wrist
    ```

    The more detail about robot type, sensors, environment, and task — the better the output.
  </Accordion>

  <Accordion title="Let Drift explore before changing things">
    Before modifying a simulation, ask Drift to inspect what's already there:

    ```drift theme={null}
    what topics are being published?
    what does my current URDF look like?
    /ps
    ```

    This helps Drift make targeted changes and avoids unnecessary rebuilds.
  </Accordion>

  <Accordion title="Debug by describing, not by guessing">
    When something breaks, describe the symptom directly:

    ```drift theme={null}
    why isn't my camera publishing images?
    what went wrong with the last build?
    the robot arm isn't moving — what's wrong?
    ```

    Drift checks topics, logs, URDF / MJCF config, and process state to give you a diagnosis.
  </Accordion>

  <Accordion title="Hand your team's knowledge to the agent with /skill">
    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 theme={null}
    /skill add ./team-docs/ekf-tuning.md
    ```

    Drift will use that skill from then on. See [Custom Skills](/guides/skills) for the full pattern.
  </Accordion>
</AccordionGroup>

## Useful slash commands

| Command                                                      | What it does                                            |
| ------------------------------------------------------------ | ------------------------------------------------------- |
| `/help`                                                      | Show all commands and examples                          |
| `/init`                                                      | Generate a starter `DRIFT.md` for the current workspace |
| `/skill add <path>` / `/skill list` / `/skill remove <name>` | Manage custom skills                                    |
| `/ps`                                                        | Show running background processes                       |
| `/version`                                                   | Check your Drift CLI version                            |
| `/update`                                                    | Update to the latest version                            |
| `/login` / `/logout` / `/profile`                            | Manage your Drift account                               |
| `/clear`                                                     | Clear the terminal                                      |
| `/exit`                                                      | Exit Drift CLI                                          |

## What's next?

<CardGroup cols={2}>
  <Card title="Robot Showcase" icon="paw" href="/showcase/quadruped-go2">
    Full walkthroughs with Unitree Go2, Aloha, and Unitree H1
  </Card>

  <Card title="Your First Simulation" icon="play" href="/guides/first-simulation">
    A detailed walkthrough of building a complete simulation from scratch
  </Card>

  <Card title="Project Context" icon="brain" href="/guides/project-context">
    The full DRIFT.md workflow
  </Card>

  <Card title="Custom Skills" icon="puzzle-piece" href="/guides/skills">
    Hand your team's expertise to Drift
  </Card>
</CardGroup>

## Getting help

* **In Drift**: type `/help` or ask `drift> how do I...`
* **FAQ**: [Frequently Asked Questions](/getting-started/faq)
* **Bugs**: [Open an issue on GitHub](https://github.com/godrift-ai/drift-releases/issues)
* **Discord**: [Join the community](https://discord.gg/GnZtVZHAW6)