Skip to content

Worker Pools

Worker pools provide the compute that executes your Terraform and OpenTofu runs. Zenfra runs a managed Public Worker Pool, and you can run Private Worker Pools on your own infrastructure when runs need to reach private networks or hold credentials that must not leave your environment.

Public Worker Pool

The Public Worker Pool is managed by Zenfra and needs no setup. The Workers page lists it first, as Public Worker Pool · Active · Managed. Choose it in the stack wizard when you do not need a private worker.

Private Worker Pools

A private worker is a container you run. It dials out to Zenfra, claims runs for its pool, and executes them on the host it runs on. Nothing needs to accept inbound connections.

Creating and managing pools requires the Admin role; for other roles Create Pool is disabled (Admin access required).

Creating a private pool

  1. Navigate to Workers in the sidebar and click Create Pool.
  2. Provide a name (3 to 50 characters; letters, numbers and hyphens).
  3. Zenfra shows the pool's API key once (Save your API key). Copy it and store it securely; it cannot be retrieved later. If you lose it, rotate the key (below).

The pool detail page then shows the Pool ID and a Quick Start command that already contains it.

Quick Start

docker run -d --restart=unless-stopped --name zenfra-worker \
  -e ZENFRA_WORKER_API_BASE_URL=https://api.zenfra.cloud \
  -e ZENFRA_WORKER_POOL_ID=<pool_id> \
  -e ZENFRA_WORKER_POOL_API_KEY=<api_key> \
  ghcr.io/zenfracloud/zenfra-worker:latest

Follow the Private Worker Setup guide for prerequisites, persistent mounts, disk sizing, upgrading and troubleshooting.

Pool detail page

Pool Information

Field Description
Pool ID Unique identifier for the pool; the value of ZENFRA_WORKER_POOL_ID
Type PRIVATE for self-hosted pools
Status Active or Inactive
API Key ID Identifier of the current API key (not the key itself)
Key Version Increments on each rotation
Created When the pool was created
Last Used When a worker last connected

Pool Capacity

Worker slot allocation for the whole organization: Online Workers, Org Slots Used, Available, and how many slots other pools are using.

Connected Workers

Every worker that has connected to this pool, with Worker ID, Status (Online / Offline), Capabilities (the Terraform and OpenTofu versions and providers it reports) and Last Seen. Workers register on connect and report their status with periodic heartbeats; the table updates automatically.

Managing a pool

The list row menu and the detail page Actions menu offer:

  • Edit: rename the pool or switch its Status. Deactivating prevents new task assignments. Activate it again to resume.
  • Rotate API Key: generates a new key and invalidates the current one immediately. Every worker using the old key disconnects. The new key is shown once. A running container keeps its old variables, so re-create each worker container with the new key (see Upgrading).
  • Deactivate / Activate: the same status switch as in Edit.
  • Delete: removes the pool permanently, disconnects its workers and invalidates the API key. You type the pool name to confirm. This cannot be undone.

Worker Pools list

The Workers page shows every pool with Name, Status (Active / Inactive), Workers (connected count), Slots (used / total), Created, Last Used and Actions.

Organization-level capacity

Worker slots are allocated per organization, and your plan determines the total. Organization > Overview shows Slots Used and Slots Available, and Organization > Billing shows the current plan. Plan changes go through support@zenfra.cloud. (Organization > Worker Pools only links back to the Workers page.)

Assigning pools to stacks

When creating a stack you choose the worker pool in the Basic Info step (the Public Worker Pool or one of your private pools); you can change it later under Stack details when editing the stack. All runs for the stack execute on that pool.

An AWS integration with Generate credentials in worker enabled requires a private pool: the worker's own AWS identity assumes your role, so a run on the Public Worker Pool fails with worker credential mode requires a private worker pool.

Upgrading a private pool across the September 2026 release needs a drain-and-discard step; see the September 2026 Upgrade Notes.