Developer inspector

The developer inspector lets Chrome DevTools attach to a running DataMind Oda app, so you can debug its host process and its connected browser clients from one DevTools window. It is development tooling for a source checkout rather than part of the everyday app, and it listens on this computer only.

Turn the inspector on

The inspector joins one run through an overlay file. Nothing is installed into your profile, so a run started without the overlay has no inspector.

Build the project first: pnpm run build. The overlay loads the inspector from the build output, and Building and shipping Oda covers building and running from source.
Start the web mode with the overlay: oda --profile web --patch ./packages/experimental/inspector/cordis.patch.yml
Open the devtools:// address the app logs once the inspector listens. Chrome DevTools attaches to the run from there.

In a source checkout, pnpm run demo:inspector starts the same web mode and loads the inspector from source instead of the build output.

The Elements view

The inspector presents the app as one document with two fixed containers: <host> for the app's host side, and <clients> for the browser clients that connect to it.

Each connected browser client is one <client> entry; it joins as a source and keeps its buffered observations through reconnects.
Node trees are depth-limited: expanding a node loads its children, so a large tree never loads in one piece.
When a browser client disconnects, its tree remains available as the last snapshot it sent, and the inspector retains up to eight disconnected trees.
The same connection also exposes a custom inspector domain that lists the connected sources and reads the tree; the tree read needs no DevTools session and enables no other debugging.

Defaults in the overlay

The inspector's fields live in its entry in the overlay you run. Set one there when a default does not fit:

host: 127.0.0.1; only a loopback address is accepted.
port: 9230; a busy port steps up to the next free one, and 0 asks the operating system to assign a port.

See the inspector reference for every field and default.

Safety

Warning

While the inspector runs, anything attached to its DevTools socket can run code in the host and in any connected browser client. Stop the run when you are done.

The debugging target grants arbitrary code execution in the host and in any connected client through evaluation; host debugger operations add further control on top.
The inspector binds to loopback only, and the client ingest socket additionally requires a random token carried in the WebSocket subprotocol.
The DevTools socket itself has no token: its loopback binding is the only access control.
Fetch capture does not redact. Credentials, cookies, query values and payloads can be recorded, so treat captures as sensitive.

Messages you may see

Message	What it means	What to do
`Inspector Client query socket is not connected`	A query was sent while the client's socket was between connections.	Wait for the client to reconnect, then try again.
`inspector: Client source is closed`	The client side was already closed when it tried to update its state, as happens during teardown.	Reload the page if the client should still be connected.
`[inspector] Client source rejected: <message>`	The inspector refused a browser client as a source; the message carries the reason.	Read the carried reason; the client closes that connection and retries with backoff.
`inspector protocol: Worker frame exceeds <n> bytes`	An incoming frame was larger than the frame limit, so the connection closes and reconnects with backoff.	If it repeats, the limit is too small for the data being sent; raise `maxSourceFrameBytes` in the overlay.
`Client source result exceeds the source-frame byte limit`	A sources answer did not fit in one frame, so the inspector refused it.	Read fewer sources at once, or raise `maxSourceFrameBytes` in the overlay.

Questions, answered

Do I need to install the inspector?

No. It joins one run through an overlay file; nothing is installed into your profile. A run started without the overlay has no inspector, and when that run stops, the inspector goes with it.

What do I open once the inspector is running?

The devtools:// address the app logs once the inspector listens; opening it attaches Chrome DevTools to the run.

Which parts of Oda can I debug?

DevTools reaches the host side fully: console, sources, evaluation, breakpoints, pause and resume all work there. A connected browser client adds its console entries, evaluation and read-only sources; breakpoints, stepping and call frames are not supported in a client, and pause and resume never control one. The capability list a browser client advertises leaves out the debugger and the heap profiler.

Why does the tree show only the levels I expand?

Node trees arrive one level at a time: a level is withheld until you expand its parent, and a node you have not opened shows only how many children it holds.

Can I reach the inspector from another computer?

No. Only a loopback address is accepted for the bind, and the client ingest socket additionally requires a random token, so nothing outside this computer can reach it.

Why did the inspector stop working mid-run?

The inspector's worker process exited. It does not restart the worker on its own, so that run loses the inspector; start the run again to get it back.

What does `Client source result exceeds the source-frame byte limit` mean?

A sources answer was too large for one frame, so the inspector refused it. Read fewer sources at once, or raise maxSourceFrameBytes in the overlay.

Can I run the inspector without building first?

No. The overlay loads the inspector from the build output, so build the project first. In a source checkout, pnpm run demo:inspector loads it from source instead.