Skip to content

Quickstart

This guide takes you from install to a verified run in the simulator in a few minutes. You don't need a robot, ROS or an API key.

Before you begin

  • A terminal on macOS or Linux. On Windows, use WSL 2.
  • Python 3.10 or newer. (3.10 is the floor because ROS 2 Humble ships rclpy for 3.10 only.)
  • pipx, which installs command-line tools in their own environment.

  1. Install Quatern

    brew install pipx
pipx ensurepath
pipx install quatern

    sudo apt install pipx        # Debian, Ubuntu; on Fedora: sudo dnf install pipx
pipx ensurepath
pipx install quatern

    Quatern's sandbox relies on Linux and macOS process limits, so on Windows run it inside WSL 2. In PowerShell:

    wsl --install -d Ubuntu

    Then, in the Ubuntu terminal:

    sudo apt install pipx
pipx ensurepath
pipx install quatern

    Open a new terminal after pipx ensurepath so quatern is on your PATH.

    Using ROS 2? Install with your ROS Python

    If ROS 2 is installed, Quatern needs to see rclpy. Source ROS first and give the install access to it:

    source /opt/ros/<distro>/setup.bash
pipx install --system-site-packages quatern

    You only need this to drive a ROS 2 robot or Gazebo. The simulator and the catalog work without it.

  2. Start Quatern

    quatern

    The first time, Quatern creates its data folder and tells you where it is:

    Note: Quatern data will be stored at ~/.quatern. Set QUATERN_DATA_DIR to override.

    Then it opens the interactive session (the REPL) and offers to set up the agent:

    quatern — no robot, target -. /help for commands; plain text goes to the agent.

Welcome to Quatern. The agent needs a sign-in or your own key.
How do you want to use the agent?
  1) Sign in with GitHub — free monthly usage on Quatern's hosted API
  2) Paste your own Anthropic API key (from https://console.anthropic.com/settings/keys)
  3) Skip for now — every slash command works without it; /login any time
Choose [1]:

  3. Sign in

    Pick one. You can change it later with /login, or skip it entirely: every command works without the agent, which then uses Quatern's reference code.

    Press Enter (or type 1). Quatern shows a one-time code and opens GitHub in your browser:

    Your code: ABCD-1234
Enter it at https://github.com/login/device (opening your browser)…

    Enter the code on GitHub and approve. Back in the terminal:

    signed in as your-github-name; token stored at ~/.quatern/credentials (readable by you only)

    Quatern only asks GitHub for read access to your public profile. See Accounts and usage for the free allowance.

    Type 2 and paste a key from the Anthropic Console. Input is hidden.

    Anthropic API key:
stored at ~/.quatern/credentials (readable by you only)

    Requests go straight to Anthropic and are billed to your Anthropic account. You can also set ANTHROPIC_API_KEY instead of storing a key.

    Type 3. The tour and every slash command still work; the agent stays off until you run /login. Until you sign in or set a key, quatern offers this choice each time it starts.

    skipped; /login any time
    Sign-in didn't work?
    • error: sign-in was cancelled in the browser: you declined on GitHub. Run /login to try again.
    • error: the sign-in code expired before it was approved; run quatern login again: codes expire after about 15 minutes.
    • Quatern sign-ups need a GitHub account at least 30 days old.: use your own key instead (option 2).
    • Browser didn't open? Go to https://github.com/login/device yourself and enter the code.

  4. Take the 2-minute tour

    With no robot set up yet, Quatern offers a tour in its built-in simulator:

    No robot yet. Take a 2-minute tour in the simulator? [Y/n]

    Press Enter. The tour takes a catalog robot through the whole loop in seven steps. It records 120 seconds of simulated driving, but it runs faster than real time, so on most computers the tour finishes in under half a minute.

    [1/7] Pick a robot
Robots in the catalog:
   1.  c101               Quatern's own test rover: ELEGOO 4WD chassis, Arduino + L298N, RealSense depth camera.       [built-in sim]
   ...
Which robot? (number or name) 5
    installed TurtleBot 3 Burger from the catalog into ~/.quatern/robots

[2/7] Pick a world
    Which world? [room]
    goal: Navigate around the island to reach (1.2, 2.0)

[3/7] Record a 120-second drive in the simulator
    recorded turtlebot3_burger.default_2026-10-02_quickstart_room_v1: wheel_odom 30 Hz, imu 100 Hz, scan 5 Hz

[4/7] Calibrate the simulated actuators
[5/7] Generate localization and planning
[6/7] Verify offline against the capture
    verdict: READY after 1 iteration(s); stack stk_turtlebot3_burger.default_20261002T033750776419

[7/7] Deploy in the simulator, behind the gate and the watchdog
    Proceed past the gate? The simulated robot will move. [y/N] y
    RECEIPT rcpt_turtlebot3_burger.default_20261002T033751087648: COMPLETED (STOP_OBSERVED)

Quickstart complete in 10s wall-clock.

    What each step does:

    Step What happens
    Pick a robot Installs a catalog robot and its sample recording.
    Pick a world room, hallway or warehouse_aisle. Arms run in a simpler simulator with no world.
    Record A simulated operator drives a loop while every sensor records through its noise model. Quatern only records.
    Calibrate Measures how the simulated actuators respond.
    Generate Signed in, the agent adapts Quatern's reference localizer and planner to this recording, in up to 2 rounds. Otherwise the reference modules run as they are.
    Verify Replays the recording through the code in a sandbox, cross-checks the sensors, builds a map and plans to the goal. See How verification works.
    Deploy Shows the gate, asks you, and runs the plan in the simulator with the watchdog on. Ends in a receipt.

    Afterwards the REPL has the robot selected: quatern (turtlebot3_burger / sim2d:sim) >.

    Run the tour again any time

    /quickstart in the REPL, or quatern quickstart --robot turtlebot3_burger from your shell. Add --realtime to watch the deploy at real speed.

    The tour stopped early?
    • offline verification did not pass: ...: the goal or the world doesn't suit this robot. Try the default world, or a different robot. The message includes the command for the full report.
    • ...'s footprint (X m) is too wide for the 'hallway' route; pick another world: choose room or warehouse_aisle.
    • [agent] ... is not available on your plan; using ...: harmless; Quatern switched to a model your account can use.

  5. Give it a first task

    Signed in, type what you want in plain English at the prompt. Anything that isn't a /command goes to the agent:

    quatern (turtlebot3_burger / sim2d:sim) > plan a route around the island to (1.2, 2.0) and verify it

    The agent's tool calls show as [tool] ... and their results as [result] .... It ends with a verification report. To run the same check yourself, without the agent:

    /verify --goal "Navigate around the island to reach (1.2, 2.0)"

    The report ends with the verdict and the stack it saved:

      verdict: READY for the deploy gate (the code executed in the sandbox against the recorded stream)
  stack: stk_turtlebot3_burger.default_20261002T034438153397 (pin it with `quatern pin stk_turtlebot3_burger.default_20261002T034438153397`)

    Not signed in?

    Plain text prints agent disabled: not signed in. Run quatern login (or /login here) .... Every /command still works.

  6. Approve a deploy

    Pin the stack you just verified as your last-known-good, then open the deploy gate:

    /pin stk_turtlebot3_burger.default_20261002T034438153397
/deploy

    The gate shows what's about to run and every condition that will stop it:

    DEPLOY GATE
  robot:      turtlebot3_burger (instance default)
  target:     sim (sim2d, not hardware)
  stack:      stk_turtlebot3_burger.default_... [ready] from capture ...
  plan:       52 waypoints over 2.61 in grid2d
  duration:   15.5 s predicted
  will abort on:
    - the localizer's estimate, or the robot's own state, off the plan by more than: base 0.5, ...
    - no estimate from the localizer for 0.50 s
    - a stream stale (0.50 s, or two periods of a slower source) or under 30% of its rate
    - an obstacle in the planned path that the map did not have, or a drop-off ahead
    ...
Proceed past the gate? THE ROBOT WILL MOVE. [y/N]

    Type y. The robot runs with the watchdog on and the run ends in a receipt:

    gate confirmed; deploying...
RECEIPT rcpt_turtlebot3_burger.default_...: COMPLETED (STOP_OBSERVED)
  stop: observed 0.03s after the stop request, travel after stop 0.000 (by watchdog)
  max deviation base: 0.115

    Answer n (or just press Enter) and nothing moves: gate declined; nothing moved.

    On a real robot

    The gate also asks Physical e-stop in reach? [y/N] and refuses to open until hardware-only checks pass. Read Safety before your first hardware run.

Next steps

  • Set up your robot: a catalog robot, your own URDF, or a few questions.
  • Commands: every shell and slash command.
  • quatern stats shows how long each step took. The timings stay on your computer.