ViberglassViberglassDocs
← Back to site

Clankers

A clanker is a saved configuration for an AI worker. It bundles together an agent (which CLI to drive: Claude Code, Codex, Qwen CLI, Gemini CLI, OpenCode, Kimi Code, or Mistral Vibe), a deployment strategy (where it runs: AWS Lambda, AWS ECS, or Docker), the secrets it needs, and any custom AGENTS.md / skills/ files.

You configure clankers from Platform → Clankers in the web UI. This page covers the data model and the operational details from an admin's perspective.

AWS Lambda Container

Runs the worker as a Lambda function backed by a container image in ECR. Best for short-lived jobs.

{
  "computeType": "lambda",
  "imageUri": "123456789012.dkr.ecr.eu-west-1.amazonaws.com/viberator-worker:dev-latest",
  "timeout": 900,
  "memorySize": 3008,
  "vpcConfig": {
    "subnetIds": ["subnet-..."],
    "securityGroupIds": ["sg-..."]
  }
}

When you click Start on a Lambda clanker the platform calls ClankerProvisioningService.deployLambda(), which creates or updates the function, registers the IAM execution role, and updates the clanker status to active once the function reaches the Active state.

AWS ECS

Runs the worker as an ECS Fargate task. Best for long-running jobs (Lambda's 15-minute ceiling does not apply) and for clankers that need more memory or persistent network paths.

{
  "computeType": "ecs",
  "cluster": "arn:aws:ecs:eu-west-1:123456789012:cluster/dev-viberglass-worker-cluster-9821611",
  "taskDefinitionArn": "arn:aws:ecs:eu-west-1:123456789012:task-definition/viberator-worker-claude-code-ecs:2",
  "taskFamily": "viberator-worker-claude-code-ecs",
  "launchType": "FARGATE",
  "cpu": 1024,
  "memory": 2048,
  "containerImage": "123456789012.dkr.ecr.eu-west-1.amazonaws.com/viberator-worker-multi-agent"
}

The clanker detail page in the UI surfaces the cluster ARN, task definition ARN, family, revision, status, registration time, CPU, memory, and container images so you can confirm what is actually running without dropping into the AWS console.

When you start an ECS clanker the platform registers a fresh task definition revision, then runs ecs.runTask() against it for every job. The clanker status moves to active once the task definition is registered.

Docker

Runs the worker as a local Docker container via the Docker socket. Used for self-hosted installs and for development. Configuration:

{
  "computeType": "docker",
  "containerImage": "viberator-worker:latest",
  "networkMode": "bridge"
}

The platform shells out to the local Docker daemon to start the container with the bootstrap payload as an env var.

Lifecycle

  1. Create — Open Clankers → New Clanker. Fill in the metadata (name, description), pick the agent, attach secrets, choose a deployment strategy, fill in the strategy-specific config, and optionally attach an AGENTS.md plus skill files.
  2. Save — Creating a clanker stores its settings only. The clanker is in inactive state until you provision it.
  3. Start / Provision — On the clanker detail page, click Start (or Deploy, depending on the strategy). The platform routes to ClankerProvisioningService, which calls the strategy-specific deploy handler. Status moves through deploying → active (or failed with status_message).
  4. Run jobs — Once active, the clanker is selectable on tickets, claws, and project SCM execution settings.
  5. Edit — Editing the clanker creates a new revision of the deployment artifact (Lambda alias bump or new ECS task definition revision). The status indicator on the detail page reflects the latest deployment. You need to redeploy/start the clanker for changes to take effect.
  6. Deactivate / Delete — Click Deactivate to keep the configuration but stop accepting new jobs, or Delete clanker to remove it entirely. Deletion does not automatically tear down the underlying AWS resources; clean those up via Pulumi or the AWS console.

Secrets

A clanker's secret_ids array picks the entries that should be injected into the worker environment. Open the clanker's edit page and tick the secrets you need.

The same secret can also be attached at the task-template level (for claws) or via an integration credential (for SCM operations). The worker merges all three sets together at runtime, so it's fine to keep the clanker's secret list short and add task-specific ones on the templates.

Configuration files

Clankers can carry an AGENTS.md and any number of skill files under skills/. The new clanker form has:

  • An AGENTS.md textarea with an Upload .md button.
  • A Skill Files (skills/)** section with Upload .md Files and Add Skill buttons. Each skill must use a path under skills/, for example skills/review.md.

These files are stored in clanker_config_files and dropped into the worker's scratch directory before the agent boots. They behave exactly like the AGENTS.md and skills you would put in a normal agent repo.

Agent images

Every clanker references a container image for its worker. The default images live in ECR under viberator-worker-* repositories and are built from infra/workers/docker/. See Clanker Images for the build, tag, and push workflow.

Next
Clanker Images