> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelieo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable Chrome Remote Debugging for NSP V8 State Probing

> Configure Chrome's remote debugging port for NSP V8 state extraction — launch flags, Windows shortcuts, profile isolation, and verification steps.

NSP reads JavaScript state from Chrome tabs — Gmail, Google Calendar, Slack Web, and other browser-based apps — by connecting to the Chrome DevTools Protocol (CDP). CDP is Chrome's built-in remote control interface, used by debuggers, test runners, and profilers. By default it is disabled for security reasons. You must enable it at launch by passing a single command-line flag.

## Why CDP Is Needed

The NSP daemon's V8 probe connects to CDP to:

* Walk the V8 heap and extract live JavaScript object graphs from open tabs
* Read DOM state for UI-rendered data not available in network responses
* Inject lightweight state-capture scripts that run inside the page's JavaScript context

Without the debug port open, NSP cannot attach to any Chrome-based application.

## Launching Chrome with the Debug Port

<Warning>
  Close **all** existing Chrome windows before running these commands. Chrome only allows one debug session per user profile. If any Chrome window is already open (even minimized), the new instance will inherit the existing profile and silently ignore the `--remote-debugging-port` flag.
</Warning>

<Tabs>
  <Tab title="Command Prompt">
    ```cmd theme={null}
    "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    # Close any running Chrome first
    Stop-Process -Name chrome -ErrorAction SilentlyContinue
    Start-Sleep -Seconds 1

    # Launch with debug port
    Start-Process "chrome.exe" -ArgumentList "--remote-debugging-port=9222"
    ```
  </Tab>

  <Tab title="Dedicated profile (recommended)">
    Using a separate user data directory lets your normal Chrome session continue running alongside the NSP-enabled instance:

    ```cmd theme={null}
    "C:\Program Files\Google\Chrome\Application\chrome.exe" ^
      --remote-debugging-port=9222 ^
      --user-data-dir="C:\Temp\ChromeNSP"
    ```

    The `--user-data-dir` path is created automatically on first launch. It stores cookies, extensions, and session data separately from your default profile.
  </Tab>
</Tabs>

## Verify CDP Is Active

After launching Chrome, confirm the debug port is responding before starting the NSP daemon:

```bash theme={null}
curl http://localhost:9222/json/version
```

You should see a JSON response like:

```json theme={null}
{
  "Browser": "Chrome/127.0.0.0",
  "Protocol-Version": "1.3",
  "User-Agent": "Mozilla/5.0 ...",
  "V8-Version": "12.7.224.20",
  "WebKit-Version": "537.36 ...",
  "webSocketDebuggerUrl": "ws://localhost:9222/devtools/browser/..."
}
```

If this returns an error or nothing at all, Chrome is not running with CDP enabled. Close all Chrome windows and relaunch with the flag.

## Create a Windows Shortcut

Create a permanent desktop shortcut so you don't have to retype the command each time:

<Steps>
  <Step title="Right-click the Desktop">
    Select **New → Shortcut**.
  </Step>

  <Step title="Set the target">
    Paste this as the shortcut location (adjust for your Chrome installation path if needed):

    ```text theme={null}
    "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\Temp\ChromeNSP"
    ```
  </Step>

  <Step title="Name the shortcut">
    Give it a recognisable name such as `Chrome (NSP)` so it's easy to distinguish from your regular Chrome shortcut.
  </Step>

  <Step title="Launch and verify">
    Double-click the new shortcut, then run `curl http://localhost:9222/json/version` to confirm the port is active.
  </Step>
</Steps>

## Chrome Profile Considerations

Every Chrome profile has its own cookies, login sessions, and extensions. Which profile matters for NSP:

<CardGroup cols={2}>
  <Card title="Default profile" icon="user">
    Works fine if you always close normal Chrome before launching the NSP-enabled instance. You'll be logged in to all your accounts already.
  </Card>

  <Card title="Dedicated NSP profile" icon="shield">
    Recommended for production. Use `--user-data-dir="C:\Temp\ChromeNSP"` to create a separate profile. Log in to the accounts your agent needs and leave normal Chrome untouched.
  </Card>
</CardGroup>

<Info>
  Extensions installed in your default profile are not available in a dedicated `--user-data-dir` profile. If your target application requires a Chrome extension to function, install it in the NSP profile.
</Info>

## Opening the Target Application

After Chrome is running with CDP active, navigate to the application you want NSP to monitor. The daemon identifies tabs by URL pattern:

| URL                   | NSP App Name    |
| --------------------- | --------------- |
| `mail.google.com`     | Gmail           |
| `calendar.google.com` | Google Calendar |
| `app.slack.com`       | Slack Web       |
| `docs.google.com`     | Google Docs     |

Each open tab that matches a known URL pattern appears as a separate entry in `GET /substrate/v1/apps`. You can have multiple tabs open simultaneously.

## Electron Apps

Electron applications (VS Code, Slack Desktop, Discord, Figma, and others) embed their own Chromium and typically expose CDP automatically. NSP detects them from the process command line — no manual flag required:

```cmd theme={null}
code.exe    # VS Code — NSP detects automatically
slack.exe   # Slack Desktop — NSP detects automatically
```

If an Electron app in your environment does *not* expose CDP, launch it with its own debug port:

```cmd theme={null}
your-app.exe --remote-debugging-port=9223
```

Use a port other than 9222 if Chrome is already using that port.

## What Happens When Chrome Closes

If Chrome is closed while NSP is streaming state from it:

1. The daemon detects the process exit within one scan cycle (default: 5 seconds).
2. All active `session.watch()` streams for that PID close with a `WebSocketClosed` error.
3. When Chrome relaunches **with the debug port flag**, the daemon re-detects it and creates a new session with a new PID.
4. Your agent should call `client.wait_for_app()` after reconnecting to handle the new session gracefully.

```python theme={null}
import asyncio
import nelieo_nsp as nsp

async def robust_connect(client):
    """Wait for Gmail to appear, even across Chrome restarts."""
    while True:
        try:
            session = await client.wait_for_app("Gmail", timeout=60.0)
            return session
        except nsp.NSPNotFoundError:
            print("Gmail not found — is Chrome open with --remote-debugging-port=9222?")
            await asyncio.sleep(10)
```

## Troubleshooting

| Symptom                               | Cause                            | Fix                                                                    |
| ------------------------------------- | -------------------------------- | ---------------------------------------------------------------------- |
| `curl localhost:9222` returns nothing | Chrome not running with CDP flag | Close all Chrome windows, relaunch with `--remote-debugging-port=9222` |
| `GET /apps` returns no Chrome apps    | Chrome open but flag not set     | Verify with `curl http://localhost:9222/json/version`                  |
| Two Chrome instances conflict         | Separate profile already running | Use `--user-data-dir` to isolate each instance                         |
| Gmail not listed in `GET /apps`       | Tab not open                     | Navigate to `mail.google.com` in the debug-enabled Chrome              |
| `confidence: 0.40` doesn't increase   | Cold probe still running         | Wait 30–90 seconds; confidence rises as the probe finishes             |
| Electron app not detected             | App doesn't expose CDP           | Launch with `--remote-debugging-port=NNNN`                             |