Deploying the Helix Controlplane

Deploying the Helix Controlplane


See Architecture to understand how the control plane fits in.

Deployment on Docker Compose

Requires: x86_64 architecture, docker

git clone
cd helix
git checkout 0.6.9
cp .env.example-prod .env

Now edit .env with the editor of your choice.

docker compose up -d

You’ll want to point a DNS hostname at the IP address of your server.

Then load http://<YOUR_CONTROLPLANE_HOSTNAME> in your browser (the app runs on port 80).


Check configuration:

cd helix
git pull
git checkout 0.6.9

Open .env.example-prod and compare it to your current .env to check whether there are any new or changed configuration requirements.

Deploy the upgrade:

docker compose pull
docker compose up -d --remove-orphans

Version-specific upgrade notes

Attaching a runner

Requires: x86_64 architecture, Linux and NVIDIA

Ensure you have the NVIDIA docker toolkit installed.

sudo docker run --privileged --gpus all --shm-size=10g \
    --restart=always -d \
    --name helix-runner --ipc=host --ulimit memlock=-1 \
    --ulimit stack=67108864 \
    -v ${HOME}/.cache/huggingface:/root/.cache/huggingface \ \
    --api-host <http(s)://YOUR_CONTROLPLANE_HOSTNAME> --api-token <RUNNER_TOKEN_FROM_ENV> \
    --runner-id $(hostname) \
    --memory <GPU_MEMORY>GB \


  • Update <GPU_MEMORY> to correspond to how much GPU memory you have, e.g. “80GB” or “24GB”
  • You can add --gpus 1 before the image name to target a specific GPU on the system (starting at 0). If you want to use multiple GPUs on a node, you’ll need to run multiple runner containers (in that case, remember to give them different names)
  • Make sure to run the container with --restart always or equivalent in your container runtime, since the runner will exit if it detects an unrecoverable error and should be restarted automatically
  • If you want to run the runner on the same machine as the controlplane, either: (a) set --network host and set --api-host http://localhost so that the runner can connect on localhost via the exposed port, or (b) use --api-host so that the runner can connect to the API server via the docker bridge IP

Runner upgrades

docker rm -f helix-runner

Then run the command above.

Questions? Bugs?

Come find us on Discord.

Last updated on