Skip to main content
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 and log into your workspace.
Named builders must be enabled for your workspace. Specifying a custom shape also requires builder customization to be enabled. Contact 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:
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:
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:

​
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:
Choose the local registration when building:

​
Troubleshooting

If setup reports Named builders are not enabled for tenant ..., contact 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.
Last modified on November 6, 2026