> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Using local Docker images

> Use locally built Docker images with microsandbox

<Tooltip tip="This example uses the local image cache. On microsandbox cloud, specify an OCI image when creating the sandbox and it is pulled for you."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

microsandbox cannot read Docker's private local image store directly. First, build the image with Docker:

```bash theme={null}
docker build -t my-image:latest .
```

Stream the image into microsandbox's local image store:

<CodeGroup>
  ```bash macOS & Linux theme={null}
  docker save my-image:latest | msb load
  ```

  ```powershell Windows theme={null}
  docker save -o my-image.tar my-image:latest
  msb load --input my-image.tar
  Remove-Item my-image.tar
  ```
</CodeGroup>

You can now run it like any other image:

```bash theme={null}
msb run my-image:latest
```

You can also save to a file first:

```bash theme={null}
docker save -o my-image.tar my-image:latest
```

Load the saved archive:

```bash theme={null}
msb load --input my-image.tar
```

If the archive has no useful tag, or you want a different local alias, pass one:

<CodeGroup>
  ```bash macOS & Linux theme={null}
  docker save my-image:latest | msb load --tag app:local
  ```

  ```powershell Windows theme={null}
  docker save -o my-image.tar my-image:latest
  msb load --input my-image.tar --tag app:local
  Remove-Item my-image.tar
  ```
</CodeGroup>

Run it by its new local name:

```bash theme={null}
msb run app:local
```

`msb load` is the short top-level form of `msb image load`.

`msb load` can also import OCI Image Layout archives produced by tools such as BuildKit, Skopeo, or ORAS. If the OCI layout does not include an `org.opencontainers.image.ref.name` annotation, pass `--tag` to name the imported image locally.

## Local registry alternative

Use a local registry when you want registry-like push/pull behavior, or when multiple machines should pull the same locally built image.

<Steps>
  <Step title="Start a local registry">
    Run a local OCI registry on port 5050:

    ```bash theme={null}
    docker run -d -p 5050:5000 --name registry registry:2
    ```

    <Tip>
      Port 5000 is used by AirPlay on macOS. This guide uses port 5050 to avoid conflicts.
    </Tip>
  </Step>

  <Step title="Build, tag, and push your image">
    Build your Docker image and tag it for the local registry:

    ```bash theme={null}
    docker build -t localhost:5050/my-image:latest .
    ```

    If you already have an existing image, re-tag it:

    ```bash theme={null}
    docker tag my-image:latest localhost:5050/my-image:latest
    ```

    Push to the local registry:

    ```bash theme={null}
    docker push localhost:5050/my-image:latest
    ```
  </Step>

  <Step title="Pull with microsandbox">
    Since the local registry runs over plain HTTP, use the `--insecure` flag:

    ```bash theme={null}
    msb pull localhost:5050/my-image:latest --insecure
    ```
  </Step>

  <Step title="Use it in microsandbox">
    <CodeGroup>
      ```rust Rust theme={null}
      let sb = Sandbox::builder("worker")
          .image("localhost:5050/my-image:latest")
          .registry(|r| r.insecure())
          .create()
          .await?;
      ```

      ```typescript TypeScript theme={null}
      import { Sandbox } from "microsandbox";

      await using sb = await Sandbox.builder("worker")
          .image("localhost:5050/my-image:latest")
          .registry((r) => r.insecure())
          .create();
      ```
    </CodeGroup>

    <Tip>
      For persistent configuration that applies to all CLI and SDK operations, add the registry to `~/.microsandbox/config.json` instead. See [Registry TLS](/images/overview#registry-tls).
    </Tip>
  </Step>
</Steps>