Skip to main content
Version: v1.6 (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​

topaz-host --log-level Information

The topaz-host and topaz binaries are already on your PATH. Open a second terminal and use topaz to manage resources.

ROPC authentication (az login --username --password)​

When the host starts, it also launches a built-in HTTP CONNECT proxy on port 44380. This proxy is required for az login --username --password (Resource Owner Password Credentials).

Set the HTTPS_PROXY environment variable once before running any az commands that require authentication:

export HTTPS_PROXY=http://127.0.0.1:44380
az login --username alice@mytenant.onmicrosoft.com --password P@ssw0rd!

The proxy passes all non-Topaz CONNECT requests through to the real internet unchanged. Topaz prints a reminder with the correct command when it starts.

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

topaz health demo

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