# Set up flagd in the AppHost

<Badge text="⭐ Community Toolkit" variant="tip" size="large" />

<ThemeImage
  light={flagdLightIcon}
  dark={flagdIcon}
  alt="flagd logo"
  width={100}
  height={100}
  zoomable={false}
  classOverride="float-inline-left icon"
/>

This article is the reference for the Aspire flagd Hosting integration. It enumerates the AppHost APIs that you use to model a flagd resource in your [`AppHost`](/get-started/app-host/) project.

If you're new to the flagd integration, start with the [Get started with flagd integrations](/integrations/devtools/flagd/flagd-get-started/) guide. For how consuming apps read the connection information this page exposes, see [Connect to flagd](../flagd-connect/).

## Installation

To start building an Aspire app that uses flagd, install the [📦 CommunityToolkit.Aspire.Hosting.Flagd](https://www.nuget.org/packages/CommunityToolkit.Aspire.Hosting.Flagd) NuGet package:

```bash title="Terminal"
aspire add flagd
```

<LearnMore>
  Learn more about [`aspire add`](/reference/cli/commands/aspire-add/) in the command reference.
</LearnMore>

Or, choose a manual installation approach:

```csharp title="C# — AppHost.cs"
#:package CommunityToolkit.Aspire.Hosting.Flagd@*
```

```xml title="XML — AppHost.csproj"
<PackageReference Include="CommunityToolkit.Aspire.Hosting.Flagd" Version="*" />
```

:::note
TypeScript AppHost support for the flagd integration is not yet available.
:::

## Add flagd resource

Once you've installed the hosting integration in your AppHost project, you can add a flagd resource. The flagd container requires a sync source. Use `WithBindFileSync` to mount a directory of flag-definition files into the container:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync("./flags/");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();
```

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the `ghcr.io/open-feature/flagd` image, it creates a new flagd server instance on your local machine.

1. The AppHost reference call configures a connection in the consuming project named after the referenced flagd resource, such as `flagd` in the preceding example.
**Note:** When you reference a flagd resource from the AppHost, Aspire makes the server's connection information available to the consuming project as environment variables. For a complete list of these properties and per-language connection examples, see [Connect to flagd](../flagd-connect/).

## Add flagd resource with file sync options

To specify the flag-definition filename explicitly, pass both the `fileSource` directory and the `filename` to `WithBindFileSync`:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync(
        fileSource: "./flags/",
        filename: "flagd.json");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();
```

The `fileSource` parameter is the path on your host machine where flag configuration files are located. The `filename` parameter names the flag configuration file inside that directory. When `filename` is omitted, it defaults to `flagd.json`.

## Flag configuration format

flagd uses JSON files for flag definitions. Create a `flags` folder in your project root and add a flag configuration file. A minimal example:

```json title="JSON — flags/flagd.json"
{
    "$schema": "https://flagd.dev/schema/v0/flags.json",
    "flags": {
        "welcome-banner": {
            "state": "ENABLED",
            "variants": {
                "on": true,
                "off": false
            },
            "defaultVariant": "off"
        },
        "background-color": {
            "state": "ENABLED",
            "variants": {
                "red": "#FF0000",
                "blue": "#0000FF",
                "yellow": "#FFFF00"
            },
            "defaultVariant": "red"
        }
    }
}
```

For more information on flag configuration, see the [flagd flag definitions documentation](https://flagd.dev/reference/flag-definitions/).

## Configure logging

To enable debug logging for the flagd container, call `WithLogLevel`:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd("flagd")
    .WithBindFileSync("./flags/")
    .WithLogLevel(Microsoft.Extensions.Logging.LogLevel.Debug);

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();
```

Debug logging provides verbose output for troubleshooting flag evaluation issues. Currently, only the `Debug` log level is supported.

## Customize ports

To use fixed host ports instead of randomly assigned ones, pass the `port` and `ofrepPort` parameters to `AddFlagd`:

```csharp title="C# — AppHost.cs"
var builder = DistributedApplication.CreateBuilder(args);

var flagd = builder.AddFlagd(
    name: "flagd",
    port: 8013,
    ofrepPort: 8016)
    .WithBindFileSync("./flags/");

builder.AddProject<Projects.ExampleProject>("api")
    .WithReference(flagd);

// After adding all resources, run the app...
builder.Build().Run();
```

The `port` parameter sets the host port for the flagd HTTP/gRPC endpoint. The `ofrepPort` parameter sets the host port for the [OFREP](https://github.com/open-feature/protocol) (OpenFeature Remote Evaluation Protocol) endpoint. When these parameters are omitted, Aspire assigns random ports.

## Health checks

The flagd hosting integration automatically registers a health check for the flagd resource. The health check polls the flagd `/healthz` endpoint to verify the server is running and reachable.