Deploy a Gyoza Worker#

A worker polls the gyoza server for pending OpRuns and executes them as Docker containers. You can run as many workers as needed, the server scheduler distributes work across all active workers. This guide shows how to deploy a worker using the Docker Compose setup included in the gyoza repository.

Prerequisites#

Environment variables#

The Docker Compose file reads several environment variables at startup. You can set them in a .env file at the repository root or export them directly in your shell.

Variable

Default

Description

GYOZA_SERVER_URL

http://localhost:5555

Base URL of the gyoza server this worker connects to.

GYOZA_API_KEY

(empty)

API key for authenticating with the server. Must match the GYOZA_API_KEY configured on the server.

GYOZA_WORKER_ID

worker-1

Unique identifier for this worker instance. Each worker in the cluster must have a distinct ID. If left empty, a random UUID will be generated.

GYOZA_WORKING_DIRECTORY

/tmp/gyoza

Host directory used to stage op run data (input/output JSON files and temporary volumes). This path is bind-mounted into both the worker container and the op containers it spawns.

GYOZA_HEARTBEAT_INTERVAL

10

Seconds between heartbeat ticks sent to the server.

GYOZA_DOCKER_CONFIG

$HOME/.docker

Docker config directory the worker uses to pull op images. Point this at a dedicated directory to give the worker its own registry account, separate from the host’s. See Use a separate registry account (optional).

GYOZA_MOUNTS

(empty)

Comma-separated host:container[:ro|:rw] paths mounted into every op container. See Share a cache or credentials with every op (optional).

GYOZA_CONTAINER_ENV

(empty)

Comma-separated KEY=VALUE pairs set on every op container. See Share a cache or credentials with every op (optional).

A minimal .env file looks like this:

GYOZA_SERVER_URL=http://gyoza-server:5555
GYOZA_API_KEY=my-secret-key
GYOZA_WORKER_ID=worker-12345

Start the worker#

The scripts/start_worker.sh helper wraps Docker Compose so you don’t have to remember the compose file path. From the repository root, run:

./scripts/start_worker.sh up

This builds the gyoza image and starts the worker. By default the process runs in the foreground so you can see the logs directly. To run it in the background, pass the -d flag:

./scripts/start_worker.sh up -d

The script accepts the same actions as docker compose, you can use it to stop the worker, build the image, etc. Any extra arguments after the action are forwarded, so you can use flags like -d, --force-recreate, or --no-cache as needed.

Important

The default Compose file reserves all NVIDIA GPUs on the host so the worker can detect available VRAM and report it in its heartbeats. If your machine does not have a GPU, pass the --no-gpu flag to avoid the GPU reservation.

./scripts/start_worker.sh --no-gpu up

The worker will function normally, it will simply report zero VRAM and only receive ops that have no vram_mb constraint.

Use a separate registry account (optional)#

By default the worker pulls op images with the host’s Docker credentials. To let it pull from a private repository under a different account, log that account into a dedicated directory and point GYOZA_DOCKER_CONFIG at it, everything else stays the same:

echo "<token>" | docker --config ~/gyoza-worker-docker \
  login <registry> -u <username> --password-stdin

GYOZA_DOCKER_CONFIG=~/gyoza-worker-docker ./scripts/start_worker.sh up -d

Use --password-stdin (as above) so the credentials are written into the config’s auths entry. If the file shows "credsStore" instead, they live in an external keychain the worker can’t read.

Share a cache or credentials with every op (optional)#

Where a model cache lives, or which credentials are reachable, is a property of the machine, not of an op. The worker therefore owns both, and gyoza.yml stays free of host paths.

Every op container already receives GYOZA_WORKING_DIRECTORY/cache, mounted at the same path and exported as GYOZA_CACHE_DIR. It sits beside the per-run directories, so it survives the cleanup that wipes a run’s own directory, and a model downloaded by one run is still there for the next. Point a library at it to make that download happen once:

GYOZA_CONTAINER_ENV=MODELBRIDGE_CACHE_DIR=/tmp/gyoza/cache

To place the cache on a specific disk, or to expose anything else, add mounts. Append :ro to keep a mount read-only:

GYOZA_MOUNTS=/mnt/nvme/models:/cache/models,/etc/aws:/aws:ro
GYOZA_CONTAINER_ENV=MODELBRIDGE_CACHE_DIR=/cache/models,AWS_REGION=sa-east-1

Both settings apply to every op the worker runs, so treat a mount as visible to any image the server schedules here. Gyoza’s own GYOZA_INPUT_PATH and GYOZA_OUTPUT_PATH are set last and cannot be overridden. A malformed entry stops the worker at startup rather than failing each run.

Verify the worker is connected#

Once started, the worker registers with the server through its first heartbeat. You can confirm it appeared in the server’s worker list:

curl -H "X-API-Key: my-secret-key" http://localhost:5555/workers

You should see your worker ID in the response with its reported resources.

Run multiple workers#

To scale the cluster, start additional workers on different machines. Each worker must have a unique GYOZA_WORKER_ID, so always set it in your environment variables:

GYOZA_WORKER_ID=worker-23456 ./scripts/start_worker.sh up -d

Stop the worker#

./scripts/start_worker.sh down

Next steps#