Docker DCP Worker

Docker image · register and run, CPU or NVIDIA GPU · tested on Ubuntu 24.04 and macOS

Before you start, you'll need two things from your Distributive account:

The machine needs Docker and outbound HTTPS to the internet. On Linux, run the commands as a user in the docker group, or put sudo in front of each docker command.

Deploying to a Kubernetes cluster instead? See Kubernetes DCP Workers.

1 GPU host setup (NVIDIA only, once)

Skip this step for a CPU-only worker. For an NVIDIA GPU on Ubuntu, install the driver and the NVIDIA Container Toolkit, then reboot: 

sudo apt-get update && \
sudo apt-get install -y nvidia-driver-570 curl gpg && \
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg && \
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list >/dev/null && \
sudo apt-get update && \
sudo apt-get install -y nvidia-container-toolkit && \
sudo nvidia-ctk runtime configure --runtime=docker --set-as-default && \
sudo reboot

Use the full driver package (nvidia-driver-<version>), not a compute-only or headless one: the worker runs GPU work through WebGPU, which needs the driver's graphics libraries. After the reboot, nvidia-smi should list your GPU, and docker info | grep -i "default runtime" should show nvidia. With NVIDIA as Docker's default runtime, the worker finds the GPU without any extra flags, so the commands in step 2 are the same on every machine.

2 Register and run

Fill in your values and the commands below update. Nothing you type leaves this page.

Or copy the commands as-is and replace the placeholder values before running them.

Register the worker (once per machine):

docker volume create dcp-worker && \
docker run --rm -v dcp-worker:/opt/dcp/.dcp distributivenetwork/dcp-worker \
  --register=0xYOUR_REGISTRATION_KEY && \
echo "Waiting 65 s for registration to take effect..." && \
sleep 65

Start the worker:

docker run -d --name dcp-worker --restart unless-stopped \
  -v dcp-worker:/opt/dcp/.dcp distributivenetwork/dcp-worker \
  --no-global --earnings-account=0xYOUR_EARNINGS_ACCOUNT

What they do:

  1. Create a Docker volume named dcp-worker that holds the worker's identity. It outlives the container, so updating or recreating the container keeps the same registered worker.
  2. Register the worker to your account in a short-lived container, then wait 65 seconds: a new registration takes up to a minute to reach the worker.
  3. Start the worker in the background. --restart unless-stopped brings it back after a crash or a reboot, --no-global means it only runs jobs from your own compute groups, and --earnings-account sends its earnings to your account.
  4. GPU work needs no extra options. WebGPU is on by default in the image, and on a machine set up in step 1 the worker uses the NVIDIA GPU for WebGPU jobs. On a machine without a supported GPU it turns WebGPU off by itself and runs CPU work only.

3 Confirm it's running

docker logs -f dcp-worker

A healthy startup on an NVIDIA machine includes:

* Starting Distributive Worker <worker-id>
. WebGPU available. GPU info:
   - vendor: nvidia
   - device: nvidia-l4
. Configured Cores:    cpu: 4    gpu: 1
! Leaving the global compute group
* Ready.

On a CPU-only machine you'll see gpu: 0 instead. When a job from one of your compute groups is available you'll see Slice Completed lines. Press Ctrl+C to stop watching (the worker keeps running). To list the compute groups the worker will use: 

docker exec dcp-worker sudo -u dcp /opt/dcp/bin/dcp-worker.sh --show=compute-groups --no-global

4 Stopping, restarting, and updating

Stop, letting running slices finish (up to 5 minutes):

docker stop -t 300 dcp-worker

Start again:

docker start dcp-worker

Update to the latest image:

docker pull distributivenetwork/dcp-worker && \
docker stop -t 300 dcp-worker && \
docker rm dcp-worker

Then run the Start the worker command from step 2 again. No need to register again: the identity is in the dcp-worker volume. To change the earnings account or other options, remove the container the same way and start it with the new options.

5 Uninstalling

Remove the worker, keeping its identity:

docker rm -f dcp-worker && \
docker rmi distributivenetwork/dcp-worker

The identity stays in the dcp-worker volume, so starting a worker with that volume later brings back the same registered worker.

To remove everything, also delete the volume. This deletes the worker's identity; registering again later creates a new worker. 

docker volume rm dcp-worker

6 Troubleshooting

Running and Ready, but never gets work: check that a job is actually running in one of your compute groups, then restart the worker with docker restart dcp-worker. A worker started too soon after registering can miss its compute groups until it restarts.

The log says This GPU is not supported; disabling: the container only found the software renderer, not your GPU. Check that nvidia-smi works on the host and that docker info | grep -i "default runtime" shows nvidia. If it doesn't, run sudo nvidia-ctk runtime configure --runtime=docker --set-as-default && sudo systemctl restart docker, then remove and start the worker again.

macOS and Windows: Docker Desktop doesn't give containers access to the GPU, so the worker runs CPU work only. On Apple silicon, the same commands pull the arm64 image automatically.

Registration fails: check the key was copied completely, and that it hasn't already been used up or expired in your account.