Running Buildkite Agent with Docker

You can run the Buildkite Agent inside a Docker container using the buildkite/agent docker image on Docker Hub.

Running each build in it’s 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 via 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. Simply start your container with -d to daemonize it and it will be restarted on system boot with the same environment variables and arguments.

Running different versions

The default tag (i.e. buildkite/agent and buildkite/agent:latest) will always point to the latest stable release.

We recommend you use buildkite/agent:3 for new setups to get at least version 3.0 of the agent

If you want to use an exact version of Buildkite Agent you can use the corresponding tag, such as buildkite/agent:3.0.1.

You can see all the available versions on

Configuring the agent

Most agent configuration settings can be set with environment variables. Setting sensitive data, (such as the agent token) via environment variables or command line arguments is not recommended as they are exposed in commands such as docker inspect.

In addition to environment variables, you can copy or mount a configuration file to /etc/buildkite-agent/buildkite-agent.cfg, for example:

docker run -it \
  -v "$HOME/buildkite-agent.cfg:/etc/buildkite-agent/buildkite-agent.cfg:ro" \

Adding hooks

You can add custom agent hooks by mounting or copying them into the /buildkite/hooks directory (and ensuring they are executable).

For example, this is how you'd mount the hooks directory using a read-only host volume:

docker run -it \
  -v "$HOME/buildkite-hooks:/buildkite/hooks:ro" \

Alternatively, if you create your own image based off buildkite/agent, you can copy your hooks into the correct location:

FROM buildkite/agent

ADD hooks /buildkite/hooks/

Exposing build secrets into the container

There are many approaches to exposing secrets to Docker containers. In addition, many Docker platforms have their own methods for exposing secrets. If you’re running your own Docker containers, we recommend using a read-only host volume.

The following example mounts a directory containing secrets on the host machine ($HOME/buildkite-secrets) into the container as a read-only data volume at /buildkite-secrets:

docker run -it \
  -v "$HOME/buildkite-secrets:/buildkite-secrets:ro" \

You can then use an environment agent hook to expose those secrets via environment variables, or to configure tools such as git or ssh.

Authenticating private git repositories

To configure a git-credentials file located at /buildkite-secrets/git-credentials, you could use the following environment agent hook mounted to /buildkite/hooks/environment:


set -euo pipefail

git config --global credential.helper "store --file=/buildkite-secrets/git-credentials"

# You can export other secrets here too
# export FOO=bar

To configure a private SSH key located at /buildkite-secrets/id_rsa_buildkite_git you could use the following environment agent hook mounted to /buildkite/hooks/environment:


set -euo pipefail

eval "$(ssh-agent -s)"
ssh-add -k /buildkite-secrets/id_rsa_buildkite_git

# You can export other secrets here too
# export FOO=bar

Other options for configuring Git and SSH include:

  • Running ssh-agent on the host machine and mounting the ssh-agent socket into the containers. See the Buildkite Agent SSH keys documentation for examples on using ssh-agent.
  • The least-secure approach: the built-in docker-ssh-env-config support allows you to pass in keys via environment variables.

Invoking Docker from within a build

To invoke Docker from within builds you'll need to mount the Docker socket into the container:

docker run -it \
  -v /var/run/docker.sock:/var/run/docker.sock \

Note that this gives builds the same access to the host system as docker has, which is generally root.

Entrypoint customizations

The entrypoint uses tini to correctly pass signals to, and kill, sub-processes. Instead of redefining ENTRYPOINT we recommend you copy executable scripts into /docker-entrypoint.d/. All executable scripts should not contain any file extension, and will be executed in alphanumeric order.