Manual setup — .NET MAUI

Prerequisites

An existing .NET MAUI app targeting net10.0 (any combination of -android, -ios, -maccatalyst, -windows, or -macos).
The Ailoha CLI installed on your dev machine: see install instructions.

1. Install the package

Add a reference to Ailoha.Agent.Maui in your MAUI app project (the head project, not class libraries):

dotnet add package Ailoha.Agent.Maui

Or add it directly to your .csproj:

<ItemGroup>
  <PackageReference Include="Ailoha.Agent.Maui" Version="0.1.*" />
</ItemGroup>

2. Register the agent

In MauiProgram.cs, call AddMauiDevFlowAgent() on the MauiAppBuilder. Wrap it in #if DEBUG so the agent never ships in release builds:

using Ailoha.Agent;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>();

#if DEBUG
        builder.AddMauiDevFlowAgent();
#endif

        return builder.Build();
    }
}

Optional: Blazor Hybrid support

If your app uses BlazorWebView, also call AddMauiBlazorDevFlowTools(). This wires Chrome DevTools Protocol into the WebView so the agent can drive it like a real browser.

#if DEBUG
builder
    .AddMauiDevFlowAgent()
    .AddMauiBlazorDevFlowTools();
#endif

3. Configure (optional)

AddMauiDevFlowAgent accepts an options callback:

builder.AddMauiDevFlowAgent(options =>
{
    options.Port = 9233;
    options.EnableFileLogging = true;
    options.EnableNetworkMonitoring = true;
});

Option	Default	Notes
`Port`	`9233`	Falls back through `9238` if taken. Override in code, with MSBuild `-p:AilohaPort=XXXX`, or with a project `.ailoha` file.
`EnableFileLogging`	`true`	Persist agent logs to disk for triage.
`EnableNetworkMonitoring`	`true`	Captures HTTP traffic via `DevFlowHttpHandler`.
`EnableProfiler`	`false`	Enables runtime profiling endpoints and sampling.

4. Use stable element IDs

The agent prefers AutomationId when resolving CSS-style selectors. Add it to anything you want to query reliably:

<Button x:Name="LoginButton"
        AutomationId="login-button"
        Text="Sign in"
        Clicked="OnLoginClicked" />

5. Run and verify

Build and run the app on your target device or simulator. Then, from your dev machine:

ailoha agent status
ailoha ui tree --depth 2
ailoha ui screenshot --output ./shot.png

If the CLI reports the app, you're done. The agent is ready for use from any MCP-aware AI client.

On Android emulators or physical devices, you may need to forward the agent port: adb forward tcp:9233 tcp:9233. The broker handles this automatically when discovery runs through the CLI.

Troubleshooting

Port in use. The agent tries the configured port and five subsequent ports. If all are taken, set options.Port explicitly or pass -p:AilohaPort=XXXX.
App not discovered. Run ailoha diagnose and ailoha agent list to verify broker registration and selected agent state.
Release builds include the agent. Confirm your AddMauiDevFlowAgent call is inside #if DEBUG.

What's next

Browse the protocol capabilities the CLI and MCP clients can call.
Add a custom extension from your own MAUI library.