Installation

One static Go binary (pure Go — no CGO, no runtime dependencies), CI-tested on Linux, macOS, and Windows.

Release channels activate at the first tagged release. Homebrew, winget, the GHCR image, and the archive downloads below publish automatically from v* tags; until the first tag lands, install from source (go install works today).

macOS — Homebrew

brew install calvinchengx/tap/fabric-emulator

Windows — winget

winget deliberately lags the latest tag. Homebrew and GHCR publish on every v* tag; winget does not. Microsoft’s moderation takes days, tags here land several times a day, and a queue of superseded manifest PRs spends moderator attention on versions nobody will install. So the manifest is submitted for chosen releases only — the current one is PR #410794, and the command works once it merges. For the newest build, use Homebrew, the GHCR image, go install, or the archives below.

winget install calvinchengx.fabric-emulator

Any platform — go install

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

Needs Go ≥ 1.25. Pure Go all the way down (modernc.org/sqlite), so this cross-compiles and installs anywhere Go runs.

Docker

docker run --rm -p 9443:9443 \
  -e FABRIC_ENTRA_ISSUER="https://host.docker.internal:8443/6f89cf12-978b-4d23-ac18-9ef0c127cf87/v2.0" \
  -e FABRIC_ENTRA_TLS_INSECURE=true \
  ghcr.io/calvinchengx/fabric-emulator:latest

Distroless, multi-arch (amd64/arm64), with a built-in HEALTHCHECK (the binary probes its own /health — no shell in the image). State lives in /data; mount it to persist.

docker-compose — the emulator family, with real engines by default

docker compose up

This starts the whole family wired together (issuer alignment included): entra-emulator (:8443), azure-keyvault-emulator (:8444), and fabric-emulator (:9443) — plus real compute attached by default: a Spark statement-executor agent (native Livy sessions, notebook cell execution) and a SQL Server sidecar (the T-SQL/TDS warehouse surface — Warehouse, Lakehouse SQL endpoint, Fabric SQL Database). docker-compose.override.yml — auto-loaded alongside docker-compose.yml, no flag needed — adds those sidecars and their env vars; see 14-real-compute.md. --profile rti attaches Microsoft’s KQL engine; --profile eventstream plus -f docker-compose.eventstream.yml attaches Apache Kafka (Lakehouse and Reflex destinations included). An optional msmdsrv DAX oracle is FABRIC_DAX_URL on a machine you own, not a compose profile (52).

To run the same stack explicitly on LakeSail’s Sail (the default Rust Spark-Connect engine, with no JVM; see 20-lakesail-engine.md):

docker compose -f docker-compose.yml -f docker-compose.compute.yml up

Opt out to the lite, contract-only pair (no heavy sidecars, honest 501s on the Spark/SQL surfaces) by naming the base file explicitly, which makes Compose skip the override:

docker compose -f docker-compose.yml up

This is the recommended way to run the full stack — see the quickstart.

Prerequisites differ per platform — the Docker group on Linux, the VM memory cap and Apple-silicon sidecar constraints on macOS, sh.exe and GNU Make on Windows. 26-platform-setup.md covers all three, and make doctor verifies the result on any of them.

Release archives

Tagged releases carry tar.gz/zip archives per OS/arch plus checksums.txt: https://github.com/calvinchengx/fabric-emulator/releases.

From source

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

Verify

fabric-emulator version      # stamped by the release pipeline; "dev" from source
fabric-emulator healthcheck  # exit 0 when a local instance is healthy

The server needs one thing to start: an issuer to trust (FABRIC_ENTRA_ISSUER or -entra-issuer) — see configuration.