Clanker Images | Viberglass Docs

How worker images are built, tagged, pushed, and selected at runtime.

Where the Dockerfiles live

All worker Dockerfiles are under infra/workers/docker/ in the viberator monorepo:

Building and pushing

All images are built and pushed by infra/workers/scripts/setup-harness-images.sh. The script:

Resolves your AWS account, region, and ECR registry hostname from your shell environment.
Creates the ECR repositories that don't yet exist (aws ecr create-repository).
Builds each image with docker buildx build, taking advantage of layer caching for Node modules.
Tags the result with both an environment-specific tag (dev or prod) and latest.
Pushes the image to ECR.

Usage:

# Build and push every image to the dev registry
./infra/workers/scripts/setup-harness-images.sh dev

# Build and push only the multi-agent image
./infra/workers/scripts/setup-harness-images.sh dev multi-agent

# Build for production
./infra/workers/scripts/setup-harness-images.sh prod

The script is idempotent. Re-running it after a small change rebuilds only the affected layers thanks to Buildx caching.

CI/CD

The same script is wrapped by the deploy-viberators.yml GitHub Actions workflow. Triggers:

Automatic — pushes to main that touch apps/viberator/** or infra/workers/docker/**.
Manual — workflow_dispatch with a harness selector (claude, codex, qwen, gemini, opencode, mistral, kimi, multi-agent, or all) and an environment selector (dev/prod).

The workflow:

Authenticates to AWS via OIDC (no static credentials).
Logs into ECR.
Runs the build/push script for the selected images.
Uploads a build summary listing every image and tag pushed.

For the broader deployment story (Pulumi, backend ECS, frontend Amplify), see Deployment.

Image naming

Images are pushed to ECR with these repository names:

Repository	Used by
`viberator-worker-multi-agent`	Multi-agent ECS clankers and the default Lambda image.
`viberator-worker-claude-code-ecs`	Claude Code ECS clankers (the original lean image).
`viberator-worker-<agent>`	Single-agent ECS clankers (one per supported agent).

Tags follow the pattern <env>-<sha> plus floating tags <env>-latest and latest. The clanker's deployment_config references either the immutable <env>-<sha> tag (for reproducible deploys) or the floating tag (for "always run the latest dev image").

Image selection at job time

Each clanker stores its image in deployment_config:

For Lambda: imageUri (full ECR URI with tag).
For ECS: containerImage (full ECR URI; the platform attaches it to the task definition during provisioning).
For Docker: containerImage (image name resolvable by the local daemon).

When a job is dispatched, the worker invoker reads this config and uses it to:

Lambda: pass the ImageUri when updating the function configuration.
ECS: include it in the container definition of the task definition revision.
Docker: pull and run the image locally.

You can switch a clanker between agents by editing the clanker, picking a different agent type, and changing the imageUri to the matching agent-specific repo. After saving, click Start to roll the new image into the underlying Lambda function or ECS task definition.

Local development

For local Docker workers, you usually don't need ECR at all. The docker-compose.yml at the repo root builds a worker image from viberator-docker-worker.Dockerfile and points the local clanker at viberator-worker:latest. Rebuild with:

docker compose build worker

The worker volume-mounts the platform's bootstrap payload directory, so jobs run end-to-end without anything in AWS.