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 us-docker.pkg.dev/airplane-prod/public/agent:1. 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.

Copied
1
docker run --name airplane-agent \
2
-d --restart always \
3
--pull always \
4
-e AP_API_TOKEN=YOUR_API_TOKEN \
5
-e AP_TEAM_ID=YOUR_TEAM_ID \
6
-e AP_LABELS="container-runtime:docker" \
7
-v /var/run/docker.sock:/var/run/docker.sock \
8
us-docker.pkg.dev/airplane-prod/public/agent:1

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 https://app.airplane.dev/agents 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.