Hosted agents

A collection of common tasks with Hosted agents using the GraphQL API.

You can test out the Buildkite GraphQL API using the Buildkite GraphQL console. This includes built-in documentation under its Documentation tab.

Create a Buildkite hosted queue

Create a new Buildkite hosted queue in a cluster, which are queues created for Buildkite hosted agents.

mutation {
  clusterQueueCreate(
    input: {
      organizationId: "organization-id"
      clusterId: "cluster-id"
      key: "hosted_linux_small"
      description: "Small AMD64 Linux agents hosted by Buildkite."
      hostedAgents: {
        instanceShape: LINUX_AMD64_2X4
      }
    }
  ) {
    clusterQueue {
      id
      uuid
      key
      description
      dispatchPaused
      hosted
      hostedAgents {
        instanceShape {
          name
          size
          vcpu
          memory
        }
      }
      createdBy {
        id
        uuid
        name
        email
        avatar {
          url
        }
      }
    }
  }
}

Creates a small Buildkite hosted queue using AMD64-based Linux Buildkite hosted agents. The instanceShape value is referenced from the InstanceShape enum, and represents the combination of machine type, architecture, CPU and Memory available to each job running on a hosted queue. The LINUX_AMD64_2X4 value is a Linux AMD64 2 vCPU and 4 GB memory instance.

Learn more about the instance shapes available for Linux and macOS Buildkite hosted agents.

Change the instance shape of a Buildkite hosted queue's agents

mutation {
  clusterQueueUpdate(
    input: {
      organizationId: "organization-id"
      id: "cluster-queue-id"
      hostedAgents: {
        instanceShape: LINUX_AMD64_4X16
      }
    }
  ) {
    clusterQueue {
      id
      hostedAgents {
        instanceShape {
          name
          size
          vcpu
          memory
        }
      }
    }
  }
}

To increase the size of the AMD64-based Linux agent instances for a Buildkite hosted queue, update the instanceShape value to a one of a greater size, such as LINUX_AMD64_4X8, which is a 4 vCPU and 8 GB memory. This allows you to scale the resources available to each job running on this Buildkite hosted queue.

Learn more about the instance shapes available for Linux and macOS Buildkite hosted agents.

It is only possible to change the size of the current instance shape assigned to this queue. It is not possible to change the current instance shape's machine type (from macOS to Linux, or vice versa), or for a Linux machine, its architecture (from AMD64 to ARM64, or vice versa).

Instance shape values for Linux

Specify the appropriate Instance shape for the instanceShape value in your GraphQL API mutation.

Instance shape Size Architecture vCPU Memory
Instance shape Instance shape LINUX_AMD64_2X4 Size Size Small Architecture Architecture AMD64 vCPU vCPU 2 Memory Memory 4 GB
Instance shape Instance shape LINUX_AMD64_4X16 Size Size Medium Architecture Architecture AMD64 vCPU vCPU 4 Memory Memory 16 GB
Instance shape Instance shape LINUX_AMD64_8X32 Size Size Large Architecture Architecture AMD64 vCPU vCPU 8 Memory Memory 32 GB
Instance shape Instance shape LINUX_AMD64_16X64 Size Size Extra Large Architecture Architecture AMD64 vCPU vCPU 16 Memory Memory 64 GB
Instance shape Instance shape LINUX_ARM64_2X4 Size Size Small Architecture Architecture ARM64 vCPU vCPU 2 Memory Memory 4 GB
Instance shape Instance shape LINUX_ARM64_4X16 Size Size Medium Architecture Architecture ARM64 vCPU vCPU 4 Memory Memory 16 GB
Instance shape Instance shape LINUX_ARM64_8X32 Size Size Large Architecture Architecture ARM64 vCPU vCPU 8 Memory Memory 32 GB
Instance shape Instance shape LINUX_ARM64_16X64 Size Size Extra Large Architecture Architecture ARM64 vCPU vCPU 16 Memory Memory 64 GB

Instance shape values for macOS

Specify the appropriate Instance shape for the instanceShape value in your GraphQL API mutation.

Instance shape Size vCPU Memory
Instance shape Instance shape MACOS_ARM64_M4_6X28 Size Size Medium vCPU vCPU 6 Memory Memory 28 GB
Instance shape Instance shape MACOS_ARM64_M4_12X56 Size Size Large vCPU vCPU 12 Memory Memory 56 GB

Note: Shapes MACOS_M2_4X7, MACOS_M2_6X14, MACOS_M2_12X28, MACOS_M4_12X56 were deprecated and removed on July 1, 2025.