Concepts

Airfield Overview

Airfield is an opinionated robotics framework centered on packages. It defines a consistent project layout, package metadata schema, and command surface so teams can build and run robot code reproducibly.

Airfield CLI

The Airfield CLI is the primary interface for interacting with Airfield. It is designed to be used in a variety of contexts, from a single developer working on a laptop to a large team working on a shared system. The CLI is used to:

• Initialize new projects
• Install dependencies
• Build and run packages
• Create and manage plans

It has built-in developer comfort features such as shell completion and a system doctor to help you get started quickly and stay productive.

Package Model

Robotics teams often share runtime infrastructure while owning different software components. Airfield treats each component as a package with explicit metadata:

• what source tree to build
• what dependencies to install
• how packages are grouped into runnable plans

This keeps package ownership clear while still enabling full-project orchestration.

Core principles

1. Encapsulated package execution with isolated dependencies
2. Convention-over-configuration project layout
3. Explicit dependency declarations by target architecture
4. Deterministic orchestration from package plans
5. Optimized for flexible robotic development and reliable productionization

Project Layout

airfield project init creates a project root with predictable folders:

<project>/
  airfield.yaml
  packages/
  dependencies/
    x86_64/
    arm64/
  plans/

airfield.yaml is the root marker used for project discovery by runtime commands.

Package model

Each package has an airfield.yaml file:

name: my_pkg
dependencies:
  - ros_base>=1.3,<2.0
  - cv_bridge==3.2.1
source_path: src

• name is the package identifier.
• dependencies are resolved from architecture-specific dependency manifests.
• source_path is the source folder relative to the package directory.

Considerations for Isolating Dependencies

To ensure isolation, Airfield uses a containerized build process. This ensures that packages are built in isolated environments with specific versions of dependencies. It also means that packages are reproducible and can be run in a predictable environment regardless of other packages installed on the system. As part of the containerization process, Airfield mounts the package source at runtime, which means that when working inside the packages container, developers have access to the same code that they edit outside the container. This ensures that the source code is not copied into the image, that the source code is always up to date, and that changes are not lost when rebuilding the image.