Concepts

Airfield Overview

Airfield runs each part of a robot’s ROS 2 stack in its own Docker container, without changing how the ROS code itself is written or built. It defines a consistent project layout, package metadata schema, and command surface so teams can build and run their code reproducibly on a laptop, in CI, and on the robot.

This page walks from the command surface down to what actually happens at launch time through one example project: my_robot/, with three Airfield packages called base_driver, camera_driver, and nav_stack.

Tip: green dashed terms in the text are clickable. Click one and the part of the diagram it refers to lights up.

Core principles

1. Encapsulated package execution with isolated dependencies
2. Convention-over-configuration project layout
3. Explicit dependency declarations by target architecture (arm64, x86_64)
4. Deterministic orchestration from package plans
5. Flexible enough for research iteration, strict enough for production bring-up

The command surface

Every invocation has the same shape: airfield <namespace> <command> [arguments]. The two namespaces mirror Airfield’s two core nouns:

• project commands act on the whole workspace: up launches a plan (described below) as a tmux session, down tears it down again, liftoff runs package defaults one after another without tmux, and run executes a single package’s default target.
• package commands act on one Airfield package: build produces its container image, run executes a named target from its run: map, cmd runs any one-off command inside the container, and shell drops you into an interactive shell there.
• The third column is support tooling. The one to know early is doctor, which checks host requirements (Docker, GPU/CUDA, tmux, …) before anything can fail mysteriously; subpackages acts as git across every source repo in the project at once.

There are also two additional conveniences. First, a [pkg name] argument can be omitted when your shell is already inside that package’s folder, because Airfield detects the package from the working directory (build is the one exception: pass .). Second, commands resolve by unique prefix, so airfield pa b means airfield package build.

A project on disk

A project is a normal directory with four Airfield-specific pieces at the root:

• The project airfield.yaml (kind: project) sets the ros_distro and default base_image that every package inherits, and lists the source repos that make up the project.
• packages/ holds the Airfield packages: each subfolder is one package, and each package becomes exactly one container image.
• dependencies/ holds one small YAML manifest per dependency, telling Airfield how to install it (apt or pip), split by architecture (arm64/, x86_64/) with xplatform/ for recipes that work everywhere. These are the project’s own manifests; a name with no manifest here falls through to the same two folders in the shared Airfield packages repository, which is where most common dependencies already have a recipe. See Manage Dependencies.
• plans/ holds descriptions of what a full launch looks like.

The central idea in this diagram: an Airfield package wraps one or more ROS packages. base_driver bundles three (motor_driver, joystick, gui); camera_driver bundles two; nav_stack wraps exactly one. In that last case the package’s own folder is the ROS package (source_path: "."), which is why its package.xml sits at the top level right next to airfield.yaml.

Note: containers isolate dependency environments, not ROS packages. It is preferred to bundle ROS packages whose dependencies agree, and split out a separate Airfield package where dependencies diverge. Bundling costs no runtime isolation since at launch each pane still gets its own container, as the last diagram shows.

The extra base_driver/ and camera_driver/ folders marked (ROS metapackage) are the glue that makes bundling work; they’re explained in the next diagram. The optional .air file holds machine-local extras (such as additional container mounts) that belong to one machine rather than to the shared package config.

Inside one Airfield package

Zooming into packages/base_driver/: the left side is its entire airfield.yaml; the right side is the source tree it points at.

• source_path names the folder that colcon treats as the workspace source. Here src/ holds three ordinary ROS 2 packages (motor_driver, joystick, and gui), each with its own package.xml, untouched by Airfield. (When a package wraps a single ROS package, source_path: "." skips the inner folder entirely; see nav_stack in the previous diagram.)
• dependencies are installed into the package’s one shared image (next diagram); devices and group_add pass hardware through to the container (here /dev/input plus the dialout group for serial ports).
• The run: map gives memorable names to launch commands. Note that the targets invoke the inner ROS packages’ executables (ros2 run motor_driver motor_node), because by the time these commands execute, the container is just a sourced ROS workspace that colcon has built.
• The fourth folder in src/, the base_driver/ metapackage, is a ROS package with no code that only depends on the other three. It deliberately shares the Airfield package’s name: on the first run Airfield builds colcon build --packages-up-to base_driver (next diagram), and that name match is what lets a single command build the whole bundle.

Note: the src/ at the top of the package (Airfield’s source_path) is a workspace-style folder that holds whole ROS packages, while the src/ inside gui/ is that ROS package’s own C++ source folder.

What sits below each inner package is decided by that package’s build type, which is a ROS convention rather than anything Airfield imposes:

• ament_cmake (C++), which is what all three packages above are: .cpp files go in src/ and headers in include/<package_name>/, next to package.xml and CMakeLists.txt.
• ament_python: the code lives in a folder named after the package itself, so a Python motor_driver/ would hold a second motor_driver/ beside package.xml and setup.py. That inner folder is a Python module directory, meaning a folder with an __init__.py in it that Python treats as one importable unit, which is what lets the node be reached as import motor_driver.motor_node.

Build vs run: the two-phase lifecycle

Phase 1: airfield package build produces an environment image, airfield-pkg-base_driver. It resolves each entry in dependencies: against the dependency manifests, then generates a Dockerfile: a base image (package override, else project default, else the ROS-distro default), the apt/pip installs from the manifests, and a small entry script. No ROS source is compiled into the image, which is exactly why it only needs rebuilding when dependencies change.

Phase 2: every run, cmd, or shell starts a fresh, disposable container from that image. Your source is live-mounted, so edits on the host are instantly visible inside: no rebuild, no copy, and nothing is lost when an image is rebuilt. The entry script then makes one decision: if install/base_driver already exists in the workspace, it skips straight to your command; on first run it compiles with colcon build —packages-up-to base_driver, which is where the metapackage from the previous diagram earns its keep, pulling all three bundled ROS packages into one build. Either way it finishes by sourcing ROS plus the workspace install and executing your command.

install/ is the directory colcon writes finished build output into, one subfolder per ROS package, so install/base_driver is nothing more than colcon’s own record that this bundle has already been compiled. Because --packages-up-to builds the metapackage last, after the three packages it depends on, that single folder appearing is enough to prove all four succeeded.

The ~/workspace/ folder (src, build, install, log) lives on the host and is mounted into every container: the first container to need a package compiles it once, and every later one (including every pane of a plan) just sources the result. Simultaneous first runs can’t collide; the build is serialized with a lock in the same shared folder. None of this needs configuring — Airfield mounts the workspace itself.

~/workspace is the path inside the container, and it is the same everywhere. On the host, build/, install/, and log/ live in the project, at <project>/.airfield/workspace/, so two projects never share one install/. See Shared colcon workspace.

Anatomy of a plan

A plan is one YAML file in plans/ that describes everything airfield project up should launch. windows split into panes, and each pane sets two keys:

• package: selects which Airfield package’s container this pane runs in
• cmd: sets what to run there; it’s a raw shell command executed inside the container, so it addresses the inner ROS packages directly (ros2 run / ros2 launch), just like the run: targets two diagrams up

pre_window is exported into every pane, which makes it the place for session-wide environment like MAP=speedway. The same package may drive several panes (base_driver appears in both the motor pane and the joystick pane), which costs nothing extra: one image, two containers, as the next diagram shows. A pane can also be left null to get a plain shell inside the session, handy for debugging alongside the running nodes.

Launch time: project up

airfield project up navstack renders the plan into a tmuxinator config (.airfield/navstack.tmuxinator.yml) and starts it as a tmux session. Each pane executes airfield package cmd <package> -- "<cmd>". In other words, every pane is exactly one phase-2 run from the previous diagram, reusing the images from phase 1.

Follow the fan-out in the middle: three images back four containers. The single base_driver image spawns two independent containers (pane 2 and pane 3), so bundling several ROS packages into one Airfield package never sacrifices runtime isolation. All four containers mount the same ~/workspace/, so the first pane to need a package builds it and the rest just source install/: build once, launch many.

airfield project down kills the session, and each pane’s Airfield process stops its own container on the way out, leaving no orphaned containers running.

Where to go next

Ready to try it? Quick Start walks the same loop with real commands, the tutorials cover each piece in depth, and Runtime & Environment documents how the containers are wired to the host.