Configure Chrome for NSP V8 Probing and CDP Integration

NSP’s V8 probe reads live application state from Chrome and Electron apps using the Chrome DevTools Protocol (CDP). CDP is a low-level debugging interface built into every Chrome binary, but it only activates when Chrome is launched with the --remote-debugging-port flag. Without that flag, the daemon has no channel into the V8 heap and cannot probe JavaScript apps at all. This guide walks you through launching Chrome correctly, verifying the connection, and keeping the setup persistent across reboots.

You must close all existing Chrome windows before relaunching with the debugging flag. Chrome only allows one remote debugging port per user profile. If any Chrome window is already running, the new instance will silently attach to the existing process and the flag will have no effect.

Why Chrome Needs the Remote Debugging Port

When the --remote-debugging-port=9222 flag is present, Chrome opens a local HTTP server on that port that speaks the CDP wire protocol. NSP’s V8 probe connects to this server to:

Enumerate open browser tabs and identify supported apps by URL pattern
Inject the __axon_aso_snapshot JavaScript snippet to read the application’s data model from the V8 heap directly (the fast-path, returning in 5–50 ms)
Fall back to a full heap snapshot when the fast-path is unavailable

Without this port, NSP cannot establish a CDP session, and no V8 apps will appear in GET /substrate/v1/apps.

Launch Chrome with Remote Debugging

Close all existing Chrome windows

Make sure every Chrome window is fully closed before proceeding. Check your system tray as well — Chrome sometimes continues running in the background after the last visible window closes. Right-click the Chrome icon in the tray and choose Exit if it appears.

Relaunch Chrome with the debugging flag

Open a new terminal and run one of the commands below. Both launch the same Chrome binary; choose whichever shell you prefer.

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

Start-Process "chrome.exe" -ArgumentList "--remote-debugging-port=9222"

Chrome will open a normal browser window. The debugging port is active as long as this Chrome process is running.

Open a supported app in a tab

Navigate to any NSP-supported JavaScript app in one of your Chrome tabs. Supported apps include:

Gmail — mail.google.com
Slack — app.slack.com
VS Code (web) — vscode.dev
Notion — notion.so
GitHub — github.com
HubSpot, Salesforce, Shopify, and most Electron apps

Wait a few seconds after the page finishes loading before checking detection — the ASO fast-path needs a moment to initialize on first attach.

Verify NSP detects the app

Query the apps endpoint to confirm the daemon has picked up Chrome and is actively probing your tab:

curl http://localhost:7842/substrate/v1/apps

You should see a response that includes at least one entry with "runtime": "v8" and "probe_status": "active":

{
  "total": 1,
  "apps": [
    {
      "pid": 12847,
      "app_id": "gmail-chrome-12847",
      "app_name": "Gmail",
      "runtime": "v8",
      "probe_status": "active",
      "confidence": 0.97,
      "object_count": 23,
      "action_count": 5
    }
  ]
}

Take note of the pid — you will use it when reading state or opening a WebSocket watch stream.

Verify Chrome is Accessible on the Debug Port

Before involving NSP at all, you can confirm Chrome is listening correctly by hitting its built-in CDP tab listing endpoint directly:

curl http://localhost:9222/json/list

A healthy response returns a JSON array of open tab descriptors. If you get a connection refused error, Chrome is not running with the debug port active — go back to Step 1.

Persistent Setup

Typing the launch command every time Chrome restarts is tedious. Instead, create a persistent launcher so Chrome always opens with the debug flag.

Windows .bat launcher

Create a file named chrome-debug.bat in a convenient location (for example, your Desktop or C:\Tools\):

chrome-debug.bat

@echo off
:: Close any existing Chrome process before launching
taskkill /IM chrome.exe /F >nul 2>&1
timeout /t 2 /nobreak >nul

:: Launch Chrome with the NSP remote debugging port
start "" "C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222

Double-click this file whenever you need Chrome in debugging mode. The taskkill line handles the “close all windows first” requirement automatically.

Desktop shortcut

Alternatively, create a Windows shortcut to Chrome and append the flag to the Target field:

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

Right-click the shortcut → Properties → Shortcut tab → paste the full target string above.

Multiple Chrome Profiles

Each Chrome user profile can only bind one debugging port. If you need to probe Chrome under multiple profiles simultaneously, launch each profile on a separate port:

# Profile 1 — Default
Start-Process "chrome.exe" -ArgumentList "--remote-debugging-port=9222 --profile-directory=Default"

# Profile 2 — Work
Start-Process "chrome.exe" -ArgumentList "--remote-debugging-port=9223 --profile-directory=`"Profile 1`""

You will also need to configure the daemon to scan additional ports. Add each port to the v8_debug_ports list in axon.toml:

[watcher]
v8_debug_ports = [9222, 9223]

Troubleshooting

Chrome not detected in /substrate/v1/apps

The most common cause is that an existing Chrome process was already running when you launched with the flag. The new instance attached to the old process, which has no debug port.Fix: Close every Chrome window — including any background instances in the system tray — then relaunch using the bat launcher or shortcut. After Chrome restarts, wait 5–10 seconds before querying the apps endpoint.

Port 9222 is already in use

Another process is already bound to port 9222, preventing Chrome from opening its debug server.Run the following command to identify what is using the port:

netstat -an | findstr 9222

If the output shows a LISTENING entry, find the owning process in Task Manager (or with netstat -ano | findstr 9222) and terminate it, or switch Chrome to a different port such as 9223.

Chrome is detected but no apps appear

The daemon found Chrome’s debug port but did not identify any supported app in the open tabs.Check: Make sure you have at least one supported app (Gmail, Slack, etc.) open in a tab and fully loaded before querying. A tab that is still loading or is showing an error page will not match any app signature.If the app is open but still not appearing, refresh the tab and wait another 10 seconds. The process scanner runs on a 5-second cycle by default.

Confidence is stuck below 0.80

A confidence value below 0.80 means the ASO fast-path is still initializing its semantic labels. This is normal for the first 5–10 seconds after a new tab is detected.Wait 5–10 seconds and re-query GET /substrate/v1/apps. Confidence for V8 apps typically settles between 0.95 and 0.99 once the fast-path completes its first full pass.If confidence stays low after 30 seconds, try refreshing the tab in Chrome and waiting again. A fully loaded page gives the probe more objects to label.

Get Started

The Daemon

Runtime Probes

Security

Guides

Why Chrome Needs the Remote Debugging Port

Launch Chrome with Remote Debugging

Verify Chrome is Accessible on the Debug Port

Persistent Setup

Windows .bat launcher

Desktop shortcut

Multiple Chrome Profiles

Troubleshooting

​Why Chrome Needs the Remote Debugging Port

​Launch Chrome with Remote Debugging

​Verify Chrome is Accessible on the Debug Port

​Persistent Setup

​Windows .bat launcher

​Desktop shortcut

​Multiple Chrome Profiles

​Troubleshooting

Why Chrome Needs the Remote Debugging Port

Launch Chrome with Remote Debugging

Verify Chrome is Accessible on the Debug Port

Persistent Setup

Windows .bat launcher

Desktop shortcut

Multiple Chrome Profiles

Troubleshooting