Enable Chrome Remote Debugging for NSP V8 State Probing

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

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.

Command Prompt
PowerShell
Dedicated profile (recommended)

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

# 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"

Using a separate user data directory lets your normal Chrome session continue running alongside the NSP-enabled instance:

"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.

Verify CDP Is Active

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

curl http://localhost:9222/json/version

You should see a JSON response like:

{
  "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:

Right-click the Desktop

Select New → Shortcut.

Set the target

Paste this as the shortcut location (adjust for your Chrome installation path if needed):

"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="C:\Temp\ChromeNSP"

Name the shortcut

Give it a recognisable name such as Chrome (NSP) so it’s easy to distinguish from your regular Chrome shortcut.

Launch and verify

Double-click the new shortcut, then run curl http://localhost:9222/json/version to confirm the port is active.

Chrome Profile Considerations

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

Default profile

Works fine if you always close normal Chrome before launching the NSP-enabled instance. You’ll be logged in to all your accounts already.

Dedicated NSP profile

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.

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.

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:

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:

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:

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

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`

Get Started

The Daemon

Runtime Probes

Security

Guides

Why CDP Is Needed

Launching Chrome with the Debug Port

Verify CDP Is Active

Create a Windows Shortcut

Chrome Profile Considerations

Default profile

Dedicated NSP profile

Opening the Target Application

Electron Apps

What Happens When Chrome Closes

Troubleshooting

​Why CDP Is Needed

​Launching Chrome with the Debug Port

​Verify CDP Is Active

​Create a Windows Shortcut

​Chrome Profile Considerations

Default profile

Dedicated NSP profile

​Opening the Target Application

​Electron Apps

​What Happens When Chrome Closes

​Troubleshooting

Why CDP Is Needed

Launching Chrome with the Debug Port

Verify CDP Is Active

Create a Windows Shortcut

Chrome Profile Considerations

Opening the Target Application

Electron Apps

What Happens When Chrome Closes

Troubleshooting