Agent images

Agent images let you define custom Dockerfile bodies for Buildkite hosted agents. Each agent image is associated with a cluster and is built on top of a Buildkite-managed base image.

This API is available to organizations with Buildkite hosted agents enabled. If Buildkite hosted agents are not enabled for your organization, every endpoint returns 404 Not Found. When they are enabled but the target cluster is not a hosted cluster, list requests return an empty list, get and delete requests return 404 Not Found, and create requests return 422 Unprocessable Entity.

Agent image data model

id ID of the agent image (the Namespace profile ID)
name Name of the agent image
status Build status of the agent image. Possible values: BUILDING, READY, FAILED
image_ref The fully qualified image URL once the agent image has been built. null while the image is still building
version Version number of the agent image
last_build_error Error message from the most recent failed build, or null if no error
dockerfile The user-supplied Dockerfile body (without the FROM instruction). This is the content you would submit in a create request
base_image The Buildkite-managed base image FROM line prepended to every agent image Dockerfile
composed_dockerfile The full Dockerfile sent to the image builder: base_image followed by dockerfile
url Canonical API URL of the agent image
web_url URL of the agent image on Buildkite
cluster_url API URL of the cluster the agent image belongs to

List agent images

Returns the list of a cluster's agent images, sorted alphabetically by name. Non-hosted clusters return an empty list.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/agent-images"

[
  {
    "id": "abc123def4567",
    "name": "my-custom-image",
    "status": "READY",
    "image_ref": "registry.example.com/your-org/buildkite/abc123def4567:v1",
    "version": 1,
    "last_build_error": null,
    "dockerfile": "RUN apt-get update && apt-get install -y curl",
    "base_image": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c",
    "composed_dockerfile": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c\nRUN apt-get update && apt-get install -y curl",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent-images/abc123def4567",
    "web_url": "https://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent_images/abc123def4567",
    "cluster_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf"
  }
]

Required scope: read_clusters

Success response: 200 OK

Get an agent image

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/agent-images/{id}"

{
  "id": "abc123def4567",
  "name": "my-custom-image",
  "status": "READY",
  "image_ref": "registry.example.com/your-org/buildkite/abc123def4567:v1",
  "version": 1,
  "last_build_error": null,
  "dockerfile": "RUN apt-get update && apt-get install -y curl",
  "base_image": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c",
  "composed_dockerfile": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c\nRUN apt-get update && apt-get install -y curl",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent-images/abc123def4567",
  "web_url": "https://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent_images/abc123def4567",
  "cluster_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf"
}

Required scope: read_clusters

Success response: 200 OK

Create an agent image

Buildkite manages the base image for all hosted agent images. Submit only the Dockerfile body — the instructions to layer on top of the base image. Do not include a FROM instruction; Buildkite prepends the managed base image automatically.

Image builds are asynchronous. The response returns immediately with status: "BUILDING". Poll get an agent image until status is READY or FAILED.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/agent-images" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-custom-image", "dockerfile": "RUN apt-get update && apt-get install -y curl" }'

{
  "id": "abc123def4567",
  "name": "my-custom-image",
  "status": "BUILDING",
  "image_ref": null,
  "version": 1,
  "last_build_error": null,
  "dockerfile": "RUN apt-get update && apt-get install -y curl",
  "base_image": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c",
  "composed_dockerfile": "FROM docker.io/buildkite/hosted-agent-base:ubuntu-v1.0.1@sha256:f1378abd34fccb2b7b661aaf3b06394509a4f7b5bb8c2f8ad431e7eaa1cabc9c\nRUN apt-get update && apt-get install -y curl",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent-images/abc123def4567",
  "web_url": "https://buildkite.com/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/agent_images/abc123def4567",
  "cluster_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf"
}

Required request body properties:

name Name for the agent image. Must be unique within the cluster.
Example: "my-custom-image"
dockerfile Dockerfile body to layer on top of the Buildkite-managed base image. Must be a string and must not contain a FROM instruction. Pass an empty string ("") to build an image with no additional layers.
Example: "RUN apt-get update && apt-get install -y curl"

Required scope: write_clusters

Success response: 201 Created

Error responses:

409 Conflict { "message": "an agent image named \"my-custom-image\" already exists in this cluster" }
422 Unprocessable Entity { "message": "Reason for failure" }

Delete an agent image

Deleting an agent image that is currently assigned to one or more queues returns 409 Conflict. Reassign those queues to a different agent image before deleting.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/agent-images/{id}"

Required scope: write_clusters

Success response: 204 No Content

Error responses:

404 Not Found { "message": "No agent image found with the given ID." }
409 Conflict { "message": "this agent image is in use by one or more queues; reassign those queues before deleting it" }