> ## 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 attach-context

Attach your local Docker to an ephemeral environment.

`docker attach-context` configures a Docker context that uses an ephemeral environment.

## Usage

```bash theme={null}
nsc docker attach-context {--new | --to <instance-id>} [--name <name>] [-state <path>] [--machine_type <cpu>x<mem>] [--background] [--use]
```

### Example

<Steps titleSize="h4">
  <Step title="Create an ephemeral instance">
    Create an ephemeral instance and note its ID:

    ```bash theme={null}
    nsc create
    ```

    ```text nocopy Output theme={null}
    Created new ephemeral environment! ID: me4ev9pm8qk8o
    ```
  </Step>

  <Step title="Attach Docker">
    Attach your local Docker client to the new environment:

    ```bash theme={null}
    nsc docker attach-context --to me4ev9pm8qk8o --name my-remote-docker --background --use
    ```

    ```text nocopy Output theme={null}
    Attached Docker Context: my-remote-docker
    ```
  </Step>

  <Step title="Run Docker commands">
    Use the newly created context to run Docker commands:

    ```bash theme={null}
    docker compose up
    ```
  </Step>
</Steps>

### Example with Cache Volumes

<Steps titleSize="h4">
  <Step title="Create an instance with a cache volume">
    Create a bare instance with a cache volume:

    ```bash theme={null}
    nsc create --bare --volume cache:tagname:/mountpoint:50gb
    ```

    ```text nocopy Output theme={null}
    Created new ephemeral environment! ID: me4ev9pm8qk8o
    ```
  </Step>

  <Step title="Attach Docker">
    Attach your local Docker context to the remote instance:

    ```bash theme={null}
    nsc docker attach-context --to me4ev9pm8qk8o --background --use
    ```
  </Step>

  <Step title="Mount the cache volume">
    Run a container and bind mount the cache volume directory into it:

    ```bash theme={null}
    docker run --rm -it -v /mountpoint:/cache ubuntu
    ```

    Your container can access the cache context at `/cache` path. Check how [cache volumes](/docs/architecture/storage/cache-volumes) work.
  </Step>
</Steps>

## Options

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

Create a new ephemeral environment. Either `--new` or `--to <instance-id>` must be set.

<h3 id="--to-instance-id">
  \--to \<instance-id>
</h3>

Rather than creating a new ephemeral environment, attach to Docker in an existing environment (identified by its id).
Either `--new` or `--to <instance-id>` must be set.

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

The name of the Docker context that is created; by default it will be `nsc-{instance-id}`.

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

Specify a custom directory where the command stores the Docker context configuration.

<h3 id="--machine_type-cpuxmem">
  \--machine\_type \<cpu>x\<mem>
</h3>

Specifying the machine shape when creating a new environment. The following are the supported machine shapes:

* `2x2`: 2 CPU 2 GB memory.
* `2x4`: 2 CPU 4 GB memory.
* `4x4`: 4 CPU 4 GB memory.
* `4x8`: 4 CPU 8 GB memory.
* `4x16`: 4 CPU 16 GB memory.
* `16x32`: 16 CPU 32 GB memory.

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

If set, attach to the Docker context in the background. So, `nsc docker attach-context` does not block the caller.

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

If set, it configures local Docker to use the newly configured Docker context.