whalewatch-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hemanth Reddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# whale-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server monitoring for Whale: a pinned OpenTelemetry Collector (contrib 0.161.0,
+sha256-checked) installed as a systemd service. Per host it reports:
+
+- CPU, memory, load, disk I/O, filesystems (used / size) and network
+- the busiest processes — CPU and memory once a minute; idle small ones are dropped,
+  except common databases, caches, queues and proxies (Redis, Postgres, RabbitMQ, nginx …)
+- Docker containers (CPU, memory, network) when `/var/run/docker.sock` exists
+- any log files you name, each under its own service in Logs
+- the OS, and on AWS the instance type, region, zone and instance id
+
+## Install
+
+    curl -fsSL https://app.whale.balajitech.xyz/agent/install.sh | sudo bash -s -- --key <ingest key>
+
+Or from npm, on a server with Node 16 or later:
+
+    npx whalewatch-agent --key <ingest key>
+
+It runs the same installer with the same options. Unless you're root it re-runs
+itself with sudo, so expect a password prompt.
+
+Linux (x86-64, ARM64) with systemd. `--help` lists the options: `--url` (self-hosted
+ingest), `--project`, `--host`, `--logs NAME=GLOB`, `--interval`, `--no-processes`,
+`--no-docker`, `--uninstall`. Re-running upgrades or reconfigures; a new config is
+validated before it replaces the running one.
+
+Files: `/opt/whale-agent` (collector), `/etc/whale-agent/config.yaml`,
+`/etc/whale-agent/agent.env` (the key, mode 600), `/var/lib/whale-agent` (log
+offsets). Its own logs: `journalctl -u whale-agent`.
+
+## Docker instead of systemd
+
+    bash install.sh --print-config --root-path /hostfs > config.yaml
+    WHALE_API_KEY=<ingest key> docker compose up -d
+
+## Notes
+
+- A host that also runs whalewatch is one row in Hosts (both report the OS hostname).
+  The agent already covers host metrics, so `WHALE_HOST_METRICS=0` in those services
+  avoids sending them twice.
+- Volume: about 45 datapoints per 30 s scrape plus a few per busy process per minute —
+  roughly 8M datapoints a month for a typical server.
+- Exports are gzipped OTLP/HTTP protobuf with the `x-api-key` header. Ingest must
+  decompress gzip (`whale-api/src/ingest/decompress.ts`); deploy that before agents.
+- Command lines never leave the machine (they can carry secrets); processes report
+  pid, executable name and owner.
+- Upgrading the collector: bump `OTELCOL_VERSION` and both SHA256s (from the release's
+  `.tar.gz.sha256` assets), check the config with `otelcol-contrib validate`, then
+  `pnpm sync:agent` to refresh the copy the web app serves
+  (`whale-webapp/public/agent/install.sh`).
+
+## AWS (CloudWatch + resource map)
+
+`aws/whale-aws.yaml` is a CloudFormation stack, deployed once per account and region:
+
+```sh
+curl -fsSLO https://app.whale.balajitech.xyz/agent/aws/whale-aws.yaml
+aws cloudformation deploy --stack-name whale-aws --template-file whale-aws.yaml \
+  --capabilities CAPABILITY_IAM --region ap-south-1 \
+  --parameter-overrides WhaleIngestKey=<ingest-key>
+```
+
+- **Metrics:** a CloudWatch metric stream (OpenTelemetry 1.0 format) → Kinesis Data Firehose → `POST /v1/aws/firehose` on the ingest, authenticated with the ingest key. Curated EC2, ALB/NLB, RDS, ElastiCache, Lambda and SQS metrics; edit `IncludeFilters` to change the set. Firehose needs an HTTPS endpoint — self-hosters set `WhaleIngestUrl`.
+- **Map:** a read-only Lambda lists load balancers, target groups (with target health), EC2, RDS, ElastiCache, Lambda (with event-source mappings) and SQS every `InventoryMinutes` (10), infers compute → database/cache links from security groups, and sends the snapshot to `/v1/metrics` as OTLP (`aws.resource`, `aws.relation`). Invoke the function once after deploying to see the map immediately.
+- **Cost:** AWS bills metric streams per metric update and Firehose per GB — the curated metric list keeps both small.
+- **Removal:** `aws cloudformation delete-stack --stack-name whale-aws`. The failed-delivery S3 bucket is kept (objects expire after 7 days); delete it by hand if you want it gone.

package/bin/whalewatch-agent.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+'use strict'
+// npx whalewatch-agent --key <ingest key> [options]
+//
+// Runs the bundled install.sh (the same script Whale serves at
+// /agent/install.sh) with the arguments given. Installing and uninstalling
+// need root, so a non-root run goes through sudo; --help and --print-config
+// run as the caller.
+
+const { spawnSync } = require('node:child_process')
+const path = require('node:path')
+
+const script = path.join(__dirname, '..', 'install.sh')
+const args = process.argv.slice(2)
+const asCaller = args.some((a) => a === '-h' || a === '--help' || a === '--print-config')
+
+// install.sh checks for root before it checks the OS, so say the real reason here.
+if (!asCaller && process.platform !== 'linux') {
+  console.error('whalewatch-agent: the installer is Linux-only; elsewhere run the collector in Docker (see --print-config)')
+  process.exit(1)
+}
+
+const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+let cmd = 'bash'
+let argv = [script, ...args]
+if (!asCaller && !isRoot) {
+  // sudo starts from a clean environment; carry the installer's own settings across.
+  const env = ['WHALE_API_KEY', 'WHALE_URL', 'WHALE_PROJECT', 'WHALE_HOST']
+    .filter((k) => process.env[k])
+    .map((k) => `${k}=${process.env[k]}`)
+  cmd = 'sudo'
+  argv = env.length > 0 ? ['env', ...env, 'bash', script, ...args] : ['bash', script, ...args]
+}
+
+const r = spawnSync(cmd, argv, { stdio: 'inherit' })
+if (r.error) {
+  const missing = r.error.code === 'ENOENT'
+  console.error(
+    missing && cmd === 'sudo'
+      ? 'whalewatch-agent: sudo not found; run this as root'
+      : `whalewatch-agent: ${missing ? `${cmd} not found` : r.error.message}`,
+  )
+  process.exit(1)
+}
+process.exit(r.status === null ? 1 : r.status)

package/docker-compose.yml

@@ -0,0 +1,22 @@
+# whale-agent in a container instead of a systemd service:
+#   bash install.sh --print-config --root-path /hostfs > config.yaml
+#   WHALE_API_KEY=<ingest key> docker compose up -d
+services:
+  whale-agent:
+    image: otel/opentelemetry-collector-contrib:0.161.0
+    command: ["--config=/etc/whale-agent/config.yaml"]
+    restart: unless-stopped
+    network_mode: host # host interfaces and hostname
+    pid: host # host processes
+    user: "0:0" # other users' /proc entries and the Docker socket
+    environment:
+      WHALE_API_KEY: ${WHALE_API_KEY:?set WHALE_API_KEY}
+      WHALE_URL: ${WHALE_URL:-https://ingest.whale.balajitech.xyz}
+      OTEL_RESOURCE_ATTRIBUTES: service.name=whale-agent,whale.project=${WHALE_PROJECT:-default}
+    volumes:
+      - ./config.yaml:/etc/whale-agent/config.yaml:ro
+      - /:/hostfs:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - whale-agent-state:/var/lib/whale-agent
+volumes:
+  whale-agent-state:

package/install.sh

@@ -0,0 +1,467 @@
+#!/usr/bin/env bash
+# whale-agent — server monitoring for Whale.
+#
+# Installs a pinned OpenTelemetry Collector (contrib build) as a systemd service
+# that sends this machine's CPU, memory, load, disks, filesystems and network,
+# its busiest processes, Docker containers and any log files you name to
+# Whale's OTLP ingest. On EC2 the instance type, region and AZ come along.
+#
+#   curl -fsSL https://<your-whale>/agent/install.sh | sudo bash -s -- --key <ingest key>
+#
+# Re-run it to upgrade or change settings; --uninstall removes everything.
+# --print-config prints the collector config for running it in Docker instead.
+#
+# Source of truth: whale-agent/install.sh. The copy served at /agent/install.sh
+# (whale-webapp/public/agent/) is refreshed with `pnpm sync:agent`.
+#
+# Everything runs from main() on the last line, so a truncated download
+# executes nothing.
+
+set -euo pipefail
+
+OTELCOL_VERSION="0.161.0"
+SHA256_AMD64="778c689efa681ff6e4722ce9f66b9b7f57c3ba009ab2e2b43dc2e0315862c731"
+SHA256_ARM64="cd5de93213a0dbb90e4998b3b9e4e15ed691ec635cf7cf4147f95799fb16b676"
+DEFAULT_URL="https://ingest.whale.balajitech.xyz" # = whale-node DEFAULT_INGEST_URL
+
+PREFIX="/opt/whale-agent"
+CONF_DIR="/etc/whale-agent"
+STATE_DIR="/var/lib/whale-agent"
+UNIT_FILE="/etc/systemd/system/whale-agent.service"
+
+# Characters allowed in a log glob. No quotes, spaces or commas: commas separate
+# globs, and everything lands inside single-quoted YAML.
+GLOB_RE='/[A-Za-z0-9._/*?@+~-]+'
+
+die() { echo "whale-agent: $*" >&2; exit 1; }
+say() { echo "whale-agent: $*" >&2; }
+
+usage() {
+  cat <<'EOF'
+whale-agent — ships this server's metrics and logs to Whale.
+
+  curl -fsSL https://<your-whale>/agent/install.sh | sudo bash -s -- --key <ingest key> [options]
+
+  --key KEY         Ingest key (Settings → API keys). Or set WHALE_API_KEY.
+  --url URL         Ingest URL. Default: Whale's hosted ingest. Self-hosters must set it.
+  --project SLUG    Project to file this host under (a project-scoped key wins).
+  --host NAME       Report this name instead of the OS hostname.
+  --logs SPEC       Tail log files as a service: NAME=GLOB[,GLOB...]. Repeatable.
+                    e.g. --logs nginx=/var/log/nginx/*.log --logs api=/srv/api/*.log
+  --interval SECS   Host metrics interval, 10-3600 (default 30).
+  --no-processes    Don't report per-process CPU and memory.
+  --docker          Report containers even if /var/run/docker.sock isn't here yet.
+  --no-docker       Never report containers.
+  --root-path PATH  Where the host's / is mounted when running in a container.
+  --print-config    Print the collector config and exit (Docker / Kubernetes).
+  --uninstall       Stop the agent and remove everything it installed.
+EOF
+}
+
+parse_args() {
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --key | --url | --project | --host | --logs | --interval | --root-path)
+        [ $# -ge 2 ] || die "$1 needs a value"
+        case "$1" in
+          --key) KEY="$2" ;;
+          --url) URL="$2" ;;
+          --project) PROJECT="$2" ;;
+          --host) HOST_NAME="$2" ;;
+          --logs) LOGS="${LOGS}${2}"$'\n' ;;
+          --interval) INTERVAL="$2" ;;
+          --root-path) ROOT_PATH="$2" ;;
+        esac
+        shift 2
+        ;;
+      --no-processes) PROCESSES=0; shift ;;
+      --docker) DOCKER=1; shift ;;
+      --no-docker) DOCKER=0; shift ;;
+      --print-config) MODE=print; shift ;;
+      --uninstall) MODE=uninstall; shift ;;
+      -h | --help) usage; exit 0 ;;
+      *) die "unknown option: $1 (try --help)" ;;
+    esac
+  done
+}
+
+matches() { printf '%s' "$1" | grep -Eq "$2"; }
+
+validate_common() {
+  URL="${URL%/}"
+  matches "$URL" '^https?://[A-Za-z0-9.:_/-]+$' || die "--url must look like https://ingest.example.com"
+  matches "$PROJECT" '^[A-Za-z0-9._-]{1,64}$' || die "--project may only use letters, digits, . _ -"
+  if [ -n "$HOST_NAME" ]; then
+    matches "$HOST_NAME" '^[A-Za-z0-9._-]{1,253}$' || die "--host may only use letters, digits, . _ -"
+  fi
+  if ! matches "$INTERVAL" '^[0-9]+$' || [ "$INTERVAL" -lt 10 ] || [ "$INTERVAL" -gt 3600 ]; then
+    die "--interval must be 10-3600 seconds"
+  fi
+  if [ -n "$ROOT_PATH" ]; then
+    matches "$ROOT_PATH" '^/[A-Za-z0-9._/-]*$' || die "--root-path must be an absolute path"
+    ROOT_PATH="${ROOT_PATH%/}"
+  fi
+  local spec name
+  while IFS= read -r spec; do
+    [ -n "$spec" ] || continue
+    name="${spec%%=*}"
+    [ "$name" != "$spec" ] || die "--logs expects NAME=GLOB, got: $spec"
+    matches "$name" '^[a-z0-9][a-z0-9_-]{0,62}$' || die "log name must be lowercase letters, digits, _ -: $name"
+    matches "${spec#*=}" "^${GLOB_RE}(,${GLOB_RE})*\$" || die "log globs must be absolute paths without spaces or quotes: ${spec#*=}"
+  done <<EOF
+$LOGS
+EOF
+}
+
+validate_key() {
+  [ -n "$KEY" ] || die "an ingest key is required: --key <key> (create one under Settings → API keys)"
+  matches "$KEY" '^[A-Za-z0-9._:+/=-]{8,256}$' || die "that doesn't look like an ingest key"
+}
+
+docker_on() {
+  [ "$DOCKER" = 1 ] && return 0
+  [ "$DOCKER" = auto ] && [ -S /var/run/docker.sock ]
+}
+
+# One file_log receiver per --logs NAME, so each source files under its own
+# service name in Whale's Logs tab.
+log_receivers() {
+  local spec name globs out="" g sep
+  set -f
+  while IFS= read -r spec; do
+    [ -n "$spec" ] || continue
+    name="${spec%%=*}"
+    globs="${spec#*=}"
+    out="${out}  file_log/${name}:"$'\n'"    include: ["
+    sep=""
+    # set -f above: the globs must reach the collector unexpanded.
+    for g in $(printf '%s' "$globs" | tr ',' ' '); do
+      out="${out}${sep}'${ROOT_PATH}${g}'"
+      sep=", "
+    done
+    out="${out}]"$'\n'"    start_at: end"$'\n'"    storage: file_storage"$'\n'
+    out="${out}    resource:"$'\n'"      service.name: ${name}"$'\n'
+  done <<EOF
+$LOGS
+EOF
+  set +f
+  printf '%s' "$out"
+}
+
+log_receiver_names() {
+  local spec names=""
+  while IFS= read -r spec; do
+    [ -n "$spec" ] || continue
+    names="${names:+$names, }file_log/${spec%%=*}"
+  done <<EOF
+$LOGS
+EOF
+  printf '%s' "$names"
+}
+
+# Processes reported however idle (see filter/small_processes). An RE2 regex
+# over the executable name; [.] keeps backslashes out of the OTTL string.
+KEEP_PROCESSES='^(redis-server|valkey-server|keydb-server|memcached|beam[.]smp|nats-server|postgres|postmaster|mysqld|mariadbd|mongod|mongos|clickhouse-server|nginx|haproxy|caddy|traefik|envoy|etcd|consul|minio)$'
+
+gen_config() {
+  local root_line="" metrics_receivers="host_metrics" logs_names process_block="" docker_block="" logs_pipeline=""
+  if [ -n "$ROOT_PATH" ]; then root_line="    root_path: ${ROOT_PATH}"; fi
+
+  if [ "$PROCESSES" = 1 ]; then
+    metrics_receivers="${metrics_receivers}, host_metrics/processes"
+    process_block="
+  # Per-process CPU and memory, once a minute. Only the two metrics the Hosts
+  # page shows, and filter/small_processes below drops idle, small processes —
+  # a busy server has hundreds and they would dominate the bill otherwise.
+  # Command lines stay on the machine: they can carry secrets.
+  host_metrics/processes:
+    collection_interval: 60s
+${root_line}
+    scrapers:
+      process:
+        mute_process_all_errors: true
+        resource_attributes:
+          process.command_line: { enabled: false }
+          process.executable.path: { enabled: false }
+        metrics:
+          process.cpu.time: { enabled: false }
+          process.cpu.utilization: { enabled: true }
+          process.disk.io: { enabled: false }
+          process.memory.virtual: { enabled: false }
+"
+  fi
+
+  if docker_on; then
+    metrics_receivers="${metrics_receivers}, docker_stats"
+    docker_block="
+  # Containers: CPU (docker-stats style — 100% is one core), memory, network.
+  docker_stats:
+    endpoint: unix:///var/run/docker.sock
+    collection_interval: ${INTERVAL}s
+    metrics:
+      container.blockio.io_service_bytes_recursive: { enabled: false }
+      container.cpu.usage.kernelmode: { enabled: false }
+      container.cpu.usage.total: { enabled: false }
+      container.cpu.usage.usermode: { enabled: false }
+      container.memory.file: { enabled: false }
+      container.memory.total_cache: { enabled: false }
+      container.memory.usage.limit: { enabled: false }
+      container.network.io.usage.rx_dropped: { enabled: false }
+      container.network.io.usage.tx_dropped: { enabled: false }
+"
+  fi
+
+  logs_names="$(log_receiver_names)"
+  if [ -n "$logs_names" ]; then
+    logs_pipeline="    logs:
+      receivers: [${logs_names}]
+      processors: [memory_limiter, resource_detection, batch]
+      exporters: [otlp_http]"
+  fi
+
+  cat <<EOF
+# whale-agent config — generated by install.sh for otelcol-contrib ${OTELCOL_VERSION}.
+# Re-run the installer to change it; hand edits are overwritten.
+
+extensions:
+  file_storage:
+    directory: ${STATE_DIR}
+    create_directory: true
+
+receivers:
+  host_metrics:
+    collection_interval: ${INTERVAL}s
+${root_line}
+    scrapers:
+      cpu:
+        metrics:
+          system.cpu.time: { enabled: false }
+          system.cpu.utilization: { enabled: true }
+          system.cpu.logical.count: { enabled: true }
+      load: {}
+      memory:
+        metrics:
+          system.memory.utilization: { enabled: true }
+      disk:
+        exclude:
+          devices: ['^(loop|ram|sr|fd|zram|nbd|dm-)[0-9]*$']
+          match_type: regexp
+        metrics:
+          system.disk.io_time: { enabled: false }
+          system.disk.merged: { enabled: false }
+          system.disk.operation_time: { enabled: false }
+          system.disk.operations: { enabled: false }
+          system.disk.pending_operations: { enabled: false }
+          system.disk.weighted_io_time: { enabled: false }
+      filesystem:
+        exclude_fs_types:
+          fs_types: [autofs, binfmt_misc, bpf, cgroup, cgroup2, configfs, debugfs, devpts, devtmpfs, efivarfs, fuse.lxcfs, fusectl, hugetlbfs, mqueue, nsfs, overlay, proc, pstore, rpc_pipefs, securityfs, selinuxfs, squashfs, sysfs, tmpfs, tracefs]
+          match_type: strict
+        exclude_mount_points:
+          mount_points: ['^/(dev|proc|sys|run|snap|var/lib/docker|var/lib/containerd|var/lib/kubelet)(/|$)']
+          match_type: regexp
+        metrics:
+          system.filesystem.inodes.usage: { enabled: false }
+          system.filesystem.utilization: { enabled: true }
+      network:
+        exclude:
+          interfaces: ['^(lo|docker[0-9]*|veth.*|br-.*|cni.*|flannel.*|cali.*|virbr.*)$']
+          match_type: regexp
+        metrics:
+          system.network.connections: { enabled: false }
+          system.network.dropped: { enabled: false }
+          system.network.errors: { enabled: false }
+          system.network.packets: { enabled: false }
+      # system.uptime also carries the host's OS / cloud details into Whale.
+      system:
+        metrics:
+          system.uptime: { enabled: true }
+${process_block}${docker_block}$(log_receivers)
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+    spike_limit_mib: 64
+  # host.name comes from the OS hostname — the same value whalewatch reports —
+  # so a host running both lines up as one row. ec2 adds instance type,
+  # region and AZ on AWS and does nothing elsewhere.
+  resource_detection:
+    detectors: [env, system, ec2]
+    timeout: 5s
+    override: false
+    system:
+      hostname_sources: [os]
+      resource_attributes:
+        host.arch: { enabled: true }
+        os.description: { enabled: true }
+  # Databases, caches, queues and proxies always pass, however idle: a quiet
+  # Redis is still one someone watches (Infrastructure matches services by
+  # process name, so a dropped idle daemon would read as stopped).
+  filter/small_processes:
+    error_mode: ignore
+    metrics:
+      datapoint:
+        - 'metric.name == "process.cpu.utilization" and value_double < 0.005 and not IsMatch(resource.attributes["process.executable.name"], "${KEEP_PROCESSES}")'
+        - 'metric.name == "process.memory.usage" and value_int < 52428800 and not IsMatch(resource.attributes["process.executable.name"], "${KEEP_PROCESSES}")'
+  batch:
+    timeout: 10s
+
+exporters:
+  otlp_http:
+    endpoint: \${env:WHALE_URL}
+    headers:
+      x-api-key: \${env:WHALE_API_KEY}
+    compression: gzip
+
+service:
+  extensions: [file_storage]
+  telemetry:
+    logs:
+      level: warn
+    metrics:
+      level: none
+  pipelines:
+    metrics:
+      receivers: [${metrics_receivers}]
+      processors: [memory_limiter, resource_detection, filter/small_processes, batch]
+      exporters: [otlp_http]
+${logs_pipeline}
+EOF
+}
+
+write_env() {
+  local attrs="service.name=whale-agent,whale.project=${PROJECT}"
+  if [ -n "$HOST_NAME" ]; then attrs="${attrs},host.name=${HOST_NAME}"; fi
+  printf 'WHALE_API_KEY="%s"\nWHALE_URL="%s"\nOTEL_RESOURCE_ATTRIBUTES="%s"\n' "$KEY" "$URL" "$attrs"
+}
+
+write_unit() {
+  cat <<EOF
+[Unit]
+Description=Whale agent (OpenTelemetry Collector ${OTELCOL_VERSION})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+# root: other users' /proc entries and the Docker socket need it.
+EnvironmentFile=${CONF_DIR}/agent.env
+ExecStart=${PREFIX}/otelcol-contrib --config=${CONF_DIR}/config.yaml
+Restart=always
+RestartSec=10
+MemoryMax=512M
+Nice=10
+
+[Install]
+WantedBy=multi-user.target
+EOF
+}
+
+# A 401 here beats a silently rejected agent.
+preflight() {
+  local code
+  code="$(curl -s -o /dev/null -w '%{http_code}' -m 15 -X POST "${URL}/v1/metrics" \
+    -H "x-api-key: ${KEY}" -H 'content-type: application/json' \
+    --data '{"resourceMetrics":[]}' || true)"
+  case "$code" in
+    2??) ;;
+    401 | 403) die "${URL} rejected the key (HTTP ${code}) — check --key, and --url if you self-host" ;;
+    *) say "warning: couldn't confirm ${URL} (HTTP ${code:-no response}); installing anyway" ;;
+  esac
+}
+
+install_agent() {
+  local arch sum tgz tmp
+  [ "$(id -u)" -eq 0 ] || die "run as root: curl ... | sudo bash -s -- --key <key>"
+  [ "$(uname -s)" = Linux ] || die "the installer is Linux-only; elsewhere run the collector in Docker (see --print-config)"
+  command -v systemctl >/dev/null 2>&1 || die "systemd not found; use --print-config and run the collector in Docker"
+  for c in curl tar sha256sum; do command -v "$c" >/dev/null 2>&1 || die "$c is required"; done
+  case "$(uname -m)" in
+    x86_64 | amd64) arch=amd64; sum="$SHA256_AMD64" ;;
+    aarch64 | arm64) arch=arm64; sum="$SHA256_ARM64" ;;
+    *) die "unsupported CPU: $(uname -m)" ;;
+  esac
+
+  preflight
+  mkdir -p "$PREFIX" "$CONF_DIR" "$STATE_DIR"
+
+  if [ "$(cat "$PREFIX/VERSION" 2>/dev/null || true)" != "$OTELCOL_VERSION" ]; then
+    tmp="$(mktemp -d)"
+    WORK="$tmp"
+    tgz="otelcol-contrib_${OTELCOL_VERSION}_linux_${arch}.tar.gz"
+    say "downloading OpenTelemetry Collector ${OTELCOL_VERSION} (${arch}, ~110 MB)"
+    curl -fsSL --retry 3 -o "$tmp/$tgz" \
+      "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTELCOL_VERSION}/${tgz}"
+    echo "${sum}  $tmp/$tgz" | sha256sum -c - >/dev/null 2>&1 || die "checksum mismatch on ${tgz} — not installing it"
+    tar -xzf "$tmp/$tgz" -C "$tmp" otelcol-contrib
+    install -m 0755 "$tmp/otelcol-contrib" "$PREFIX/otelcol-contrib.new"
+    mv -f "$PREFIX/otelcol-contrib.new" "$PREFIX/otelcol-contrib"
+    echo "$OTELCOL_VERSION" >"$PREFIX/VERSION"
+  fi
+
+  # Write next to the live files and validate before swapping them in, so a
+  # bad flag never takes down a running agent.
+  (umask 077 && write_env >"$CONF_DIR/agent.env.new")
+  gen_config >"$CONF_DIR/config.yaml.new"
+  if ! (set -a && . "$CONF_DIR/agent.env.new" && set +a &&
+    "$PREFIX/otelcol-contrib" validate --config="$CONF_DIR/config.yaml.new"); then
+    rm -f "$CONF_DIR/agent.env.new" "$CONF_DIR/config.yaml.new"
+    die "the generated config didn't validate — nothing changed"
+  fi
+  mv -f "$CONF_DIR/agent.env.new" "$CONF_DIR/agent.env"
+  mv -f "$CONF_DIR/config.yaml.new" "$CONF_DIR/config.yaml"
+  chmod 600 "$CONF_DIR/agent.env"
+  chmod 644 "$CONF_DIR/config.yaml"
+
+  write_unit >"$UNIT_FILE"
+  systemctl daemon-reload
+  systemctl enable whale-agent >/dev/null 2>&1
+  systemctl restart whale-agent
+  sleep 5
+  if ! systemctl is-active --quiet whale-agent; then
+    journalctl -u whale-agent -n 30 --no-pager >&2 || true
+    die "the service didn't stay up — log above"
+  fi
+  say "running. $(hostname) shows up under Hosts within a minute."
+  if [ -n "$(log_receiver_names)" ]; then say "tailing new lines of: $(log_receiver_names)"; fi
+  say "config: ${CONF_DIR}/config.yaml · logs: journalctl -u whale-agent"
+}
+
+uninstall_agent() {
+  [ "$(id -u)" -eq 0 ] || die "run as root"
+  systemctl disable --now whale-agent >/dev/null 2>&1 || true
+  rm -f "$UNIT_FILE"
+  systemctl daemon-reload >/dev/null 2>&1 || true
+  rm -rf "$PREFIX" "$CONF_DIR" "$STATE_DIR"
+  say "removed."
+}
+
+main() {
+  WORK=""
+  trap '[ -z "$WORK" ] || rm -rf "$WORK"' EXIT
+  KEY="${WHALE_API_KEY:-}"
+  URL="${WHALE_URL:-$DEFAULT_URL}"
+  PROJECT="${WHALE_PROJECT:-default}"
+  HOST_NAME="${WHALE_HOST:-}"
+  INTERVAL=30
+  PROCESSES=1
+  DOCKER=auto
+  ROOT_PATH=""
+  LOGS=""
+  MODE=install
+  parse_args "$@"
+  case "$MODE" in
+    uninstall) uninstall_agent ;;
+    print)
+      validate_common
+      gen_config
+      say "run it with WHALE_API_KEY, WHALE_URL and OTEL_RESOURCE_ATTRIBUTES=service.name=whale-agent,whale.project=${PROJECT} set"
+      ;;
+    install)
+      validate_common
+      validate_key
+      install_agent
+      ;;
+  esac
+}
+
+main "$@"

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "whalewatch-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Server monitoring for Whale. Installs a pinned OpenTelemetry Collector as a systemd service that ships this server's metrics, processes, containers and logs to Whale.",
+  "license": "MIT",
+  "homepage": "https://whale.balajitech.xyz/docs/",
+  "bin": {
+    "whalewatch-agent": "bin/whalewatch-agent.js"
+  },
+  "files": [
+    "bin",
+    "install.sh",
+    "docker-compose.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "observability",
+    "monitoring",
+    "opentelemetry",
+    "otel",
+    "collector",
+    "agent",
+    "metrics",
+    "logs",
+    "systemd",
+    "whale"
+  ]
+}