Installation

Pick whichever fits your platform. All methods give you the same single, self-contained entra-emulator binary (the Svelte portal is baked in — no Node toolchain required at runtime).

Quick pick by platform

• macOS (Intel / Apple Silicon) → Homebrew
• Windows → winget — or the release .zip until the catalog PR merges
• Linux → Homebrew or Docker
• CI / containers / any OS → Docker or go install

All methods

Method	Platforms	Best for
Homebrew	macOS, Linux	Mac/Linux dev machines
winget	Windows	Windows dev machines
Docker	anywhere Docker runs	CI, containers, zero local install
Pre-built binary	macOS, Linux, Windows	pinned versions, air-gapped
go install	any platform with Go	Go developers
From source	any platform with Go	hacking on the emulator

It’s a dev tool

The emulator is intentionally insecure (open admin API, seeded secrets, self-signed TLS). Install it on a workstation or CI runner — never expose it publicly.

Homebrew (macOS / Linux)

brew install calvinchengx/tap/entra-emulator
entra-emulator version

Works on macOS and Linux (Intel and Apple Silicon / arm64). Each tagged release refreshes the cask, so brew upgrade picks up new versions. The cask clears the macOS quarantine attribute for you, so the unsigned binary runs without a Gatekeeper prompt.

Windows (winget)

winget install calvinchengx.entra-emulator
entra-emulator version

Each tagged release opens a manifest PR against microsoft/winget-pkgs; the package is installable once that PR is merged (Microsoft’s validation can take a day or two). Until then — or for scoop / choco, which aren’t published — use the release archive or go install.

Docker

A ~13 MB distroless image (pure-Go, no cgo) on GHCR, with a built-in HEALTHCHECK:

docker run -p 8443:8443 -v entra-emulator-data:/app/data \
  ghcr.io/calvinchengx/entra-emulator:latest

The image defaults to ORIGIN_MODE=compat and binds 0.0.0.0. Mount a volume at /app/data to persist the SQLite store, TLS cert, and signing key across restarts. Tags: latest and each released X.Y.Z.

Pre-built binaries (all platforms)

Every tagged release attaches cross-platform archives (linux / macOS / Windows × amd64 / arm64) to the GitHub Releases page. Download the one for your OS/arch and extract it.

macOS / Linux (…_darwin_arm64.tar.gz, …_linux_amd64.tar.gz, …):

tar -xzf entra-emulator_*_"$(uname -s | tr A-Z a-z)"_*.tar.gz
./entra-emulator version

Windows — download entra-emulator_<version>_windows_amd64.zip (or arm64), unzip it, and run entra-emulator.exe from PowerShell:

.\entra-emulator.exe version

macOS Gatekeeper on manual downloads

The binaries are unsigned. If you download the archive by hand (rather than via Homebrew), macOS may quarantine it. Clear it with: xattr -dr com.apple.quarantine ./entra-emulator.

Each release also publishes checksums.txt — verify with sha256sum -c (Linux) / shasum -a 256 -c (macOS) / Get-FileHash (Windows PowerShell).

go install

With a Go toolchain (1.25+), install straight from the module — no clone, no Node — on any platform:

go install github.com/calvinchengx/entra-emulator/cmd/entra-emulator@latest
entra-emulator version

This works because the built portal is committed to the module, so the pure-Go build is fully self-contained. Use @vX.Y.Z instead of @latest to pin a release.

From source

git clone https://github.com/calvinchengx/entra-emulator
cd entra-emulator
go build ./cmd/entra-emulator
./entra-emulator version

Rebuilding the portal UI needs pnpm (pnpm --filter entra-emulator-portal build), but a plain go build uses the committed portal/dist and needs no Node.

After installing

ORIGIN_MODE=compat entra-emulator        # everything on https://localhost:8443

Then head to the Quickstart to acquire your first token, and TLS & origins if you want the subdomain layout (login. / graph. / portal.) instead of compat mode. To trust the self-signed cert, run entra-emulator trust (it prints the platform command).