> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Buildkite Agents

Configure Namespace agents with an [`agents` block](https://buildkite.com/docs/pipelines/configure/defining-steps#step-defaults).
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.

```yaml theme={null}
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](/docs/architecture/compute/machine-shapes) for guidance on selecting resources.

### macOS base images

For macOS images, it is possible to choose [base image selectors](/docs/architecture/compute/macos#available-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

```yaml theme={null}
agents:
  nsc-os: "macos"
  nsc-image-selectors: "macos.version=26.x,image.with=xcode-latest"
```

### Linux on Apple Silicon

<Info>
  Linux on Apple Silicon is in **early access**. Reach out to enable it for your workspace.

  [Contact support →](mailto:support@namespace.so)
</Info>

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

```yaml theme={null}
agents:
  nsc-os: "linux"
  nsc-prefer-sku: "m4pro"
  nsc-shape: "6x14"
```

See [Linux on Apple Silicon machine shapes](/docs/architecture/compute/machine-shapes#linux-on-apple-silicon) for the available shapes.

## Caching

Attach a [Cache Volume](/docs/architecture/storage/cache-volumes) 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/`.           |

```yaml theme={null}
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:

1. Follow Buildkite's [guide](https://buildkite.com/docs/agent/self-hosted/security/signed-pipelines#self-managed-key-creation) for
   setting up signed pipelines.
2. 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](/docs/architecture/storage/secrets#create-secret) in Namespace, using either
   the [Vault dashboard](https://cloud.namespace.so/workspace/vars) or CLI command

```bash theme={null}
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>`.

3. Update the agent tags in your Buildkite pipeline:

```yaml theme={null}
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](/docs/security/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:

```yaml theme={null}
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:

```yaml theme={null}
agents:
  nsc-features: "docker.builder=local,docker.builder.cache_size=50gb"
```