Getting Started¶
On Mac, Windows, or no GPU?
This page assumes a Linux desktop with an NVIDIA GPU. If you don't have
one, AirStack on OSMO is the
recommended remote development path — you only need an SSH key, the
osmo CLI, and VS Code or Cursor. No local Docker, no NVIDIA drivers,
no airstack install.
AirStack is currently in ALPHA and only meant for internal usage.
We'd really appreciate your feedback and contributions to improve this project for everyone! Please join our #airstack channel on Slack to contribute or ask questions.
The AirLab Docker registry is public, so anyone can pull the Docker images without an account. You will need an account with AirLab to push images and to access the Nucleus server and other internal resources. The API and functionality are not stable and are subject to change.
By the end of this tutorial, you will have the autonomy stack running on your machine.
Requirements¶
The Docker images take about 25GB; we recommend at least 100GB of free disk space.
Check the hardware requirements for the NVIDIA Isaac Sim here. An NVIDIA RTX 3070 is the minimum GPU; a GeForce RTX 4080 or better is recommended for the best performance.
AirStack is tested on Ubuntu 22.04 and 24.04.
Clone¶
git clone --recursive -j8 [email protected]:castacks/AirStack.git
cd AirStack
Install and Setup¶
./airstack.sh install # installs docker, docker-compose, and the NVIDIA Container Toolkit
./airstack.sh setup # this lets you use the `airstack` command and sets up your keys
source ~/.bashrc # OR ~/.zshrc. applies settings to enable `airstack` command
Docker Images¶
Now you have two options on how to proceed. You can build the docker image from scratch or pull the existing image on the airlab docker registry. Building the image from scratch can be useful if you would like to add new dependencies or add new custom functionality. For most users just pulling the existing image will be more conveninent and fast since it doesn't require access to the Nvidia registry.
Option 1: Pull From the Airlab Docker Registry (Preferred)
The AirLab Docker registry (airlab-docker.andrew.cmu.edu) is public — no account or docker login is needed to pull.
The images will be pulled from the server automatically. This might take a while since the images are large.
Option 2: Build Docker Images From Scratch
1. First, gain access to NVIDIA NGC Containers by following these instructions. 2. Then: If you have permission you can push updated images to the docker server. Pushing (unlike pulling) requires logging in with your AirLab account first.Launch¶
This launches the Isaac Sim scene specified by ISAAC_SIM_SCRIPT_NAME in AirStack/.env (default: a single drone in the Pegasus default environment). By default the sim comes up playing (PLAY_SIM_ON_START="true" in .env) — launch with airstack up --no-play to come up paused and press Play in the Isaac Sim window yourself.
Containers start immediately, but the ROS 2 workspace still builds and PX4 still boots in the background. To wait until the drone is actually ready to fly:
Useful variants:
airstack up --sim airsim # MS AirSim instead of Isaac Sim
airstack up --sim isaac --robots 3 # multi-robot (auto-selects the multi-drone scene script)
The full set of launch flags is in the CLI reference (or airstack help up).
Move Robot¶
Foxglove opens automatically in the GCS with the AirStack layout already loaded — no manual import or connection needed (see GCS Foxglove Visualization). Press Takeoff in the Robot Tasks panel, then Navigate, like in this video:
Note
If you instead connect a Foxglove running on the host, the bridge is exposed on host port 8766 (container port 8765): connect to ws://localhost:8766.
Shutdown¶
To shutdown and remove docker containers:
Congratulations! You did it.
Next: the Modular AirStack Walkthrough — fly a reference stack, add a module from the catalog, build your own stack, and scale to a fleet.