Running the agent with Docker

Deploy a self-hosted Airplane agent with Docker.

If you're running on AWS or GCP, see the relevant setup docs for easier agent setup:

Basic Docker setup

If you're running in an on-premises environment or otherwise need to run the agent on existing infrastructure, the Airplane agent can be run anywhere that supports running a Docker host.

To follow the installation instructions below, you'll need the following values:

  • YOUR_API_TOKEN: generate a new token by running airplane apikeys create <token name> from the Airplane CLI.
  • YOUR_TEAM_ID: get your team ID via airplane auth info or visit the Team Settings page.

You'll need a host machine to run the agent on, that has a Docker host installed and running.

The agent Docker image is available at Below is a one-liner for running the agent in the background—be sure to replace YOUR_API_TOKEN and YOUR_TEAM_ID with the appropriate values.

docker run --name airplane-agent \
-d --restart always \
--pull always \
-e AP_LABELS="container-runtime:docker" \
-v /var/run/docker.sock:/var/run/docker.sock \

Setting the AP_LABELS environment variable will add the provided labels to the agent for use in run constraints. For details on using labels, see Execute rules & constraints.

That's it! Visit and verify that your agent appears in the list.

Consider running additional agents—each agent is able to process one task at a time.

  • You can run multiple agents on the same host. Be sure to provide a distinct --name to the docker run command (e.g. --name airplane-agent-0, --name airplane-agent-1). We recommend running no more than 2 agents per CPU core in your host, although you can pack more if your tasks and runbooks are not resource intensive.
  • You can also run multiple hosts.