Skip to main content
Setup buildx in the current machine, to use Namespace Remote Builders. docker buildx setup configures the local Docker’s buildx plugin to use the Namespace Remote Builders. So the following docker build commands will use a high-capacity remote builder hosted by Namespace. The builder machines are created on demand whenever a build is started, triggering a connection to the remote builders. The architecture of the builder machine (AMD64 or ARM64) is inferred by the build command’s platform.

​
Usage

​
Example

The following example configures local buildx to use Namespace Remote Builders.
1

Configure buildx

Configure buildx to use Namespace Remote Builders:
2

Build an image

Run a Docker build using the configured Remote Builder:

​
Options

​
—name <name>

Specify the name of the buildx builder. By default, it is “nsc-remote”.

​
—state <path>

Specify a custom directory where the command stores the remote builders context configuration.

​
—tag <tag>

If set, targets a specific remote builder instead of letting Namespace select one automatically.

​
—background

If set, runs the proxy in the background. So, nsc docker buildx setup does not block the caller.

​
—create_at_startup

By default, Remote Builders are created on demand, whenever a new build request is issued. If this flag is set, the Remote Builders are created immediately.

​
—force_cleanup

If set, forces cleanup of any previous buildx proxy already running in the background before setting up a new one. Useful if a prior --background run wasn’t shut down cleanly.

​
—use

If set, it configures local Docker context to use the Namespace Remote Builders. By default, it only configures the builders in docker buildx, and it does not change the Docker context.
Last modified on August 20, 2026