Developer inspector

The developer inspector attaches Chrome DevTools to a running DataMind Oda app, so you can debug the app's host process and its connected browser clients from one DevTools window. It is development tooling for a checkout, not part of the everyday app: it joins one run through an overlay file and listens on this computer only.

Turn the inspector on

Build the project first: pnpm run build. The overlay loads the inspector from the build output; 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.

Nothing is installed into your profile: a run started without the overlay has no inspector, and when the run stops, the inspector goes with it.

What it serves

Once it listens, the inspector serves these addresses on one local port:

Address	What it answers
`/json`, `/json/list`	The DevTools discovery documents.
`/json/version`	The version document for the protocol.
`/devtools/page/<id>`	The target socket DevTools attaches to.
`/ingest`	The socket a browser client connects to as a source.

What you can inspect

Console merges entries from the host and from every connected client.
Sources lists the host's scripts. For a connected client, only the inspector's own bundle is catalogued; other page scripts are not listed.
Network records the host's fetch calls with the full URL, request and response headers, bodies, status, timing, errors and cancellation. Bodies are kept as a prefix and marked truncated at the configured limits, and an aborted request keeps the bytes captured so far.
Runtime evaluates code in the host, or in a client you select; that selection routes evaluation, property access, function calls, promise awaiting and object release to the browser client.
Debugger serves the host: breakpoints, pause and resume work there, and console evaluation stays available while the host is paused. Client-script breakpoints, stepping and call frames are refused, and pause and resume never control a client.
Elements presents the app as one document with two fixed containers, <host> for the app's host side and <clients> for its browser clients, and one <client> entry per connected client. Levels load on demand, and a disconnected client's tree stays as the last snapshot it sent; the inspector retains up to eight disconnected trees.
A custom inspector domain is also served on the same connection: it turns its change notifications on and off, lists the connected sources, and reads the tree; the tree read needs no DevTools session and enables no other domain.

A connected client advertises runtime, console and sources, with its sources read-only; its capability list leaves out the debugger and the heap profiler.

Fields and defaults

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

Field	Default	Meaning
`host`	`127.0.0.1`	The bind address; only a loopback address is accepted.
`port`	`9230`	The first port tried; a busy port advances upward, and `0` asks the system for one.
`clientOrigins`	empty	Extra browser origins accepted by the ingest endpoint.
`captureFetch`	on	Record the host's `fetch` calls.
`maxRequestBodyBytes`	8 MiB	Request-body prefix kept per request.
`maxResponseBodyBytes`	32 MiB	Response-body prefix kept per request.
`maxBodyChunkBytes`	48 KiB	Raw bytes carried in one body record.
`maxJournalBytes`	256 MiB	Total body bytes kept.
`maxRetainedRequests`	2000	Requests kept.
`maxSourceFrameBytes`	128 KiB	Largest encoded source frame.
`startupTimeoutMs`	10 s	How long startup waits for readiness.
`stopTimeoutMs`	5 s	The window for a graceful stop.
`clientReconnectBaseMs`	250 ms	Starting client reconnect backoff.
`clientReconnectMaxMs`	5 s	Largest client reconnect backoff.
`clientRuntimeTimeoutMs`	30 s	Deadline for one runtime or sources command sent to a client.
`queryTimeoutMs`	10 s	Deadline for one non-DevTools query.

The same entry holds a few further bounds: maxSourceRecordsPerFrame 128, maxQueuedRecords 2048, maxQueuedBytes 16 MiB, maxClientRuntimeObjects 10000, maxClientRuntimeProperties 2000, maxClientSourceBytes 8 MiB, maxCordisNodes 2048 and maxDisconnectedCordisTrees 8.

Keep it safe

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 inspector binds to loopback only.
The browser ingest socket additionally requires a random token carried in the WebSocket subprotocol.
The DevTools socket itself has no token: the loopback binding is its only access control.
Fetch capture does not redact. Credentials, cookies, query values and payloads can be recorded, so treat captures as sensitive.

The worker and the bridge

DevTools state lives in a worker process, apart from the app; the worker never reads the app's live objects. The app's parts project validated snapshots into it.
The worker does not restart itself: if it exits, the run loses the inspector until you start the run again.
A browser client joins as a source over the ingest socket. It keeps buffered observations across reconnects and sends them in bounded frames and queues.

Messages you may see

Inspector Client query socket is not connected: a query was sent while the client's socket was between connections. Wait for it to reconnect and 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, and 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. The connection closes and reconnects with backoff; if it repeats, raise maxSourceFrameBytes.
Client source result exceeds the source-frame byte limit: a sources answer did not fit in one frame and was refused. Read fewer sources at once, or raise maxSourceFrameBytes.

Questions, answered

Can I add my own data to the inspector?

Yes. A plugin publishes snapshots with ctx.inspector.publish(topic, payload), and a script can read the detached tree with ctx.inspector.cordis.getTree(). Neither call needs a DevTools window.

How does the inspector see the app's state?

Through snapshots, never through live objects. The app's parts project validated snapshots into the worker, and DevTools works from those snapshots.

Why does client evaluation fail on some pages?

A client page's content security policy can refuse dynamic evaluation, and a client context has no DevTools command-line helpers. What a client offers is its console entries, evaluation and read-only sources.

Does network capture slow the app down?

It can. Full capture copies request and response streams, so a busy run adds memory and I/O pressure, and the retained-byte limit does not cover the buffering inside the stream copy.

Can I turn network capture off?

Yes. Set captureFetch to off in the overlay entry. Capture is on by default.

Are observations lost while a client reconnects?

No. The client keeps its buffered observations across a reconnect and sends them when it joins again, in bounded frames and queues. Its console entries flow only while its connection is open.

Can I debug several browser clients at once?

Yes. Every connected client joins as its own <client> entry, console entries merge from the host and from all of them, and evaluation goes to the client you select. A client keeps its identity across refreshes and reconnects, while a duplicated live tab gets a new one; a browser without Web Locks support cannot tell two live copies apart.

What does `[inspector] Client source rejected: <message>` mean?

The inspector refused a browser client as a source, and the carried message says why. The client closes that connection and retries with backoff, from 250 ms up to 5 s by default.

How much captured traffic does the inspector keep?

It is bounded: up to maxRetainedRequests requests, 2000 by default, and maxJournalBytes of body bytes, 256 MiB by default, with each body kept as a prefix of its own caps. Raise the fields in the overlay when a run needs more.

What does `Inspector Client query socket is not connected` mean?

A query reached the client while its socket was between connections, for example during a reconnect. The query is refused rather than queued, so wait for the connection and try again.