Worker Pools
By default, everything InfraDots runs, from Terraform/OpenTofu plans and applies to AI reviews and implementations, runs on InfraDots infrastructure. A worker pool moves that work into your environment: you run the runners in your own Kubernetes cluster or on your own servers, and InfraDots routes work to them.
Why run your own pool
- Network access: plans and applies can reach private APIs, VPN-only endpoints and internal registries.
- Compliance and data residency: your code is cloned, and your infrastructure is changed, from inside your network.
- Your own model account: AI agent runs use your Anthropic, AWS Bedrock, Google Vertex AI or Azure AI Foundry account, and don't count against your InfraDots AI interactions.
- Control: you choose the machines, the network policy, and when to upgrade.
The runners only connect out to InfraDots over HTTPS, so nothing needs to reach into your network.
Two kinds of pool
| Kind | Runs | Runner | Assigned to |
|---|---|---|---|
| Executor | Terraform, OpenTofu and Terragrunt plans and applies | idp-executor | Workspaces |
| Agent | AI reviews of pull requests, and AI implementations | idp-agent | Your organization, or individual workspaces |
A pool's kind is fixed when you create it, and its token is only good for that kind of work. You can have both kinds, and several of each, for example one pool per environment.
Creating a pool
- Open Organization settings → Worker Pools.
- Click Create Worker Pool, choose the kind (executor or agent), and enter a name.
- Copy the registration token. It's shown only once.
⚠️ Warning
[!warning] The registration token lets a runner join your pool and receive its work. Store it as a secret (a Kubernetes Secret or your secret manager), never in a repository.
Managing pools (creating, editing, deleting and rotating tokens) requires the organization's write permission, which organization admins have. Every member can see the pools.
Then start the runners: see Self-hosted runners for the Helm chart and for Docker on a VM.
Assigning work to a pool
Executor pools are set per workspace: open the workspace's Settings → General and choose the Worker Pool. You can also set it when you create the workspace. Only executor pools are offered.
Agent pools are set for the whole organization, for individual workspaces, or both. Each agent run goes to the first of these that is set:
- The workspace's agent pool
- The organization's agent pool
- InfraDots infrastructure (the default)
ℹ️ Info
[!info] InfraDots never falls back to its own infrastructure for a workspace that has a pool. If no runner in the pool picks a run up, the run waits, and fails after two hours with a message saying why.
Runner health
Each pool lists its runners with their version and whether they're online (in contact within the last five minutes). Agent runners also show their model provider.
A runner that's too old for the work InfraDots sends shows needs upgrade, with the reason. InfraDots keeps working with the previous runner version, so you can upgrade on your own schedule; see Upgrades.
Rotating a token
If a registration token may have leaked, use Rotate token on the pool. You get a new token, shown once. The old token stops working immediately, so every runner still using it stops at its next request: update their secret and restart them.
Troubleshooting
A runner doesn't appear in its pool
- Read its log. A runner keeps retrying registration while it can't reach InfraDots.
- Check that it can reach your InfraDots URL (
app.infradots.com) on port 443, directly or through your proxy. - Check that it uses the pool's current token, especially after a rotation.
- Agent runners have a built-in check,
idp-agent doctor; see Self-hosted runners.
Agent runs wait, then fail
The run's message says which of these happened:
- No runner was online in the pool. Start one, then retry.
- The pool's runners need an upgrade. Upgrade the runner, then retry.
- All runners were busy. Each runner handles one run at a time; add replicas.
A run fails asking you to add a model to MODEL_MAP
The agent runner uses your own cloud's model ids. Map every model InfraDots uses; see Your model account.
Best practices
- One pool per environment or network zone. For example, separate pools for production and non-production accounts, each with only the cloud access that environment needs.
- More replicas for throughput. Each runner handles one job or run at a time.
- Give runners least privilege. Executors need exactly the cloud permissions your Terraform needs. Agent runners need no cloud permissions beyond their model provider.
- Rotate tokens when people leave or a secret may have been exposed.