Install Snake Runner with Docker

Install and run Snake Runner with Docker or Kubernetes

Snake Runner has been designed with containers in mind. This means that it can be easily started within a container on a host with Docker Engine.

Quick Start

To start a runner, navigate to Bitbucket Admin PanelSnake CI section → Runners.

Then, click the Copy command button right under the docker run command listing.


Execute the copied command on a Docker host to start the runner. After starting the docker container, you will see a new runner on the Runners page.

online runner in the admin panel


There are only two parameters required for running Snake Runner:

  • the URL of the Bitbucket Server with the Snake CI add-on installed.
  • a registration token, which can be found in Bitbucket Admin PanelSnake CI section → Runners


Snake Runner is distributed as a Docker image. You can run a standalone container based on the image reconquest/snake-runner.


Pass the URL of Bitbucket Server and the registration token to docker run command like this:

docker run \
    --name snake-runner \
    --detach \
    --restart on-failure \
    -e "SNAKE_MASTER_ADDRESS=https://<bitbucket-address-here>/" \
    -e "SNAKE_REGISTRATION_TOKEN=<registration-token-here>" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/lib/snake-runner/secrets/:/var/lib/snake-runner/secrets/ \

Note that the address specified in the SNAKE_MASTER_ADDRESS should be accessible from the snake-runner container. For example, if Bitbucket is running in the Docker container on the same host machine, then both containers should be attached to the same Docker network (check --network flag for the docker run command).


  1. Stop and remove the existing Snake Runner container:
docker rm -f snake-runner
  1. Pull the latest available version of Snake Runner:
docker pull reconquest/snake-runner:latest
  1. Run the docker run command from the previous section.


Requirements: version >= 0.7.0


Snake Runner can be installed on a Kubernetes cluster using the official Helm chart: reconquest/charts/snake-runner

  1. Add the repository:
helm repo add reconquest
  1. Create your own values.yaml file to override the default values, making sure to specify values in the snake directive:
Key Description
snake.master_address The address of Bitbucket with the Snake CI add-on installed. Required
snake.registration_token The security token for registering the runner. You can obtain it from the Bitbucket admin panel → Runners. Required
snake.docker_mode Values: “host” or “dind”. “host” means that the runner will mount the host’s docker socket. “dind” stands for docker-in-docker. Required

Check out other possible values.

  1. Then, install the runner into the cluster:
# helm 2
helm install --namespace <NAMESPACE> --name ci -f values.yaml reconquest/snake-runner

# helm 3
helm install --namespace <NAMESPACE> ci -f values.yaml reconquest/snake-runner


  1. Update the remote chart repository:
helm repo update
  1. Upgrade your installation:
helm upgrade -n <NAMESPACE> ci reconquest/snake-runner --force -f values.yaml


Don’t see the runner?

  • Check the container’s logs:

    docker logs -f snake-runner
  • Still don’t see anything going wrong and want to debug on your own? Turn on debug or even trace messages by supplying log parameters such as SNAKE_LOG_TRACE=true. These options can be found in the reference.

  • Contact us directly or chat with devs on Slack.

Last modified October 21, 2020