Skip to content

Deploy a Gaia worker with Docker

Deploy a yasp-eval worker on a single host with docker run. For a Kubernetes cluster or fleet, use Deploy with Helm instead.

These steps run on the target machine — or let the agent do it for you; see Gaia workers.

Set three values

Set your API key and mint a long-lived (about 6 months) registry key from it:

export YASP_API_KEY='yasp_...'

export REGISTRY_KEY=$(yasp-toolkit registry key)

export REGISTRY_KEY=$(curl -fsS -X POST \
  -H "Authorization: Bearer $YASP_API_KEY" -G \
  --data-urlencode "audience=nexus-api" \
  --data-urlencode "scope=nexus-read" \
  "https://compile.yasp.ai/api/token")

Store a Gaia (eval) long-lived worker register key (~6 months) so the worker can register.

export GAIA_WORKER_KEY=$(yasp-toolkit eval key)

export GAIA_WORKER_KEY=$(curl -fsS -X POST \
  -H "Authorization: Bearer $YASP_API_KEY" -G \
  --data-urlencode "audience=eval-api" \
  --data-urlencode "scope=eval-register" \
  "https://compile.yasp.ai/api/token")

Alternatively, you can continue to use your API key: 

export KRONOS_WORKER_KEY="$YASP_API_KEY"

Deploy

Pick the tab for your GPU vendor and run its three blocks in order: pull the image, start the worker, then add the autoheal sidecar and confirm registration.

1. Log in with your minted key and pull the image

echo "$REGISTRY_KEY" | docker login docker.yasp.ai -u token --password-stdin

export TAG=$(curl -fsS -u token:"$REGISTRY_KEY" \
  "https://docker.yasp.ai/v2/yasp-eval/nvidia/tags/list" \
  | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)
export IMAGE=docker.yasp.ai/yasp-eval/nvidia:$TAG
docker pull "$IMAGE"

2. Start the worker

docker run --detach --name eval_prod --restart unless-stopped \
  --runtime nvidia --label autoheal=true \
  --health-cmd "yasp-eval health live" \
  --health-interval=30s --health-timeout=5s --health-retries=3 --health-start-period=60s \
  -e NVIDIA_VISIBLE_DEVICES=all \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e YASP_API_KEY=$GAIA_WORKER_KEY \
  -e YASP_LAUNCH_WORKER_IMAGE=$IMAGE \
  -e YASP_LAUNCH_DOCKER_GPUS=all \
  -e YASP_LAUNCH_DOCKER_SHM_SIZE=8g \
  -e YASP_LAUNCH_DOCKER_VOLUMES=yasp-dataset-cache:/mnt/dataset-cache \
  -e YASP_DATASET_CACHE_DIR=/mnt/dataset-cache \
  -e YASP_LAUNCH_DOCKER_FORWARD_ENV=YASP_DATASET_CACHE_DIR \
  $IMAGE yasp-eval register \
    --tag host=$(hostname -s) --tag version=$TAG --tag last_update=$(date +%F)

On Jetson (Tegra), swap YASP_LAUNCH_DOCKER_GPUS=all for YASP_LAUNCH_DOCKER_RUNTIME=nvidia — its csv mode rejects --gpus.

3. Add the autoheal sidecar and confirm registration

docker ps --filter name=^autoheal$ --format '{{.Names}}' | grep -q autoheal \
  || docker run --detach --name autoheal --restart always \
       -e AUTOHEAL_DEFAULT_STOP_TIMEOUT=30 \
       -v /var/run/docker.sock:/var/run/docker.sock willfarrell/autoheal

docker logs eval_prod 2>&1 | grep -iE 'API Key OK|worker_registered'

1. Log in with your minted key and pull the image

echo "$REGISTRY_KEY" | docker login docker.yasp.ai -u token --password-stdin

export TAG=$(curl -fsS -u token:"$REGISTRY_KEY" \
  "https://docker.yasp.ai/v2/yasp-eval/amd/tags/list" \
  | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | sort -V | tail -1)
export IMAGE=docker.yasp.ai/yasp-eval/amd:$TAG
export RENDER_GID=$(getent group render | cut -d: -f3)
docker pull "$IMAGE"

2. Start the worker

docker run --detach --name eval_prod --restart unless-stopped \
  --label autoheal=true \
  --health-cmd "yasp-eval health live" \
  --health-interval=30s --health-timeout=5s --health-retries=3 --health-start-period=60s \
  --device /dev/kfd --device /dev/dri \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  --group-add video --group-add "$RENDER_GID" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e YASP_API_KEY=$GAIA_WORKER_KEY \
  -e YASP_LAUNCH_WORKER_IMAGE=$IMAGE \
  -e YASP_LAUNCH_DOCKER_DEVICES=/dev/kfd,/dev/dri \
  -e YASP_LAUNCH_DOCKER_GROUP_ADD=$RENDER_GID \
  -e YASP_LAUNCH_DOCKER_SHM_SIZE=8g \
  -e YASP_LAUNCH_DOCKER_VOLUMES=yasp-dataset-cache:/mnt/dataset-cache \
  -e YASP_DATASET_CACHE_DIR=/mnt/dataset-cache \
  -e YASP_LAUNCH_DOCKER_FORWARD_ENV=YASP_DATASET_CACHE_DIR \
  $IMAGE yasp-eval register \
    --tag host=$(hostname -s) --tag version=$TAG --tag last_update=$(date +%F)

3. Add the autoheal sidecar and confirm registration

docker ps --filter name=^autoheal$ --format '{{.Names}}' | grep -q autoheal \
  || docker run --detach --name autoheal --restart always \
       -e AUTOHEAL_DEFAULT_STOP_TIMEOUT=30 \
       -v /var/run/docker.sock:/var/run/docker.sock willfarrell/autoheal

docker logs eval_prod 2>&1 | grep -iE 'API Key OK|worker_registered'

worker_registered in the output means it's up. It then appears in yasp-toolkit eval workers on your reference machine, with its auto-detected GPU. If it doesn't, run docker logs eval_prod and send the output to support@yasp.ai.

What the load-bearing flags do
  • $TAG — the newest image, read from the registry. Eval tags are bare semver (no v): chart 1.6.2 ↔ image 1.6.2.
  • --group-add $(stat …) — docker-socket access so the worker can spawn the per-task evaluation containers it runs each job in.
  • GPU — NVIDIA maps the card with --runtime nvidia; AMD maps /dev/kfd + /dev/dri and the video/render groups. The YASP_LAUNCH_DOCKER_* vars pass the same access to the per-task siblings — full set in the Launcher reference.
  • --health-cmd + autoheal sidecar — --restart doesn't fire on unhealthy, so the sidecar restarts a worker whose liveness check goes stale.
  • --tag host=… — target this box later; with no routing tag it joins the shared stable pool. See Tags & routing.

Upgrade, stop, or remove

Re-run the three blocks to upgrade — docker pull fetches the newest image and docker run recreates the container. To stop or remove it:

docker stop eval_prod        # pause (docker start eval_prod to resume)
docker rm -f eval_prod       # remove entirely (add: docker rm -f autoheal)