Running Buildkite Agent with Docker

This page references the out-of-date Buildkite Agent v2.

For docs referencing the Buildkite Agent v3, see the latest version of this document.

You can run the Buildkite Agent inside a Docker container using the official Docker images.

Running each build in its own container

These instructions cover how to run the agent using Docker. If you want to learn how to isolate each build using Docker and any of our standard Linux-based installers read the Docker-Based Builds guide.

Running using Docker

Start an agent with the official image based on Alpine Linux:


A much larger Ubuntu-based image is also available:

docker run -e BUILDKITE_AGENT_TOKEN="INSERT-YOUR-AGENT-TOKEN-HERE" buildkite/agent:ubuntu

Running on startup

By default Docker starts containers on restart so there's no need for upstart or similar. Start your container with -d to daemonize it and it will be restarted on system boot with the same environment variables and arguments.

SSH keys, configuration and customization

See the GitHub repository for instructions on how to customize the base image. Alternatively you can create your own Docker image using our standard installer packages (see our Ubuntu Dockerfile for an example).