Workflow

Quick Start

1. Initialize a project

airfield project init ./my_robot --ros-distro jazzy

This creates the project marker, package folder, dependency roots for x86_64 and arm64, and a plans directory.

2. Initialize a package

From inside an Airfield project:

cd my_robot
airfield package init nav_stack

Standalone package initialization is also supported:

airfield package init .

3. Wrap an existing ROS package

airfield package init --path /path/to/existing_ros_package --ros-distro jazzy

If package.xml exists, Airfield infers the ROS package name and dependency tags, then writes airfield.yaml without rewriting the ROS source files.

4. Build a package image

airfield package build nav_stack --target-device x86_64

Airfield automatically leverages Docker BuildKit optimizations. While the first build downloads necessary apt and pip dependencies, subsequent builds reuse persistent cache mounts, resulting in up to 80% faster rebuilds. Local artifacts and data files are ignored to keep the build context small.

For full Docker build logs:

airfield package build nav_stack --target-device x86_64 --show-all-output

5. Run the package

Define a named run command in packages/nav_stack/airfield.yaml:

run:
  list-packages: ros2 pkg list

airfield package run nav_stack list-packages

You can also open a package container shell:

airfield package shell nav_stack

Or run one command in the package container:

airfield package cmd nav_stack -- ros2 pkg list

6. Launch a plan

airfield project liftoff example

To generate a tmuxinator session from a plan:

airfield package up example --output .airfield/example.tmuxinator.yml

Add --launch to start tmuxinator immediately.