Worker Pools
Worker pools provide the compute infrastructure that executes your Terraform and OpenTofu runs. Zenfra offers a managed Public Worker Pool and supports self-hosted Private Worker Pools for organizations that need to run infrastructure operations within their own network.
Public Worker Pool
Every organization has access to the Public Worker Pool, which is fully managed by Zenfra. It requires no setup and is suitable for getting started quickly.
| Property | Value |
|---|---|
| Type | Managed |
| Setup | None required |
| Workers | Managed by Zenfra |
Private Worker Pools
Private worker pools run on your own infrastructure, giving you full control over the execution environment. This is useful when your infrastructure operations need access to private networks, VPNs, or internal resources.
Creating a private pool
- Navigate to Workers in the sidebar and click Create Pool.
- Provide a name for the pool.
- After creation, the pool detail page shows:
- Pool ID — unique identifier
- API Key ID — used by workers to authenticate
- Quick Start — a Docker command to launch workers
Pool detail page
The pool detail page shows:
Pool Information
| Field | Description |
|---|---|
| Pool ID | Unique identifier for the pool |
| Type | PRIVATE for self-hosted pools |
| Status | Active or inactive |
| API Key ID | The access key workers use to connect |
| Key Version | Current version of the API key |
| Created | When the pool was created |
| Last Used | When a worker last connected |
Quick Start
The Quick Start section provides a ready-to-use Docker command for launching workers:
docker run --rm \
-e ZENFRA_WORKER_POOL_ID=<pool_id> \
-e ZENFRA_WORKER_API_KEY=<api_key> \
zenfra/worker:latest
Replace <api_key> with the API key generated when you created the pool.
Pool Capacity
Shows the current capacity across the organization:
- Online Workers — number of workers currently connected
- Org Slots Used — how many of the organization's total worker slots are in use
- Available — remaining capacity
- Progress bar — visual indicator of slot utilization
Connected Workers
A table listing all workers that have connected to this pool, showing:
| Column | Description |
|---|---|
| Worker ID | Unique worker identifier (e.g., wrk_01KJJFQFPQM2PW6QEPVEJS5PCJ) |
| Status | Online or Offline |
| Capabilities | Worker-reported capabilities |
| Last Seen | When the worker last sent a heartbeat |
Workers automatically register when they connect and report their status via periodic heartbeats.
Worker Pools list
The Workers page shows all pools with:
| Column | Description |
|---|---|
| Name | Pool name |
| Status | Active or inactive |
| Workers | Number of connected workers |
| Slots | Used vs. total slots with progress bar |
| Created | When the pool was created |
| Last Used | When the pool was last used for a run |
Organization-level capacity
Worker slot capacity is managed at the organization level. Your plan determines the total number of worker slots available. You can view your organization's slot allocation under Organization > Overview or Organization > Worker Pools.
Assigning pools to stacks
When creating or configuring a stack, you select a worker pool in the Basic Info step. All runs for that stack will execute on the assigned pool.