Install on macOS

Apple Silicon: MPS

Run natively on Apple Silicon to use the GPU through Metal Performance Shaders. A Linux Docker container on a Mac does not expose the MPS backend.

Install Apple's command-line tools if they are not already available:

xcode-select --install

Complete the system installation dialog. Then install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal and prepare the service:

uv --version
git clone https://github.com/dzenplatform/embedder.git
cd embedder
DEVICE=mps make setup
DEVICE=mps make run

The Makefile uses Python 3.12 and a venv/ environment. Setup checks MPS availability and downloads the model. If it reports MPS is unavailable, check that Python runs natively on Apple Silicon, outside Docker, and that your macOS version is supported by the installed PyTorch release.

Apple Silicon: CPU

To run without GPU acceleration, use these commands from the repository directory:

DEVICE=cpu make setup
DEVICE=cpu make run

This is an alternative server process: stop a previous foreground instance with Ctrl+C first. To persist your choice, set device: cpu or device: mps in the root local.yaml, then run make setup and make run without DEVICE.

CPU in Docker, including Intel Macs

Install Docker Desktop for Mac for your computer's architecture and start it. In a terminal:

git clone https://github.com/dzenplatform/embedder.git
cd embedder
docker compose up -d
docker compose logs -f model-init embedder

If you already cloned the repository, use that checkout. Docker selects the amd64 or arm64 CPU image. This guide uses the container path for Intel Macs; native PyTorch wheel availability must be checked separately against the project's Python and PyTorch requirements.

This container does not use MPS or CUDA on a Mac. For acceleration on Apple Silicon, use the native MPS option above.

Verify the installation

After the model loads, the service listens at http://127.0.0.1:8091. Keep a native process running and open another terminal for the API checks.

Containers run in the background. Use docker compose stop to stop them while retaining the model volume.