AirStack

Build the autonomy, not the scaffolding.

AirStack is an open ROS 2 stack for aerial robots — simulator, ground control, and layered onboard autonomy that launch as one system. Developed by the AirLab at Carnegie Mellon University's Robotics Institute.

Three drones flying the real stack in Isaac Sim, the Foxglove GCS, and MS AirSim — recorded from this repo, unstaged. Watch the live demos on the documentation home page.

Zero → drones flying in sim

git clone --recursive -j8 git@github.com:castacks/AirStack.git && cd AirStack
./airstack.sh install && ./airstack.sh setup
airstack up --play --wait

Then follow the Getting Started guide and the Modular AirStack Walkthrough. No Linux box or GPU? Run AirStack on OSMO from any laptop.

One command brings up sim, robots, and ground control

airstack up starts the simulator, one container per robot, and a Foxglove-based ground control station, wired together over ROS 2. Flags select the simulator, scene, and fleet size — no launch-file surgery:

airstack up --sim airsim --scene neighborhood
airstack up --sim isaac --robots 3 --scene full-warehouse
airstack up --fleet sim_three_mixed

airstack ready blocks until the stack is flight-ready — containers running, sim publishing /clock, autonomy nodes up, PX4 EKF armable — so scripts and CI know exactly when takeoff is available.

Same code in sim and on the vehicle

The desktop dev container and the Jetson (L4T) onboard container extend one base service and launch the same stack entry point (stacks/full_default/launch/stack.launch.xml). What you test in simulation is what the vehicle runs.

CI flies the whole stack, not just unit tests

Pull requests run pytest campaigns against the live simulators on ephemeral GPU runners: image builds, colcon builds in every container, bring-up liveliness, sensor topic rates, takeoff–hover–land, fixed trajectories with cross-track error, and waypoint navigation judged on the odometry track. Run them yourself, or comment /pytest on a PR:

airstack test -m takeoff_hover_land --sim isaacsim --num-robots 1 -v

Marks are defined in tests/; metrics regressions fail the report.

AI agents can drive this repo

Module boundaries, an AGENTS.md contract, and 23 step-by-step skills under .agents/skills/ give coding agents the same on-ramp as humans: scaffold a package, wire it into a stack, fly it in sim, document it. Every demo video on the documentation home page was captured by an AI agent — it brought the stack up, scripted the flights, implemented the follow-camera it filmed with, and edited the clips.

Modular architecture

AirStack follows a layered autonomy architecture:

Robot
├── Interface Layer: Communication with robot controllers
├── Sensors Layer: Data acquisition from various sensors
├── Perception Layer: State estimation and environment understanding
├── Local Layer:
│   ├── World Models: Local environment representation
│   ├── Planners: Trajectory generation and obstacle avoidance
│   └── Controls: Trajectory following
├── Global Layer:
│   ├── World Models: Global environment mapping
│   └── Planners: Mission-level path planning
└── Behavior Layer: High-level decision making

The topology that actually launches is selected by a stack — a self-contained folder under stacks/ with pinned modules.repos and a CI-observed wiring.md. Capabilities beyond the trunk live in modules — thin external repos with a small module.yaml, pulled on demand (airstack module add <url> --version <pin>) and discovered through the module registry. Multi-robot deployments are declared by fleets under config/fleets/: who exists, which vehicle, which stack, and which ground hosts run split-stack offboard halves.

Repository map

• robot/ — onboard ROS 2 (Jazzy) autonomy stack (interface, sensors, perception, local, global, behavior)
• stacks/ — reference autonomy stacks (launch topology + pinned modules + wiring baselines)
• config/ — fleet and vehicle definitions
• simulation/ — Isaac Sim (Pegasus) and Microsoft AirSim (legacy)
• gcs/ — Ground Control Station
• common/ — shared ROS packages and the module_schema/ for module.yaml
• tools/ — repo tooling (docs catalog generator, fleet resolver, wiring/DDS generators)
• tests/ — pytest system tests, integration tests, and contract tests
• docs/ — MkDocs documentation source

System requirements

• Docker with the NVIDIA Container Toolkit
• NVIDIA GPU: RTX 3070 minimum, RTX 4080 or better recommended (for local Isaac Sim)
• Storage: Docker images take ~25 GB; 100 GB free disk space recommended
• OS: Ubuntu 22.04 or 24.04

Documentation

Full documentation lives at https://docs.theairlab.org (built from docs/ with MkDocs — airstack docs serves it locally).

Community & license

Contributions are welcome — see the Contributing guide and open issues/discussions on GitHub. AirStack is developed at Carnegie Mellon University's AirLab (PI: Sebastian Scherer); contact the team via theairlab.org. Licensed under the BSD 3-Clause Clear License — see LICENSE.