Skip to main content
Version: v1.2 (stable)

Getting started

Let's discover what Topaz is and how to set it up for local Azure development.

What is Topaz?​

Topaz is an Azure emulator that lets you develop and test Azure-based applications without connecting to real cloud services. It implements the ARM control plane and the data planes of popular services such as Azure Storage, Key Vault, Service Bus, and more — all running locally on your machine.

Early stage

Topaz is still in active development. Breaking changes may be introduced in upcoming releases. Check the release notes before upgrading.

Prerequisites​

Standalone executableDocker container
RuntimeNone — self-contained binaryDocker (or compatible runtime)
CertificatesMust be installed & trustedHandled automatically
DNSOne-time setup script requiredOne-time setup script required

Releases are published on the GitHub releases page. Download the package that matches your platform and architecture.

Windows users

The recommended way to run Topaz on Windows is inside WSL 2 (Windows Subsystem for Linux). This gives you a normal Linux environment and avoids certificate and DNS complications. All shell examples below assume a Linux/macOS shell; run them inside WSL if you're on Windows.

Step 1 — One-time DNS configuration​

macOS — install with Homebrew

On macOS you can skip Steps 1 and 3 by installing via Homebrew. DNS setup and the topaz-host and topaz binaries are handled automatically:

brew tap thecloudtheory/topaz
brew install topaz

You will still need to complete Step 2 (trusting the certificate). The certificate is installed at $(brew --prefix)/bin/topaz.crt.

Linux — shell installer or Homebrew on Linux

On Linux you can skip Step 3 by using the shell installer. It detects your architecture, downloads the correct topaz and topaz-host binaries from the latest GitHub release, and places them on your PATH:

curl -fsSL https://raw.githubusercontent.com/TheCloudTheory/Topaz/main/install/get-topaz.sh | bash

To pin a specific version, set TOPAZ_VERSION before piping:

curl -fsSL https://raw.githubusercontent.com/TheCloudTheory/Topaz/main/install/get-topaz.sh | TOPAZ_VERSION=v1.1-beta.3 bash

Alternatively, if you already have Homebrew on Linux installed, the same macOS tap works without any changes:

brew tap thecloudtheory/topaz
brew install topaz

Either way, you still need to complete Steps 1 and 2 (DNS and certificate trust).

Topaz emulates Azure service hostnames (e.g. *.blob.core.windows.net) locally. A one-time DNS configuration is required so that these hostnames resolve to 127.0.0.1. This needs admin privileges, but once done Topaz needs none at runtime.

curl -fsSL https://raw.githubusercontent.com/TheCloudTheory/Topaz/main/install/install-macos.sh | sudo bash

Or clone the repo and run it directly:

sudo bash install/install-macos.sh

You only need to run this script once per machine (or WSL instance).

Step 2 — Trust the certificate​

Topaz exposes HTTPS endpoints using a self-signed certificate that is bundled in the release package. You need to add it to your system trust store so that tools like the Azure CLI and the Azure SDKs can connect without TLS errors.

Open Keychain Access, import topaz.crt, and mark it as Always Trust, or use the terminal:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain topaz.crt
Skip certificates with Docker

When running Topaz as a Docker container you can expose only the HTTP data-plane ports and skip this step entirely. HTTPS is still available inside the container on port 8899 (ARM), but services like Blob and Table Storage use plain HTTP on their own ports.

Step 3 — Run the emulator​

cd <download-directory>
chmod +x topaz-host-linux-x64   # use topaz-host-osx-x64 on macOS; topaz-host-linux-arm64 on ARM
./topaz-host-linux-x64 --log-level Information

Topaz is split into two executables:

BinaryPurpose
topaz-host-*Runs the emulator — start this first
topaz-*CLI for managing resources in the running emulator

Available Host binaries by platform:

PlatformBinary
macOS (Apple Silicon)topaz-host-osx-arm64
macOS (Intel)topaz-host-osx-x64
Linux x64topaz-host-linux-x64
Linux ARM64topaz-host-linux-arm64
Windowstopaz-host-win-x64.exe

Available CLI binaries by platform:

PlatformBinary
macOS (Apple Silicon)topaz-osx-arm64
macOS (Intel)topaz-osx-x64
Linux x64topaz-linux-x64
Linux ARM64topaz-linux-arm64
Windowstopaz-win-x64.exe (or use the Linux binary inside WSL)
note

If you installed via the shell installer or Homebrew, the binaries are already named topaz and topaz-host and placed on your PATH. You can skip this section.

Typing the full binary name every time is tedious. Create a shell alias or move the binary to a directory on your PATH:

# Option A — symlink into /usr/local/bin
sudo ln -s "$(pwd)/topaz-host-linux-x64" /usr/local/bin/topaz-host
sudo ln -s "$(pwd)/topaz-linux-x64" /usr/local/bin/topaz

# Option B — add alias to your shell profile
echo 'alias topaz-host="/path/to/topaz-host-linux-x64"' >> ~/.zshrc   # macOS (Zsh)
echo 'alias topaz-host="/path/to/topaz-host-linux-x64"' >> ~/.bashrc  # Linux / WSL
source ~/.zshrc   # or ~/.bashrc

After this you can run topaz-host --log-level Information to start the emulator and topaz in a second terminal to manage resources.

Step 4 — Verify the emulator is running​

Once started, Topaz logs the list of bound endpoints. The quickest way to confirm everything is working is to run:

topaz health

If the host is up, you'll see something like:

Host is running
  Status:    Healthy
  Directory: /home/user/my-project
  Port:      8899

You can also hit the health endpoint directly:

curl -k https://localhost:8899/health
# Expected: HTTP 200 with {"status":"Healthy", ...}

The -k flag skips TLS verification for the quick check. In normal usage the certificate will be trusted after Step 2, so you won't need it.

Next steps​

Star on GitHub