Configure Buildkite Agents
Configure Namespace agents with an agents block.
A top-level block sets defaults for every command step in the pipeline. Add an agents block to an individual step to override those defaults for that step.
agents:
nsc-os: "linux"
nsc-arch: "amd64"
nsc-shape: "8x16"
steps:
- label: ":linux: Linux AMD64"
command: "make test"
- label: ":mac: macOS"
command: "make test-macos"
agents:
nsc-os: "macos"
nsc-arch: "arm64"
nsc-shape: "6x14"The nsc-* tags below configure the Namespace instance created for the job.
Compute tags
| Tag | Values | Default |
|---|---|---|
nsc-os | linux, macos | linux |
nsc-arch | amd64, arm64 | amd64 on Linux; arm64 on macOS |
nsc-shape | <vCPU> x <memory in GB> | 4x8 on Linux; 6x14 on macOS |
See Machine Shapes for guidance on selecting resources.
Caching
Attach a Cache Volume to preserve dependencies and other build outputs across jobs. Jobs using the same cache tag access the same cache contents.
| Tag | Default | Description |
|---|---|---|
nsc-cache-tag | None | Attaches a persistent cache. This tag is required when setting a cache path or size. |
nsc-cache-size | 20g | Capacity of the cache volume. Values below 20 GB are rounded up to 20 GB. |
nsc-cache-path | /cache on Linux; /Volumes/cache on macOS | Path where the cache is mounted. macOS paths must start with /Volumes/. |
agents:
queue: "default"
nsc-cache-tag: "my-project-dependencies"
nsc-cache-size: "50g"
nsc-cache-path: "/cache/dependencies"Use a stable tag when jobs should share a cache. Use distinct tags to isolate caches between repositories, branches, or toolchains.
Additional tags
Use these tags to configure repository mirrors, container storage, privileged containers, and local Docker builders.
| Tag | Description |
|---|---|
nsc-git-mirror | Attaches a persistent, repository-specific Git mirror cache. It is mounted at /gitmirror on Linux and /Volumes/gitmirror on macOS. |
nsc-containerd-cache-relative-path | Stores the Linux container image cache in this directory within the cache selected by nsc-cache-tag. |
The namespace-features tag accepts a comma-separated list of feature assignments. Some examples are shown below.
| Tag | Description |
|---|---|
container.privileged | Runs the Linux Buildkite agent container in privileged mode. |
docker.builder | Uses the specified Docker builder instead of the default remote builder. |
docker.builder.cache_size | Sets the capacity of the persistent local Docker builder cache. |
Enable the Git mirror, container image cache, and privileged containers together:
agents:
nsc-cache-tag: "my-project-cache"
nsc-cache-size: "50gb"
nsc-git-mirror: "10gb"
nsc-containerd-cache-relative-path: "containers"
namespace-features: "container.privileged=true"Use a local Docker builder with a persistent 50 GB cache:
agents:
namespace-features: "docker.builder=local,docker.builder.cache_size=50gb"Combine multiple namespace-features assignments into one comma-separated value when a job needs more than one feature.