> ## 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.

# Named Builders

> Select a named remote Docker builder and configure its CPU and memory.

Named builders let you select a remote builder by name instead of letting Namespace select one automatically. Use different names to separate builders for different projects or workflows.

## Prerequisites

Install the [Namespace CLI](https://namespace.so/docs/reference/cli/installation.md) and [log into your workspace](https://namespace.so/docs/reference/cli/login.md).

> [!NOTE]
>
> Named builders must be enabled for your workspace. Specifying a custom shape also requires builder customization to be enabled. Contact [support@namespace.so](mailto:support@namespace.so) to request access to either capability.

## Configure a named builder

Use `--tag` to select the remote builder and `--builder_shape` to request its CPU and memory:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
nsc docker buildx setup --tag web-builder --builder_shape 32x64
```

This configures the remote builder named `web-builder` with 32 vCPUs and 64 GB of memory. Shapes use the format `<vcpu>x<memGB>`. If you omit `--builder_shape`, Namespace uses your workspace's default builder shape.

Builder names must start with a lowercase letter and contain only lowercase letters, digits, hyphens, or underscores. Names can be up to 32 characters long.

Run a build using the configured Buildx builder:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
docker buildx build --builder nsc-remote --load -t web:latest .
```

The setup command registers the builder locally as `nsc-remote` by default. To select it as your current Buildx builder instead of passing `--builder` on each build, add `--use`:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
nsc docker buildx setup --tag web-builder --builder_shape 32x64 --use
```

## Remote and local names

`--tag` sets the remote builder name. `--name` sets the local Buildx registration name. Setting `--name` alone does not select a named remote builder.

To keep multiple named builders configured on one machine, give each a different local name:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
nsc docker buildx setup --name web --tag web-builder --builder_shape 32x64
nsc docker buildx setup --name api --tag api-builder --builder_shape 16x32
```

Choose the local registration when building:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
docker buildx build --builder web --load -t web:latest .
docker buildx build --builder api --load -t api:latest .
```

## Troubleshooting

If setup reports `Named builders are not enabled for tenant ...`, contact [support@namespace.so](mailto:support@namespace.so) to enable named builders for your workspace.

If it reports `Customization of builders is not enabled for tenant ...`, request builder customization as well, or omit `--builder_shape` to use the default shape.

## Related topics

* [Buildx setup reference](https://namespace.so/docs/reference/cli/docker-buildx-setup.md)
* [Build observability](https://namespace.so/docs/solutions/docker-builders/tracing-and-logs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.