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.

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.

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#