> 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/node.js-agent/downloading-the-node.js-agent.md).

# Installing the Node.js Agent

Install the slnodejs package from npm: latest version, the version SeaLights recommends for your account, or a pinned version.

The SeaLights Node.js agent is the npm package [`slnodejs`](https://www.npmjs.com/package/slnodejs). There is no separate binary to download.

{% hint style="info" %}
**Using an internal registry?** If your organization mirrors npm packages through Artifactory, Nexus or another private registry, install `slnodejs` from that registry. The package name and version syntax are the same.
{% endhint %}

## Requirements <a href="#requirements" id="requirements"></a>

| Item                         | Supported                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Node.js                      | 18 and later (SeaLights tests 18, 20 and 22). The package declares `>=16` in `engines`, but Node.js 16 is not supported. |
| Operating systems            | Linux (tested by SeaLights). macOS and Windows have no restriction in `slnodejs` but are not tested by SeaLights.        |
| Package managers             | npm, pnpm and Yarn.                                                                                                      |
| Lightweight V8 coverage mode | Node.js later than 20.6.0.                                                                                               |

## Where to install it <a href="#where-to-install-it" id="where-to-install-it"></a>

* **In the project, as a development dependency**, for build scanning and test runs in CI:

  ```bash
  npm install --save-dev slnodejs
  npx slnodejs --help
  ```
* **As a regular dependency**, when the application runs with the preload script in an environment that installs production dependencies only (for example a container image built with `npm ci --omit=dev`):

  ```bash
  npm install slnodejs
  ```

`npx slnodejs <command> --help` prints every flag of a command. See the [Command Reference](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/command-reference.md).

## Choosing a version <a href="#choosing-a-version" id="choosing-a-version"></a>

| Strategy                                    | When to use                                                                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [Recommended version](#recommended-version) | **Production pipelines.** Install the version that SeaLights recommends for your account; SeaLights support can lock it. |
| [Pinned version](#pinned-version)           | When your organization requires reviewed dependency versions. Upgrade on your schedule.                                  |
| [Latest version](#latest-version)           | Proofs of concept and local trials.                                                                                      |

### Recommended version <a href="#recommended-version" id="recommended-version"></a>

#### Option A: the installer package

`slnodejs-installer` asks SeaLights which `slnodejs` version is recommended for your account and installs it. When no version is locked for the account, it installs the latest version.

1. Provide the agent token: in the environment variable `SL_TOKEN`, or in `sltoken.txt` in the directory where you run the installer.
2. Install the installer, then **run it**:

{% tabs %}
{% tab title="Bash" %}

```bash
printf '%s' "$SEALIGHTS_AGENT_TOKEN" > sltoken.txt
npm install slnodejs-installer
npx slnodejs-installer
npx slnodejs --help
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
Set-Content -Path sltoken.txt -Value $env:SEALIGHTS_AGENT_TOKEN -NoNewline
npm install slnodejs-installer
npx slnodejs-installer
npx slnodejs --help
```

{% endtab %}

{% tab title="GitHub Actions" %}

```yaml
- name: Install the SeaLights Node.js agent
  env:
    SL_TOKEN: ${{ secrets.SEALIGHTS_AGENT_TOKEN }}
  run: |
    npm install slnodejs-installer
    npx slnodejs-installer
    npx slnodejs --help
```

{% endtab %}

{% tab title="Azure DevOps" %}

```yaml
- script: |
    npm install slnodejs-installer
    npx slnodejs-installer
    npx slnodejs --help
  displayName: Install the SeaLights Node.js agent
  env:
    SL_TOKEN: $(SEALIGHTS_AGENT_TOKEN)
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The installer runs `npm install --no-save`, so `slnodejs` is not added to `package.json`. A later `npm install` or `npm ci` removes it. Run the installer after those commands, in the same job that runs `slnodejs`.
{% endhint %}

The installer also creates template `.slignore`, `.slignore.generated` and `.slignore.instrument` files when they do not exist. The templates exclude files from the scan; review them before the first scan. See [Configuration → Ignore files](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/configuration.md#ignore-files).

#### Option B: query the recommended version yourself

Use this when you do not want an extra package. The endpoint is the one the installer uses. It returns the recommended version in `agent.version`, or HTTP 404 when no version is locked for the account.

```
GET https://<your-domain>.sealights.co/api/v2/agents/slnodejs/recommended?customerId=<your-customer-id>
Authorization: Bearer <agent-token>
```

`<your-customer-id>` is the part before `@` in the `subject` claim of the agent token.

{% tabs %}
{% tab title="Bash" %}

```bash
SL_DOMAIN="<your-domain>.sealights.co"
SL_CUSTOMER_ID="<your-customer-id>"
SL_TOKEN="$(cat sltoken.txt)"

RESPONSE=$(curl -s -w '\n%{http_code}' \
  -H "Authorization: Bearer ${SL_TOKEN}" \
  "https://${SL_DOMAIN}/api/v2/agents/slnodejs/recommended?customerId=${SL_CUSTOMER_ID}")
STATUS=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$STATUS" = "200" ]; then
  VERSION=$(echo "$BODY" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).agent.version))')
else
  VERSION=latest   # 404: no version lock for the account
fi

npm install --save-dev "slnodejs@${VERSION}"
npx slnodejs --help
```

{% endtab %}

{% tab title="PowerShell" %}

```powershell
$SL_DOMAIN = "<your-domain>.sealights.co"
$SL_CUSTOMER_ID = "<your-customer-id>"
$SL_TOKEN = (Get-Content sltoken.txt -Raw).Trim()

try {
  $response = Invoke-RestMethod -Method Get `
    -Uri "https://$SL_DOMAIN/api/v2/agents/slnodejs/recommended?customerId=$SL_CUSTOMER_ID" `
    -Headers @{ Authorization = "Bearer $SL_TOKEN" }
  $VERSION = $response.agent.version
} catch {
  $VERSION = "latest"   # 404: no version lock for the account
}

npm install --save-dev "slnodejs@$VERSION"
npx slnodejs --help
```

{% endtab %}
{% endtabs %}

### Pinned version <a href="#pinned-version" id="pinned-version"></a>

```bash
npm install --save-dev slnodejs@6.2.101
```

Check the published versions with `npm view slnodejs versions`.

### Latest version <a href="#latest-version" id="latest-version"></a>

```bash
npm install --save-dev slnodejs@latest
```

## Check the installed version <a href="#check-the-installed-version" id="check-the-installed-version"></a>

```bash
npm ls slnodejs --depth=0
```

Include this version when you contact SeaLights support.

## Next step <a href="#next-step" id="next-step"></a>

[Generate a session ID](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/node.js-agent/generating-a-session-id.md).


---

# 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/node.js-agent/downloading-the-node.js-agent.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.
