Install Snake Runner

Setup and run Snake Runner to handle your workload.

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

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).

Upgrading Snake Runner

  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.


Don’t see the runner?

  • Check the container 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.

Install Snake Runner with Docker

Install and run Snake Runner with Docker or Kubernetes

Standalone on Windows

How to setup & use Snake CI on Windows.

Last modified October 21, 2020