Getting Started

Install Ansight Studio, configure the local stdio bridge, add the .NET SDK, and complete your first pairing flow.

This guide takes you from a clean workstation to a first paired session.

If you want an AI agent to install and integrate Ansight into a .NET MAUI, Android, iOS, or Mac Catalyst app, please use this skill /skills/dotnet/ansight-install-dotnet.md.

Copyable prompt:

Please use this skill https://www.ansight.ai/skills/dotnet/ansight-install-dotnet.md to install and integrate Ansight into my .NET MAUI, Android, iOS, or Mac Catalyst app. Use the all-in-one Ansight.Maui or Ansight package by default, infer Ansight Studio registration metadata from the app, prefer the Ansight stdio bridge for agent setup, install or recommend the companion inspection skill at https://www.ansight.ai/skills/agents/ansight-app-inspection.md, set AnsightRemoteToolsPolicy to AllowedWithWarnings, inject a global tool guard that enables tools in developer builds and denies all tools in release builds, create ansight-readme.md with QR pairing next steps, and tell me what manual Ansight Studio, agent, or app wiring steps remain.

Prerequisites

  • A trusted desktop machine for running Ansight Studio.
  • A development build of your app on the same local network as Ansight Studio.
  • A .NET mobile app if you want to follow the SDK steps in this docs set.
  • A local AI client that can talk to MCP over stdio if you want agent-driven inspection.

1. Install Ansight Studio

Install Ansight Studio on your desktop and launch it before you start wiring the app.

Ansight Studio is the local control plane for:

  • issuing pairing configs
  • exporting QR pairing payloads
  • capturing and browsing sessions
  • exposing the local stdio-backed MCP bridge to agents

Use a developer-controlled machine, not a shared workstation.

2. Confirm the Local MCP Bridge

Prefer the stdio bridge for agent setup:

ansight-daemon mcp-stdio

Ansight Studio also exposes MCP over local HTTPS for clients that cannot use stdio:

https://localhost:45125/mcp/

Open Ansight Studio and confirm the MCP panel shows the bridge as running before you connect an agent.

3. Point Your Agent at Ansight Studio

Every MCP client has its own config shape. Prefer a stdio command config that launches ansight-daemon mcp-stdio.

For example, a stdio config usually looks like this on macOS:

{
  "ansight": {
    "command": "/Applications/Ansight.app/Contents/Helpers/ansight-daemon",
    "args": ["mcp-stdio"]
  }
}

Notes:

  • Use the exact config format your MCP client expects.
  • Prefer the ansight-daemon mcp-stdio setup in MCP Configuration so agents connect over stdio instead of directly handling Ansight Studio’s local HTTPS certificate.
  • Ansight Studio only accepts requests from localhost.
  • If your client cannot use stdio, use https://localhost:45125/mcp/ as the HTTP fallback.
  • For HTTP fallback, use localhost instead of 127.0.0.1 so the certificate hostname matches.
  • If your MCP client rejects the certificate and cannot use stdio, trust the exported data/mcp/localhost.cer certificate and retry.
  • The client handles MCP session initialization; you provide either the stdio command or the HTTP fallback endpoint.

For client-specific setup steps, read MCP Configuration.

4. Install the All-In-One SDK Package

Start with one of the all-in-one packages. They include the runtime setup, host connection support, native pairing where supported, and the default tool suites for the app type.

For a standard .NET app, use Ansight:

NuGet

dotnet add package Ansight --prerelease

For a .NET MAUI app, use Ansight.Maui instead:

NuGet

dotnet add package Ansight.Maui --prerelease

Use Ansight.Core only when you want manual registration and no bundled concrete tool packages.

5. Initialize Ansight in the App

For a standard .NET app:

using Ansight;

var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
        ansight.WithBundledHostConnection(typeof(AppBootstrap).Assembly);
    })
    .Build();

Runtime.InitializeAndActivate(options);

For a .NET MAUI app, call Ansight from MauiProgram:

using Ansight.Maui;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UseAnsight<App>();

    return builder.Build();
}

Both all-in-one paths configure host auto-probe, bundled host connection, live JPEG capture, and the relevant remote tools. Their callbacks run before default tool-suite registration, so access for deny-all suites such as secure storage is granted there. In MAUI:

using Ansight.Maui;
using Ansight.Tools.SecureStorage;

builder.UseAnsight<App>(ansight =>
{
    ansight.WithSecureStorageTools(secure =>
    {
        secure.WithStorageIdentifier("MyApp");
        secure.AllowKeyPrefix("ansight.secure.");
    });
});

Add WithBatteryLevel() or WithTouchCapture() in the same callback when you want battery charts or touch replay in local sessions.

Use the default AnsightRemoteToolsPolicy=AllowedWithWarnings for local development builds that intentionally include those tools. Use AnsightRemoteToolsPolicy=Disallowed in protected builds that omit tool packages.

6. Issue a Pairing Config in Ansight Studio

In Ansight Studio:

  1. Open the apps workspace.
  2. Register the app name and app identifier.
  3. Issue a pairing config for that app.
  4. Choose a duration that matches the workflow you need.

Ansight Studio stores the signed config locally and can also turn it into a QR payload for device-side pairing.

7. Pair the App

There are two common flows:

  • Developer pairing: enable AnsightDeveloperPairingEnabled in local Debug builds, initialize with WithAnsightSdk(...) or UseAnsight<App>(), and let the app connect with Runtime.HostConnection.ConnectAsync(HostConnectionRequest.Auto()).
  • QR pairing: Ansight and Ansight.Maui include native pairing where supported. If you are using Ansight.Core, install Ansight.Pairing, configure WithPlatformPairing(...), and call Runtime.HostConnection.ConnectAsync(HostConnectionRequest.QrCode()). If your app already scans the code itself, pass the payload with HostConnectionRequest.PayloadText(...).

The dedicated pairing guide is here:

8. Start Capturing Sessions

Once the app is paired and connected:

  • Ansight Studio shows live and saved sessions.
  • The dashboard exposes logs, telemetry, screenshots, touch input when enabled, and device metadata.
  • Agents connected over MCP can inspect Ansight Studio-owned data and, when enabled, live app tools.

Next Steps