emulator-overview.md

title	App Configuration Emulator Overview
titleSuffix	Azure App Configuration
description	Overview of Azure App Configuration emulator.
services	azure-app-configuration
author	zhiyuanliang-ms
ms.author	zhiyuanliang
ms.service	azure-app-configuration
ms.topic	overview
ms.date	11/12/2025

Azure App Configuration emulator overview

The Azure App Configuration emulator is a local development tool that provides a lightweight implementation of the Azure App Configuration service. This emulator allows developers to test and develop applications locally without requiring an active Azure subscription or connection to the cloud service.

The Azure App Configuration emulator is open source. For more information, visit the GitHub repository.

Feature overview

The following table lists the features supported by the latest Azure App Configuration emulator.

Feature	Status
Web UI	Available
Anonymous Authentication	Available
HMAC Authentication	Available
.NET Aspire Integration	Available

API	Status
/keys	Available
/kv	Available
/labels	Available
/locks	Available
/revisions	Available
/snapshots	WIP

Install the emulator

Docker

Use Docker to pull the latest App Configuration emulator image by using the following console command:

docker pull mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.0.2

GitHub

This installation method requires that you have installed:

• Git
• .NET 8.0 SDK
• Node.js

1. Clone the GitHub repository for the emulator project.

   git clone https://github.com/Azure/AppConfiguration-Emulator.git

2. Build the entire solution including the UI components.

   cd AppConfiguration-Emulator
   dotnet restore
   dotnet build

---

Run the emulator

Docker

The following command runs the App Configuration emulator Docker image. The -p 8483:8483 parameter redirects requests from host machine's port 8483 to the Docker instance. The -e Tenant:AnonymousAuthEnabled=true and -e Authentication:Anonymous:AnonymousUserRole=Owner parameters configure the anonymous authentication for the emulator.

docker run -d -p 8483:8483 \
    -e Tenant:AnonymousAuthEnabled=true \
    -e Authentication:Anonymous:AnonymousUserRole=Owner \
    mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.0.2

If you want to have persisted data for the emulator, you can use a bind mount.

docker run -d -p 8483:8483 \
    -v "C:\aace:/app/.aace" \
    -e Tenant:AnonymousAuthEnabled=true \
    -e Authentication:Anonymous:AnonymousUserRole=Owner \
    mcr.microsoft.com/azure-app-configuration/app-configuration-emulator:1.0.2

GitHub

dotnet run --project src/Azure.AppConfiguration.Emulator.Host/Azure.AppConfiguration.Emulator.Host.csproj

---

Emulator in action

Once started, the emulator is available at: http://localhost:8483

1. Open your browser and navigate to http://localhost:8483.

   [!div class="mx-imgBorder"]

2. Click the Create button and add a new key Message.

   [!div class="mx-imgBorder"]

3. Click the Save button and you see the key value in the configuration explorer.

   [!div class="mx-imgBorder"]

4. Get http://localhost:8483/kv and you get the following response.

   {"items":[{"etag":"EzV9zWW8k5JpcIXL00T5Kg","key":"Message","label":null,"content_type":null,"value":"Hello World!","tags":{},"locked":false,"last_modified":"2025-08-12T16:56:25.384738+00:00"}]}

Next steps

For examples about how to use the emulator in your applications, go to the GitHub repository.