> For the complete documentation index, see [llms.txt](https://docs.sealights.io/knowledgebase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md).

# Configuration and Runtime Overrides

The Browser Agent is configured in two places:

* **At instrumentation**, by `slnodejs scan --instrumentForBrowsers` or `slnodejs instrument` flags and by environment variables of that CI step. These values are written into the build.
* **At runtime**, by values that a page or a test sets on `window` before the instrumented files run.

## Lab ID <a href="#lab-id" id="lab-id"></a>

Coverage is attributed to the test stage that is open for the agent's lab ID. For each build on the page, the agent uses the first non-empty value of:

1. `window["__sl.labId__"]`, which applies to every build on the page;
2. the lab ID the build was instrumented with (`--labId`);
3. the build session ID of the build;
4. the application name of the build;
5. `DefaultLabId`.

The agent logs the lab ID it uses as `LabId:<value>`.

To set it at runtime, add a script that runs before the instrumented files, for example in the environment's HTML template:

```html
<script>window['__sl.labId__'] = 'staging-env';</script>
```

Use this to deploy one instrumented build to several environments, each with its own lab ID.

## Collector and token exposure <a href="#collector" id="collector"></a>

When the build is instrumented with `--collectorUrl`, the preamble loads the agent from the Collector, and the agent sends footprints to the Collector instead of directly to SeaLights. In this mode the agent does not ask SeaLights for the open test stage itself.

By default the agent token is written into the configuration of every instrumented build, so anyone who can open the deployed application can read it. To keep it out of the deployed files, also pass `--excludeTokenFromBrowserConfig`. The configuration then carries no token, and the agent sends none. Use `--excludeTokenFromBrowserConfig` only together with `--collectorUrl`: without a Collector, `slnodejs` prints a warning, and the agent calls SeaLights without a token.

## Restricting the agent to specific domains <a href="#allowed-domains" id="allowed-domains"></a>

When the same instrumented files can be served on several domains, instrument with `--allowedDomains`. The preamble then loads the agent script and the sl-mapping only when the page's host name (`window.location.hostname`) is in the list. To skip the agent on a single page, see [Skipping the agent on a page](#skipping-the-agent-on-a-page).

## Content security policy <a href="#content-security-policy" id="content-security-policy"></a>

A page with a content security policy must allow:

* in `script-src`: the host of the agent script that the preamble loads. Find its URL in the network tab of an instrumented page. When the build has a Collector URL, the script is loaded from the Collector, which redirects to the agent script; allow the redirect target as well. With `--ctxPropagationOnly`, allow the host of the OpenTelemetry plugin script instead (see [Context Propagation](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/context-propagation.md)). With `--splitPreambleIntoFile`, also allow the page's own origin, which serves the preamble file;
* in `connect-src`: SeaLights, or the Collector when the build has a Collector URL, because the agent downloads the sl-mapping and sends footprints, events and execution queries there.

`--splitPreambleIntoFile` moves the agent configuration out of the instrumented files, but the page still loads the agent from SeaLights or the Collector. See also [CSP Errors in Instrumented JS Frontend Apps](https://docs.sealights.io/knowledgebase/setup-and-configuration/troubleshooting-faq/node-javascript/csp-errors-in-instrumented-js-frontend-apps.md).

## Coverage settings <a href="#coverage-settings" id="coverage-settings"></a>

These `slnodejs` options change what the agent collects and sends. Pass them to the command that instruments the build.

| Option                                 | Effect                                                                                                                                                                       | When to use                                                              |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `--footprintsMapping server`           | The agent does not download the sl-mapping; SeaLights resolves the footprints. Default: `agent` (the agent downloads the sl-mapping and resolves footprints in the browser). | Very large applications, where the sl-mapping download slows page loads. |
| `--enableLineCoverage` (`scan` only)   | The agent reports line-level coverage in addition to methods.                                                                                                                | When line coverage is required.                                          |
| `--embedCorrectUniqueId` (`scan` only) | The instrumented files carry their own mapping; the agent does not download the sl-mapping.                                                                                  | Alternative to downloading the sl-mapping.                               |

`slnodejs instrument` does not accept `--enableLineCoverage` or `--embedCorrectUniqueId`; it takes both from the scan of the build.

Removing sensitive values from the agent start and agent event data has no `slnodejs` flag. SeaLights applies it to your account's builds when `slnodejs` instruments them; ask SeaLights support to turn it on.

## Settings read from the instrumentation environment <a href="#settings-read-from-the-instrumentation-environment" id="settings-read-from-the-instrumentation-environment"></a>

`--help` does not show these settings. `slnodejs` reads them from its own environment when it instruments the build and writes them into the build's configuration, so set them on the CI step that runs `slnodejs scan --instrumentForBrowsers` or `slnodejs instrument`, not in the browser.

| Variable                           | Effect                                                                                                                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `SL_blockBrowserHttpTraffic=true`  | The agent sends no requests to SeaLights or the Collector: no footprints, events or execution queries, and no sl-mapping download. The browser still loads the preamble file and the agent script.     |
| `SL_footprintsCollectIntervalSecs` | How often the agent moves collected hits into its send buffer, in seconds.                                                                                                                             |
| `SL_executionQueryIntervalSecs`    | How often the agent asks SeaLights for the open test stage, in seconds. The agent also sends buffered footprints at this interval; `SL_footprintsSendIntervalSecs` has no effect on the Browser Agent. |
| `SL_footprintsBufferThresholdMb`   | Buffer size at which the agent sends footprints before the interval elapses.                                                                                                                           |

```bash
export SL_executionQueryIntervalSecs=5
npx slnodejs scan --tokenFile sltoken.txt --buildSessionIdFile buildSessionId \
  --scanDir dist --outputPath sl_dist --scmType git --instrumentForBrowsers
```

The variables that change how `slnodejs` instruments the files (for example `SL_reduceInstrumentedFileSize`) are listed on [Frontend Instrumentation → Settings without a flag](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/capturing-runtime-coverage/frontend-instrumentation-static.md#settings-without-a-flag).

## Footprints when the page closes <a href="#footprints-when-the-page-closes" id="footprints-when-the-page-closes"></a>

The agent sends footprints periodically. When the page unloads, it also tries to send the footprints it still holds, but that request goes to the page's own origin without a token, so it does not reach SeaLights or the Collector. Footprints collected since the last periodic send can therefore be lost when a test closes the page or the browser.

To send them, have the test call `window.$SealightsAgent.sendAllFootprints()` and wait for it before closing the page:

```js
await window.$SealightsAgent.sendAllFootprints();
```

For example, in Playwright:

```js
await page.evaluate(() => window.$SealightsAgent && window.$SealightsAgent.sendAllFootprints());
await page.close();
```

## Runtime overrides <a href="#runtime-overrides" id="runtime-overrides"></a>

A page, or a test, can change the agent's behavior without re-instrumenting. Set these values on `window` in a script that runs before the instrumented files.

| Override                                                  | Effect                                                                                                                                                                                                    |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `window["__sl.labId__"] = "<lab-id>"`                     | Sets the lab ID for every build on the page. See [Lab ID](#lab-id).                                                                                                                                       |
| `window.$Sealights = { skipSlAgent: true }`               | The preamble does not load the agent or the sl-mapping on this page. See below.                                                                                                                           |
| `window.$Sealights.configuration = { logLevel: "debug" }` | Sets the agent's console log level. See [Agent log level](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/troubleshooting.md#agent-log-level). |

### Skipping the agent on a page <a href="#skipping-the-agent-on-a-page" id="skipping-the-agent-on-a-page"></a>

When `window.$Sealights.skipSlAgent` is truthy, the preamble does not load the agent script or the sl-mapping on that page:

```html
<script>window.$Sealights = { skipSlAgent: true };</script>
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/browser-agent/configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
