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.

macOS base images

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"

Linux on Apple Silicon

Linux on Apple Silicon is in early access. Reach out to enable it for your workspace.Contact support →

Set the nsc-prefer-sku agent tag to m4pro, m5, or m5max to prefer an Apple Silicon machine for a Linux job.

agents:
  nsc-os: "linux"
  nsc-prefer-sku: "m4pro"
  nsc-shape: "6x14"

See Linux on Apple Silicon machine shapes for the available shapes.

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, the Linux agent container, 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-container-privileged`	Set to `true` to run the Linux Buildkite agent container in privileged mode.
`nsc-container-mount-scratch`	Set to `true` to mount the host’s ephemeral scratch filesystem at `/namespace/scratch` in the Linux agent container.
`nsc-container-host-pid-namespace`	Set to `true` to run the Linux agent container in the host PID namespace.
`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 nsc-features tag accepts a comma—separated list of feature assignments. Some examples are shown below.

Feature	Description
`container.privileged`	Runs the Linux Buildkite agent container in privileged mode.
`container.mount-scratch`	Mounts the host’s ephemeral scratch filesystem at `/namespace/scratch` in the Linux agent container.
`container.host-pid-namespace`	Runs the Linux agent container in the host PID namespace.
`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"
  nsc-container-privileged: "true"

Combine multiple nsc-features assignments into one comma-separated value when a job needs more than one feature. For example, to use a local Docker builder with a persistent 50 GB cache:

agents:
  nsc-features: "docker.builder=local,docker.builder.cache_size=50gb"

Products

Platform

Administration

Compute tags

macOS base images

Linux on Apple Silicon

Caching

Verifying signed Buildkite pipelines

Additional tags

​Compute tags

​macOS base images

​Linux on Apple Silicon

​Caching

​Verifying signed Buildkite pipelines

​Additional tags

Compute tags

macOS base images

Linux on Apple Silicon

Caching

Verifying signed Buildkite pipelines

Additional tags