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"

  - label: ":windows: Windows"
    command: "Write-Host 'Hello World'"
    agents:
      nsc-os: "windows"
      nsc-windows-shell: "powershell"

The nsc-* tags below configure the Namespace instance created for the job.

Compute tags

Tag	Values	Default
`nsc-os`	`linux`, `macos`, `windows`	`linux`
`nsc-arch`	`amd64`, `arm64`	`amd64` on Linux and Windows; `arm64` on macOS
`nsc-shape`	`<vCPU> x <memory in GB>`	`4x8` on Linux and Windows; `6x14` on macOS

See Machine Shapes for guidance on selecting resources.

For macOS images, it is possible to choose base image selectors with the nsc-image-selectors agent tag. Multiple selectors may be separated by a comma. For example, to use a base image with Tahoe slim, include the agent tags

agents:
  nsc-os: "macos"
  nsc-image-selectors: "macos.version=26.x,image.with=xcode-latest"

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 `K:\cache` on Windows	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.

Verifying signed Buildkite pipelines

Namespace-managed agents support verification of signed Buildkite pipelines with self-managed keys.

To get started:

Follow Buildkite's guide for setting up signed pipelines.
During this process, you will create a public/private key pair. Save the resulting public key set (the entire contents of the resulting <key>-public.json file as a secret in Namespace, using either the Vault dashboard or CLI command

nsc vault add --from_file <key>-public.json --description "Buildkite pipeline pub key signature"

Note the ID of the secret, which is of the form sec_<my-secret-id>.

Update the agent tags in your Buildkite pipeline:

agents:
  nsc-verification-jwks-secret-id: sec_<my-secret-id>

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`.
`nsc-windows-shell`	Whether to use `batch` (default) or powershell (`nsc-windows-shell=powershell`) to run commands
`nsc-egress-policy`	Specifies the tag of the workspace egress policy to apply. Include the `buildkite-agents` additional ruleset in policies used with Buildkite agents.

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.