Downloading the Node.js Agent

The SeaLights Node.js agent is published in the npm registry and installed with npm. There is no separate binary to download.

Using an internal artifact repository? If your organization mirrors npm packages through Artifactory, Nexus, or another private registry, install slnodejs from that registry instead. The package name and version syntax stay the same.

Choosing an installation strategy

There are two ways to control which version to install:

Strategy	When to use
Latest	Quick start, dev environments, and POCs
Specific version ⭐	Production pipelines — resolve from API or pin explicitly

Strategy 1: Install the latest version

This installs the newest published release at runtime. Use it when you want the latest features and can tolerate version changes between runs.

Bash

echo "[SeaLights] Installing Node.js agent (latest)..."
npm install slnodejs@latest
npm ls slnodejs --depth=0

GitHub Actions

- name: Install SeaLights Node.js Agent (latest)
  run: |
    echo "[SeaLights] Installing Node.js agent (latest)..."
    npm install slnodejs@latest
    npm ls slnodejs --depth=0

PowerShell

Write-Host "[SeaLights] Installing Node.js agent (latest)..."
npm install slnodejs@latest
npm ls slnodejs --depth=0

Azure DevOps

- script: |
    echo "[SeaLights] Installing Node.js agent (latest)..."
    npm install slnodejs@latest
    npm ls slnodejs --depth=0
  displayName: Install SeaLights Node.js Agent (latest)

Strategy 2: Specific version (recommended)

Use this strategy in production pipelines. It gives you stable installs and controlled upgrades.

Choose one of these approaches:

• Installer utility — simplest path. It resolves and installs the approved version for you.
• Explicit version management — no extra package. You control the API call and npm install flow directly.

Approach 1: Installer utility

Use this when you want the approved version from the Dashboard without managing the resolution logic yourself.

To run the installer, provide your SeaLights Agent Token either in sltoken.txt at the project root or as the SL_TOKEN environment variable.

Bash

# Retrieve the SeaLights Agent Token from your vault or secret manager
export SL_TOKEN=$(vault kv get -field=token secret/sealights)

echo "[SeaLights] Installing Node.js agent via installer..."
npm install slnodejs-installer
npm ls slnodejs --depth=0

GitHub Actions

- name: Install SeaLights Node.js Agent via installer
  run: |
    echo "[SeaLights] Installing Node.js agent via installer..."
    npm install slnodejs-installer
    npm ls slnodejs --depth=0
  env:
    SL_TOKEN: ${{ secrets.SL_TOKEN }}

PowerShell

# Retrieve the SeaLights Agent Token from your vault or secret manager
$Env:SL_TOKEN = (vault kv get -field=token secret/sealights)

Write-Host "[SeaLights] Installing Node.js agent via installer..."
npm install slnodejs-installer
npm ls slnodejs --depth=0

Azure DevOps

- script: |
    echo "[SeaLights] Installing Node.js agent via installer..."
    npm install slnodejs-installer
    npm ls slnodejs --depth=0
  displayName: Install SeaLights Node.js Agent via installer
  env:
    SL_TOKEN: $(SL_TOKEN)

The installer authenticates with your token, resolves the approved version from the Dashboard, installs that exact slnodejs release, and writes install.log for troubleshooting.

Approach 2: Explicit version management

Use this when you do not want to install an additional package or when you want full control over the commands in your pipeline.

Tip: Leave SL_AGENT_VERSION empty in the snippets below to resolve the approved version from the Dashboard automatically.

• When the approved version changes, pipelines pick it up on the next run.
• When troubleshooting, set it to latest or pin it to X.Y.Z.

API endpoint

GET https://{DOMAIN}/api/v2/agents/slnodejs/recommended/version

• Authentication: Authorization: Bearer <your-agent-token>
• Response: JSON object with a version field, for example {"version": "4.2.1"}

Bash

SL_DOMAIN="<your-custom-domain>.sealights.co"   # Replace with your account domain
SL_TOKEN=$(cat ./sltoken.txt)                   # Or inject via secret/env var
SL_AGENT_VERSION=""                             # "" = resolve from API, "latest" = newest, "X.Y.Z" = pin

PKG_SPEC="slnodejs"
if [ "${SL_AGENT_VERSION}" != "latest" ]; then
  if [ -z "${SL_AGENT_VERSION}" ]; then
    SL_AGENT_VERSION=$(curl -sSf \
      -H "Authorization: Bearer ${SL_TOKEN}" \
      "https://${SL_DOMAIN}/api/v2/agents/slnodejs/recommended/version" \
      | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
  fi
  PKG_SPEC="${PKG_SPEC}@${SL_AGENT_VERSION}"
fi

npm install "${PKG_SPEC}"
npm ls slnodejs --depth=0

GitHub Actions

- name: Install SeaLights Node.js Agent
  env:
    SL_DOMAIN: "<your-custom-domain>.sealights.co"   # Replace with your account domain
    SL_TOKEN: ${{ secrets.SL_TOKEN }}
    SL_AGENT_VERSION: ""   # "" = resolve from API, "latest" = newest, "X.Y.Z" = pin
  run: |
    PKG_SPEC="slnodejs"
    if [ "${SL_AGENT_VERSION}" != "latest" ]; then
      if [ -z "${SL_AGENT_VERSION}" ]; then
        SL_AGENT_VERSION=$(curl -sSf \
          -H "Authorization: Bearer ${SL_TOKEN}" \
          "https://${SL_DOMAIN}/api/v2/agents/slnodejs/recommended/version" \
          | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
      fi
      PKG_SPEC="${PKG_SPEC}@${SL_AGENT_VERSION}"
    fi
    npm install "${PKG_SPEC}"
    npm ls slnodejs --depth=0

PowerShell

$SL_DOMAIN = "<your-custom-domain>.sealights.co"   # Replace with your account domain
$SL_TOKEN = Get-Content ./sltoken.txt              # Or inject via secret/env var
$SL_AGENT_VERSION = ""                             # "" = resolve from API, "latest" = newest, "X.Y.Z" = pin

$PKG_SPEC = "slnodejs"
if ($SL_AGENT_VERSION -ne "latest") {
  if ([string]::IsNullOrEmpty($SL_AGENT_VERSION)) {
    $headers = @{ "Authorization" = "Bearer $SL_TOKEN" }
    $SL_AGENT_VERSION = (Invoke-RestMethod `
      -Uri "https://$SL_DOMAIN/api/v2/agents/slnodejs/recommended/version" `
      -Headers $headers -Method Get).version
  }
  $PKG_SPEC = "$PKG_SPEC@$SL_AGENT_VERSION"
}

npm install $PKG_SPEC
npm ls slnodejs --depth=0

Azure DevOps

- script: |
    PKG_SPEC="slnodejs"
    if [ "${SL_AGENT_VERSION}" != "latest" ]; then
      if [ -z "${SL_AGENT_VERSION}" ]; then
        SL_AGENT_VERSION=$(curl -sSf \
          -H "Authorization: Bearer ${SL_TOKEN}" \
          "https://${SL_DOMAIN}/api/v2/agents/slnodejs/recommended/version" \
          | grep -o '"version":"[^"]*"' | cut -d'"' -f4)
      fi
      PKG_SPEC="${PKG_SPEC}@${SL_AGENT_VERSION}"
    fi
    npm install "${PKG_SPEC}"
    npm ls slnodejs --depth=0
  displayName: Install SeaLights Node.js Agent
  env:
    SL_DOMAIN: "<your-custom-domain>.sealights.co"
    SL_TOKEN: $(SL_TOKEN)
    SL_AGENT_VERSION: ""