Key Concepts¶

Understanding a few core concepts will help you work effectively with AirStack. This document provides the essential mental models to the AirStack way of doing things.

The AirStack Philosophy¶

CLI-First Development¶

AirStack development centers around the airstack CLI tool - your single interface for all development tasks.

airstack up           # Launch the system
airstack connect robot # Jump into a container
airstack down         # Shut everything down

First Step

Run airstack setup after installation to add the CLI to your PATH.

Why a CLI? It provides consistency and simplicity. Under the hood, it's a lightweight wrapper around Docker Compose, so you can always drop down to docker compose commands if needed.

Learn more: CLI Command Reference

Containerized Everything¶

All development happens inside Docker containers. This isn't just a deployment detail - it's how you develop, build, and test your code every day.

graph LR
    A[Your Code<br/>on Host] --> B[Robot Container<br/>ROS 2 + Build Tools]
    A --> C[Isaac Sim Container<br/>Simulation]
    A --> D[GCS Container<br/>Monitoring]

    style A fill:#bfb,stroke:#333,stroke-width:2px
    style B fill:#fbb,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#fbf,stroke:#333,stroke-width:2px

Why containers?

Reproducible: Everyone has the same environment
Isolated: Doesn't mess with your host system
Multi-robot ready: Run multiple robots on one machine
Dev-prod parity: Same containers in simulation and on real hardware

Learn more: Docker Workflow Details

How AirStack is Composed¶

AirStack simulates multiple separate machines (e.g. robots, GCS) that communicate with each other through Docker Compose:

graph TD
    A["Root docker-compose.yaml<br/>(The Connector)"] --> B[Robot Autonomy Stack]
    A --> C[Isaac Sim Simulation]
    A --> D[Ground Control Station]

    B --> B1[Sensors & Interface]
    B --> B2[Perception & Planning]
    B --> B3[Control & Behavior]

    style A fill:#76B900,stroke:#333,stroke-width:3px
    style B fill:#fbb,stroke:#333,stroke-width:2px
    style C fill:#bbf,stroke:#333,stroke-width:2px
    style D fill:#fbf,stroke:#333,stroke-width:2px

When you run airstack up, here's what happens:

Root compose file (docker-compose.yaml) includes all component-specific compose files:

include:
  - simulation/isaac-sim/docker/docker-compose.yaml
  - robot/docker/docker-compose.yaml
  - gcs/docker/docker-compose.yaml

Shared network connects all containers (subnet 172.31.0.0/24)
Independent launch - each component's command: attribute starts its main process:
Robot: Builds workspace → Launches ROS 2 autonomy stack
Isaac Sim: Starts simulation with your scene
GCS: Launches monitoring interface

This modular design means you can:

Launch only what you need: airstack up robot-desktop (skip simulation)
Swap components easily (different planners, different simulators)
Scale to multiple robots: NUM_ROBOTS=3 airstack up

Learn more: Docker Compose Architecture

Multi-Robot by Design¶

AirStack assumes you might have multiple robots, even in development. Each robot container gets:

Unique ID: ROS_DOMAIN_ID extracted from container name (e.g., robot-1 → ROS_DOMAIN_ID=1)
Unique namespace: All topics under /{robot_name}/
Isolated environment: Own workspace, own state
Shared network: Can communicate with other robots and GCS

# Launch 3 robots
NUM_ROBOTS=3 airstack up

# Connect to specific robot
airstack connect robot-1
airstack connect robot-2

Each robot runs independently but can coordinate through the shared ROS 2 network.

The Development Loop¶

Here's what a typical development session looks like:

# 1. Start containers (without auto-launching the stack)
AUTOLAUNCH=false airstack up robot-desktop

# 2. Connect to the robot container
airstack connect robot

# 3. Build your changes
bws --packages-select my_package  # within container

# 3. Launch and test
sws && ros2 launch my_package my_launch.xml   # within container

# 4. Iterate...

# 5. When done, detach and shut down
Ctrl-b, d  # Detach from tmux session
airstack down

Bash aliases within the robot container:

bws = build workspace (alias for colcon build)
sws = source workspace (alias for source install/setup.bash)
cws = clean workspace and reset variables

Learn more: Development Environment Setup

Configuration: Environment Variables¶

AirStack uses environment variables for configuration, following Docker Compose patterns.

Default settings (.env file):

VERSION=latest
AUTOLAUNCH=true
NUM_ROBOTS=1
ISAAC_SIM_SCENE=simulation/isaac-sim/scenes/two_drone_RetroNeighborhood.usd

Runtime overrides:

# Don't auto-launch (useful for development)
AUTOLAUNCH=false airstack up

# Different scene
ISAAC_SIM_SCENE=my_scene.usd airstack up

# Custom env file with overrides
airstack --env-file overrides/custom.env up

You can layer multiple env files to compose configurations. NOTE: Unlike docker compose, the airstack cli always uses the root .env file as the base, and then applies any additional env files on top of it. This ensures that essential defaults are always present, while still allowing for flexible overrides.

What Makes AirStack Different¶

If you're coming from other robotics frameworks, here's what's unique:

CLI-first: One command for everything, no hunting for scripts
Docker-native: Containers aren't optional, they're the development environment
Modular composition: Components compose via Docker, not monolithic builds
Multi-robot from day one: Built for fleets, works great for single robots too
Simulation-first: Develop and test in Isaac Sim before hardware

Next Steps¶

Now that you understand the philosophy:

Set up your environment - Get your IDE and tools ready
CLI deep dive - Master all the commands
Docker workflow - Understand container management
Fork your project - Start building

Remember

Everything flows through the airstack CLI → launches Docker Compose → starts containers → runs ROS 2 nodes. This pattern repeats everywhere in AirStack.