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

# nsc docker buildx setup

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](/docs/solutions/docker-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

```bash theme={null}
nsc docker buildx setup [--name <name>] [--state <path>] [--tag <tag>] [--background] [--create_at_startup] [--force_cleanup] [--use]
```

### Example

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

<Steps titleSize="h4">
  <Step title="Configure buildx">
    Configure `buildx` to use Namespace Remote Builders:

    ```bash theme={null}
    nsc docker buildx setup --background --use
    ```
  </Step>

  <Step title="Build an image">
    Run a Docker build using the configured Remote Builder:

    ```bash theme={null}
    docker build . -t app:latest
    ```
  </Step>
</Steps>

## Options

<h3 id="--name-name">
  \--name \<name>
</h3>

Specify the name of the `buildx` builder. By default, it is "nsc-remote".

<h3 id="--state-path">
  \--state \<path>
</h3>

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

<h3 id="--tag-tag">
  \--tag \<tag>
</h3>

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

<h3 id="--background">
  \--background
</h3>

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

<h3 id="--create_at_startup">
  \--create\_at\_startup
</h3>

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.

<h3 id="--force_cleanup">
  \--force\_cleanup
</h3>

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.

<h3 id="--use">
  \--use
</h3>

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.