Automate .NET Desktop Apps Using the NSP CLR Probe

NSP’s CLR probe lets your AI agent read live data from any running .NET application and invoke its methods directly — without hooking into the UI, writing interop code, or modifying the target app. The probe attaches to the target process, normalises field values and method return values into the Substrate Schema Format (SSF), and makes them available over the standard NSP API. This guide walks you through detecting a .NET app, reading its state, exploring actions, and executing CLR method calls.

Prerequisites

Confirm the following before you begin:

NSP daemon installed and running on port 7842. Download from platform.nelieo.com/download.
.NET Framework 4.8 or later installed on the host machine. The CLR probe targets both .NET 4.x and .NET 6+ apps.
The target .NET application is running. The daemon scans for processes every 5 seconds, so start your app before you query for it. This guide uses Mission Planner (a C# Ground Control Station) as the example; the same steps apply to any WinForms, WPF, or .NET console app.
Python 3.11+ and the NSP SDK installed.

pip install nelieo-nsp

An NSP API key from platform.nelieo.com, stored in the NSP_API_KEY environment variable.

# Windows (Command Prompt)
set NSP_API_KEY=nsp_live_sk_your_key_here

Detect the .NET App

Call the /substrate/v1/apps endpoint to confirm the daemon has detected and classified your application. Look for "runtime": "clr" in the response.

curl -H "X-Substrate-Key: nsp_live_sk_..." http://localhost:7842/substrate/v1/apps

Example response showing Mission Planner as a CLR app:

{
  "total": 2,
  "apps": [
    {
      "pid": 4521,
      "app_id": "mission-planner-4521",
      "app_name": "Mission Planner",
      "runtime": "clr",
      "runtime_name": ".NET CLR",
      "probe_status": "active",
      "confidence": 0.95,
      "object_count": 47,
      "action_count": 12,
      "last_captured_at": "2026-07-20T13:00:01Z",
      "has_state": true,
      "current_view": null,
      "current_url": null
    }
  ]
}

You can also check with the Python SDK:

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        apps = await client.list_apps()
        for app in apps:
            print(f"{app.app_name:<25}  runtime={app.runtime:<5}  "
                  f"conf={app.confidence:.2f}  status={app.probe_status}")

asyncio.run(main())

Expected output:

Mission Planner            runtime=clr    conf=0.95  status=active

The first time the CLR probe attaches to a process, it may take up to 90 seconds to complete the cold probe (heap enumeration + schema learning). Subsequent runs use the cached schema and attach in under a second. Check probe_status — it progresses from attaching → cold_probe → active.

Read .NET App State

Once attached, use session.get_*() with dot-notation keys to read values that the CLR probe has normalised into SSF. The exact keys available depend on the application; call session.state.objects to see all discovered keys.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        session = await client.attach("Mission Planner")
        print(f"Confidence: {session.confidence:.2f}")

        # Normalised SSF state keys
        alt     = session.get_float("flight.altitude_m")
        lat     = session.get_float("flight.gps.latitude")
        lon     = session.get_float("flight.gps.longitude")
        mode    = session.get_str("flight.mode")
        armed   = session.get_bool("flight.is_armed")
        battery = session.get_float("flight.battery_voltage")

        print(f"Position : {lat:.6f}, {lon:.6f}")
        print(f"Altitude : {alt:.1f} m")
        print(f"Mode     : {mode}")
        print(f"Armed    : {armed}")
        print(f"Battery  : {battery:.1f} V")

        # Print all discovered state keys
        print("\nAll state keys:")
        for key, value in session.state.objects.items():
            print(f"  {key} = {value!r}")

asyncio.run(main())

Expected output:

Confidence: 0.95
Position : 34.052200, -118.243700
Altitude : 42.3 m
Mode     : GUIDED
Armed    : True
Battery  : 12.4 V

All state keys:
  flight.altitude_m = 42.3
  flight.gps.latitude = 34.0522
  flight.gps.longitude = -118.2437
  flight.mode = 'GUIDED'
  flight.is_armed = True
  flight.battery_voltage = 12.4
  ...

Explore Available Actions

Iterate session.actions to see what NSP discovered for this CLR app. Each entry shows the action name, its full type signature, and its reversibility classification.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        session = await client.attach("Mission Planner")

        print(f"{'Action':<25} {'Reversibility':<22} Signature")
        print("-" * 85)
        for name, schema in session.actions.items():
            print(f"{name:<25} {schema.reversibility:<22} {schema.signature}")

asyncio.run(main())

Example output for Mission Planner:

Action                    Reversibility          Signature
---------------------     ---------------------  -------------------------------------------
arm_motors                reversible_write       fn() -> bool
disarm_motors             reversible_write       fn() -> bool
set_mode                  reversible_write       fn(mode: string) -> bool
take_off                  irreversible_write     fn(altitude_m: float) -> bool
set_waypoint              reversible_write       fn(lat: float, lon: float, alt_m: float) -> bool
return_to_launch          irreversible_write     fn() -> bool

Execute a CLR Action

Use session.execute() to run an action. For reversible_write actions you do not need a verify_expression, though you can add one. The example below arms the motors — a reversible operation that can be undone with disarm_motors.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        session = await client.attach("Mission Planner")

        # Reversible: arm the motors
        result = await session.execute(
            "arm_motors",
            parameters={},
        )
        print(f"Arm result : {result.success}  latency={result.latency_ms}ms")

        # Irreversible: take off to 50 m — requires verify
        result = await session.execute(
            "take_off",
            parameters={"altitude_m": 50.0},
            verify=True,
            verify_expression="flight.altitude_m > 45.0",
            verify_timeout_ms=30000,   # 30 s — takeoff takes time
        )
        print(f"Takeoff    : {result.success}")
        if result.verification:
            print(f"Verified   : {result.verification.passed}  "
                  f"({result.verification.explanation})")

asyncio.run(main())

Expected output:

Arm result : True  latency=210ms
Takeoff    : True
Verified   : True  (flight.altitude_m changed from 0.0 to 50.2)

Handle the raw_return Field

When NSP invokes a CLR method rather than a higher-level action, the response includes a raw_return field containing the .NET method’s return value serialised to JSON. Check this field when you need the actual return value of a method call rather than a simple success boolean.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        session = await client.attach("Mission Planner")

        # Invoke a .NET method directly via the CLR helper
        result = await session.execute(
            "get_status_text",   # discovered CLR method action
            parameters={},
        )

        print(f"Success    : {result.success}")
        print(f"raw_return : {result.raw_return}")
        # raw_return contains the .NET string return value, e.g. "Throttle: 65%"

        # For methods that return structured objects, raw_return is a dict
        result2 = await session.execute("get_telemetry_snapshot", parameters={})
        snapshot = result2.raw_return
        if isinstance(snapshot, dict):
            print(f"Altitude from raw_return: {snapshot.get('AltitudeM')}")

asyncio.run(main())

raw_return is null for actions that do not map to a direct method invocation (for example, actions that trigger UI events). The success field always reflects whether the action completed without error, regardless of raw_return.

Cold Probe Timing and Confidence

The first time NSP attaches the CLR probe to a process, it must enumerate the full CLR heap to build the schema — this is called a cold probe and can take up to 90 seconds. Subsequent attachments use the cached schema and complete in under a second.You can monitor probe progress by polling /substrate/v1/apps and checking probe_status and confidence:

import asyncio
import nelieo_nsp as nsp

async def wait_for_clr_app(app_name: str, timeout: float = 120.0):
    async with nsp.NSPClient() as client:
        # wait_for_app retries until probe_status == "active"
        session = await client.wait_for_app(app_name, timeout=timeout)
        print(f"Ready: {session.app_name}  "
              f"conf={session.confidence:.2f}  "
              f"objects={len(session.state.objects)}")
        return session

asyncio.run(wait_for_clr_app("Mission Planner"))

The probe_status field moves through these stages:

`probe_status`	Meaning
`detecting`	Daemon has spotted the process but not yet classified it
`attaching`	CLR bootstrapper DLL is being injected
`cold_probe`	First heap enumeration in progress (up to 90 s)
`active`	Probe is running; state is fresh and usable
`error`	Last probe attempt failed; daemon will retry automatically

Actions are gated by confidence. The CLR probe typically reaches 0.93–0.97 confidence once active. reversible_write actions require confidence >= 0.80; irreversible_write actions require confidence >= 0.95.

Full Workflow Example

The script below covers the complete CLR probe workflow: detection, state reading, action execution, and real-time streaming.

import asyncio
import nelieo_nsp as nsp

async def dotnet_agent():
    async with nsp.NSPClient() as client:
        # ── Wait for Mission Planner to be ready ─────────────────────────
        print("Waiting for Mission Planner (cold probe may take ~90s)…")
        session = await client.wait_for_app("Mission Planner", timeout=120.0)
        print(f"Connected: conf={session.confidence:.2f}  "
              f"objects={len(session.state.objects)}  "
              f"actions={len(session.actions)}")

        # ── Read normalised state ────────────────────────────────────────
        alt   = session.get_float("flight.altitude_m")
        mode  = session.get_str("flight.mode")
        armed = session.get_bool("flight.is_armed")
        batt  = session.get_float("flight.battery_voltage")
        print(f"\nAlt={alt:.1f}m  Mode={mode}  Armed={armed}  Batt={batt:.1f}V")

        # ── List available actions ───────────────────────────────────────
        print("\nAvailable actions:")
        for name, schema in session.actions.items():
            print(f"  {name:<25} [{schema.reversibility}]")

        # ── Arm the vehicle (reversible) ─────────────────────────────────
        arm_result = await session.execute("arm_motors", parameters={})
        print(f"\nArmed: {arm_result.success}  "
              f"raw_return={arm_result.raw_return!r}")

        # ── Take off to 30 m (irreversible — requires verify) ────────────
        takeoff_result = await session.execute(
            "take_off",
            parameters={"altitude_m": 30.0},
            verify=True,
            verify_expression="flight.altitude_m > 25.0",
            verify_timeout_ms=30000,
        )
        print(f"Airborne: {takeoff_result.success}")

        # ── Stream telemetry changes ─────────────────────────────────────
        print("\nStreaming telemetry (Ctrl+C to stop)…")
        async with session.watch(auto_refresh_on_event=True) as stream:
            async for event in stream:
                if not any(k.startswith("flight.") for k in event.changed_keys):
                    continue
                alt  = session.get_float("flight.altitude_m")
                mode = session.get_str("flight.mode")
                batt = session.get_float("flight.battery_voltage")
                print(f"  [seq={event.sequence}] "
                      f"Alt={alt:.1f}m  Mode={mode}  Batt={batt:.1f}V")

                # Safety: return to launch if battery drops below 20%
                remaining = session.get_float("flight.battery_remaining")
                if remaining < 20.0:
                    print("⚠  Low battery — commanding RTL")
                    await session.execute(
                        "set_mode",
                        parameters={"mode": "RTL"},
                        verify=True,
                        verify_expression="flight.mode == 'RTL'",
                    )

asyncio.run(dotnet_agent())

Get Started

The Daemon

Runtime Probes

Security

Guides

Full Workflow Example

​Full Workflow Example

Full Workflow Example