Build Pools

A Build Pool connects Citadel to dedicated builder infrastructure. Select a pool in a Build Project when builds should run separately from your managed application Platforms.

Creating, testing, and managing a pool is available in Community. Running builds through a pool requires Elastic Build Execution. Webhook-triggered pool builds also require Automated Operations. Existing in-flight builds may finish or be cancelled after a license change; queued builds cannot acquire capacity without the required capability.

Self-managed VM pools with Inbound Agent or Edge Agent connections are currently executable. AWS EC2 provisioning is not implemented and cannot be selected for new pools. A manually provisioned VM hosted in AWS works as a self-managed builder. Saved AWS configurations remain inspectable and can be disabled or deleted; Citadel does not convert them or queue builds against them.

Configure a poolCopy Anchor Link

Use a Build Pool when builds should run on builder infrastructure rather than on one of the Docker platforms managed by Citadel.

For a self-managed VM pool, choose one connection mode.

Maximum concurrent builds controls how many preparing or running builds the pool can accept. It defaults to one. A self-managed pool connects to one Agent; the setting does not create additional workers or provision machines. Core's build concurrency limit also applies across pools and Platforms.

Inbound Agent endpointCopy Anchor Link

Use this when Citadel Core can reach the builder host directly. Save the pool first, then copy the Agent Setup command from its configuration and run it on the builder. Citadel fills in its unique ID and public key automatically.

The following manual template is equivalent; copy <generated-agent-id> from the pool’s setup command. Replace AGENT_IMAGE with the image address expected by your Core version and ... with Core's current CITADEL_CORE_PUBLIC_KEY, as described in regular Agent setup. The HTTP example below is for a trusted private network; use Agent TLS when the connection needs encryption.

docker run -d \
  --name citadel-agent-build \
  --restart=always \
  -p 9001:9000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CITADEL_CORE_PUBLIC_KEY="..." \
  -e CITADEL_AGENT_ID="<generated-agent-id>" \
  AGENT_IMAGE

Use these settings when creating the pool:

Build Pools -> Add Build Pool
Provider: Self-managed VM / Static VM
Connection mode: Inbound Agent endpoint
Endpoint: http://<builder-host>:9001

On Docker Desktop, when Core also runs in Docker on the Agent host, use:

http://host.docker.internal:9001

On native Linux, add a host-gateway mapping to the Core service and recreate Core with the overlay:

services:
  server:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Alternatively, attach Core and the Agent to a shared Docker network and use http://citadel-agent-build:9000. Port 9001 is the published host port; 9000 is the Agent's container port. See Compose networking.

Click Test on the Build Pool before selecting it in a build project. A ready pool confirms that Citadel can reach the Agent and that the Agent can reach Docker.

Edge AgentCopy Anchor Link

Use this when the builder host should connect outbound to Citadel Core and should not expose a build Agent port.

Create and save the build pool first:

Build Pools -> Add Build Pool
Provider: Self-managed VM / Static VM
Connection mode: Edge Agent

After the pool is saved, open the pool's configuration and generate an Edge Agent enrollment token from the Edge Agent enrollment section. Citadel shows a Docker command for that build pool. Run it on the builder host.

The build pool Edge Agent is scoped to the build pool itself. You do not need to create a Platform resource, and there is no Edge Agent platform dropdown for build pools.

The generated command uses the Edge Agent gRPC endpoint. Its container port is 8001; the optional Edge overlay publishes it at 127.0.0.1:18001. A remote builder needs a reachable, secured gRPC address rather than the browser port or a local-only address.

Click Test on the Build Pool before selecting it in a build project. A ready edge pool confirms that the pool-scoped Edge Agent is connected, advertises build capabilities, and can reach Docker.

Build pool connection and availabilityCopy Anchor Link

For Edge Agent pools, the pool list shows the agent connection status separately from the latest Docker build capability check. Connection changes update through realtime notifications. The pool activity history records one Connected or Disconnected event per transition, including disconnects detected by heartbeat expiry and binding revocation.

The Build Pool Unavailable system rule raises a warning after an enabled self-managed pool fails its capability checks for at least 90 seconds. This covers both a disconnected agent and a connected agent whose Docker builder is unusable. Checks run periodically, so an alert can appear after the grace period on the next check. The outage start is retained across Core restarts.

The alert resolves when a capability check succeeds. Disabled, archived, and never-connected Edge pools do not raise availability alerts. Disabling or archiving a pool clears its availability incident. Configure notification channels on the rule; advanced alerting also allows changing the grace period and limiting the rule to selected build pools.

Use a pool in a Build ProjectCopy Anchor Link

After saving and testing the pool, choose Build Pool as the project's runner and select the pool. The project defines the repository, build context, Registry, and output image; the pool supplies the execution host.

If a build cannot start, check the pool's connection and Docker capability status, then see Build Project troubleshooting.

Citadel automatically includes CITADEL_AGENT_ID in each Direct Agent install command. This UUID identifies the Platform or dedicated Build Pool independently of its network address. Keep it when restarting the Agent or changing its address; use a separate setup command for each Platform or Build Pool. Requests signed for a different ID are rejected, even when Agents have identical addresses on separate networks. Edge Agents use enrollment and do not need this setting.

For an existing Platform, copy the command from its Agent Setup section. For an inbound Build Pool, save the pool first, then open its configuration to copy the command. API clients may obtain a generated agentId from GET /api/v1/platforms/agent/setup and submit it with Direct Platform creation. Existing Platform and Build Pool IDs are preserved.