Skip to main content

Using Docker

The Transitive agent and capabilities can be installed in a Docker container. Please follow the instructions below or use our example docker image.


Include this snippet in your Dockerfile:

FROM ${BASE_IMAGE:-'ubuntu:20.04'}

RUN apt-get update
RUN apt-get install -y build-essential curl git lsb-release gnupg

# Optionally: add a custom configuration file
WORKDIR /root/.transitive
COPY config.json .

# Fill in id and token from the curl command on your fleet page.
RUN curl -sf "" | bash

CMD ["./"]

The script run by the curl command will install the agent and detect the docker build environment, so it won't start the agent right away. Instead it will check the config.json file, if one was provided, and pre-install any specified desiredPackages. See Configuration for an example.

Edit your entrypoint or CMD script to include:

if [ ! -e $HOME/.transitive/.installation_complete ]; then
cp -r /transitive-preinstalled/. $HOME/.transitive
rm -rf /transitive-preinstalled
cd $HOME/.transitive

Note: the . at the end of the source in the cp command is important.

Make sure your is executable (chmod +x


  • Since Transitive uses linux namespaces to sandbox capabilities, you need to run your container with --privileged. Using --security-opt seccomp=unconfined might work, too.
  • Inside your container, $HOME/.transitive needs to be a bind-mounted folder from your host. For instance, run mkdir $HOME/transitive-docker and run your container with -v $HOME/transitive-docker:/root/.transitive, if running as root inside your container.
    • This is required for two reasons:
      • to give Transitive a place where it can permanently store files, and
      • to allow usage of this folder for creating an overlayfs mount onto /usr inside the container.
  • Make sure, /etc/machine-id is not empty, e.g., run hostname > /etc/machine-id as part of your entry point. The ID you set needs to be unique for each robot in your fleet. Usually the file is written by systemd on first boot using a randomly generated id that is long enough to assume it is globally unique. But since docker images are, of coruse, usually shared between devices, this uniqueness guarantee may not exist, or the file may be empty completely if systemd is not used in the container.
    • Alternatively you can set the TR_INSTALL_HASH environment variable to an ID of your own choosing in the docker run command.


docker run --privileged -v $HOME/.transitive:/root/.transitive -e TR_INSTALL_HASH=bot123 TAGNAME