Installation onto host machine

How to install BuildGrid directly onto your machine.


BuildGrid server currently only supports Linux. macOS and Windows platforms are not supported.


BuildGrid only supports python3 >= 3.8 but has no system requirements. Main Python dependencies, automatically handled during installation, include:

  • boto3: the Amazon Web Services (AWS) SDK for Python.

  • click: a Python composable command line library.

  • grpcio: Google’s gRPC Python interface.

  • janus: a mixed sync-async Python queue.

  • protobuf: Google’s protocol-buffers Python interface.

  • pycurl: a Python interface to the cURL library (depends on libcurl).

  • PyYAML: a YAML parser and emitter for Python.

Install from sources

BuildGrid has setuptools support. We recommend installing it in a dedicated virtual environment. In order to do so in an environment named env placed in the source tree, run:

git clone
cd buildgrid
python3 -m venv env
env/bin/python -m pip install --upgrade setuptools pip wheel
env/bin/python -m pip install --editable .


Once created, the virtual environment can be activated by sourcing the env/bin/activate script. In an activated terminal session, simply run deactivate to later deactivate it.

Once completed, you can check that installation succeed by locally starting the BuildGrid server with default configuration. Simply run:

env/bin/bgd server start data/config/default.yml -vvv


The pyproject.toml defines extra targets, auth, docs, tests, db and redis. They declare required dependency for, respectively, authentication and authorization management, generating documentation, running unit-tests and different storage implementations. They can be use as helpers for setting up a development environment. To use them run:

env/bin/python -m pip install --editable ".[auth,docs,tests]"

Installation in Kubernetes

BuildGrid also supports deployment into a Kubernetes cluster. Docker images for use in this kind of deployment are provided for the BuildGrid server and tooling and also BuildBox for running workers.

An example Kubernetes deployment of BuildGrid is provided in the buildgrid-deployments repository. This example is intended as a demo deployment, providing a starting point for writing a production deployment configuration.

Some things to consider which aren’t addressed in the example:

  • Handling Bot connections across a scaled Bots service.
  • Scaling the CAS service
    • The example uses disk storage, a real deployment probably needs to use some kind of shareable storage like S3, perhaps with a cache layer for speed.