The Agent is an open-source program that always runs on your robots, it manages communication between the Airbotics cloud and ROS 2 (and optionally the Docker daemon) on your robot.

System requirements

  • Ubuntu 22.04 Jammy Jellyfish.
  • ROS 2 Humble.
  • Docker Engine (optional).


Install the latest release from pip:

It is best practice to create Python venv before installing.

pip3 install airbotics-agent


Ensure you’ve created a new robot and set the following environment variables before you attempt to run the agent for the first time.

export AIR_TENANT_UUID="0000000-*****-******-******"
export AIR_ROBOT_ID="my-bot"
export AIR_TOKEN="art_************************"

You can then start the agent from the terminal:


In production, you may want to consider a robust process management system such as systemd to manage the lifecycle of the agent.


The following flags can be passed to the agent:

--debugLog at the debug level and above.
--daemonizeDaemonize the agent and detach from terminal. Log output is written to ~/.airbotics/airboticsd.log and a PID file is written to ~/.airbotics/


Config can be set from:

  1. Environment variables
  2. TOML

Any configuration set with environment variables will overwrite variables in the config.toml.

The following config can be set:

AIR_ROBOT_IDThe ID of robot
AIR_TENANT_UUIDThe ID of the tenant who owns the robot
AIR_TOKENAuth token for robot to authenticate with
AIR_ENABLE_CONTAINERStrueConnect agent to the docker daemon
AIR_ROS_DISTROhumbleROS distro
AIR_MQTT_HOSTbroker.airbotics.ioThe MQTT host
AIR_MQTT_KEEP_ALIVE60The MQTT keep alive in seconds
AIR_CONTAINER_REGISTRY_USERNAMEContainer registry username, if using private repos
AIR_CONTAINER_REGISTRY_PASSWORDContainer registry password, if using private repos

Environment variables

The agent will parse configuration from environment variables.

TOML file

The agent will also look in ~/.airbotics/config.toml for configuration.

Providing a config.toml is completely optional and is provided for convenience.


The agent produces logs at the following levels:

DEBUGVerbose information for debugging, visible with --debug flag.
INFOGeneral information about expected agent execution.
WARNINGWarnings arising from unexpected situations that are not serious.
ERRORErrors arising from situations that affect the agent execution.
CRITICALCritical errors arising from extreme situations that cause agent termination.

Logs are always written to ~/.airbotics/airbotics.log.

When the agent is run without the --daemonize flag, logs will also be displayed on the console.

Critical errors

There are 3 conditions that produce critical errors and result in the agent terminating:

  • AIR_TENANT_UUID, AIR_ROBOT_ID or AIR_TOKEN are not set in the configuration.
  • ROS 2 libraries cannot be imported.
  • AIR_ENABLE_CONTAINERS is set to true and the Docker daemon cannot be reached.



  • Initial release.


  • Added configuration to vitals allowing collection to be toggled.