Setup Runner

Install and run Snake Runner with Docker or Kubernetes

Snake Runner has been designed with containers in mind. It 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 Panel → Find the Snake CI section and click on Runners.

Then click on 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:

  • a URL of Bitbucket Server with the Snake CI add-on installed;
  • a registration token, which can be found in Bitbucket Admin Panel → Find the Snake CI section and click on Runners


Snake Runner is distributed as a Docker image and 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 as the following:

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 & remove 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 into 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 default values, make 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 on 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 that can be found in the reference.

  • Contact us directly or chat with devs in Slack.

Last modified September 17, 2020