Skip to content

About

The data collection engine for the Sentinel ecosystem. Connects to Discord as a user account, logs behavioral data on tracked targets, and exposes everything through a local REST/SSE API.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

ย 

History

101 Commits

Folders and files

Repository files navigation

Sentinel Logo

๐Ÿ”ง sentinel-selfbot

The data collection engine for the Sentinel ecosystem

Connects to Discord as a user account, logs behavioral data on tracked targets, and exposes everything through a local REST/SSE API โ€” with AI-powered analysis and real-time event-driven presence tracking.

Part of the Sentinel project.

GitHub stars GitHub forks
License Project Status Self-Hosted Node version AI Ready


๐Ÿง  What It Does

Add a user ID. From that moment, the selfbot records everything it can observe:

  • ๐ŸŸข Online / offline presence โ€” real-time, event-driven, including which device (desktop / mobile / web)
  • ๐ŸŽฎ Games & activities โ€” what they play, for how long, with rich metadata
  • ๐ŸŽต Spotify listening โ€” tracks, albums, artists, timestamps
  • ๐Ÿ–ฅ๏ธ Custom status changes โ€” every status text and emoji set or cleared
  • ๐ŸŽ™๏ธ Voice channel movements โ€” joins, leaves, moves, mute/deafen state, co-participants
  • ๐Ÿ’ฌ Messages โ€” sent, edited, deleted (content preserved before deletion)
  • ๐Ÿ‘ป Ghost typing โ€” started typing but never sent
  • ๐Ÿ–ผ๏ธ Profile changes โ€” username, display name, avatar, bio, connected accounts (Twitter, Steam, etc.)
  • ๐Ÿ”” Platform switches โ€” detects when a target moves from desktop to mobile mid-session
  • ๐ŸŒ Per-target timezone โ€” every hour/day-of-week analyser (sleep schedule, routine heatmap, behavioral baselines, UNUSUAL_HOUR/COMES_ONLINE after_hour alerts) runs in the target's own IANA timezone, not the host server's. Set with $tz <@user> Area/City.
  • ๐Ÿšฆ Clean onboarding pipeline โ€” newly added targets go through an explicit bootstrap phase (initial profile + presence + activity fetches) during which alerts and anomaly surfacing are suppressed. Operational mode flips on automatically after the first successful profile fetch โ€” no more "joined an hour ago, already showing 3 phantom PROFILE_UPDATE anomalies." Backstop sweep force-completes anything stuck for >30 min.
  • ๐Ÿ–ฅ๏ธ Self-commands โ€” manage tracking from any Discord channel with instant trace deletion

AI-powered intelligence (optional):

  • ๐Ÿท๏ธ Message categorization โ€” every message auto-tagged (gaming, music, venting, humor, etc.)
  • ๐ŸŒ AI social graph โ€” relationship classification with confidence scores (close friend, romantic interest, group buddyโ€ฆ)
  • ๐Ÿ“ฐ Daily intelligence briefs โ€” morning summary with anomalies and behavioral changes
  • ๐Ÿ”„ Historical message backfill โ€” fills in the past automatically when you start tracking someone
  • ๐Ÿ”” Smarter alerts โ€” digest mode, fatigue prevention, instant Discord webhooks

All data lives in a local SQLite database. Optional Supabase sync gives a cloud mirror for backup or cross-device access.


โšก How Presence Tracking Works

Sentinel uses Discord's op 14 (GUILD_SUBSCRIBE) gateway opcode with a members array to subscribe to real-time presence events for specific users. When a tracked target changes status โ€” online, idle, DND, or offline โ€” Discord pushes the change immediately as a PRESENCE_UPDATE event. No polling delay.

Key properties:

  • Offline detection is instant โ€” no waiting for a poll cycle
  • Subscriptions refresh automatically โ€” re-sent on every reconnect, session resume, and every 4 minutes in case of silent expiry
  • New targets subscribe within 5 seconds of being added via the API or self-command
  • Platform switches tracked independently โ€” moving from desktop to mobile without a status change is its own event

Requires at least one mutual Discord server between the selfbot account and the target.

โ†’ Technical deep-dive: docs/presence-tracking.md


๐Ÿ–ฅ๏ธ Self-Command System

Type commands in any Discord channel (including your own private servers). The triggering message is deleted immediately before anyone else sees it. Feedback appears as a temporary message that self-deletes after a few seconds โ€” no permanent trace in the channel.

Command Description
$add <@user> Add a tracking target
$remove <@user> Remove a target (deletes all history)
$pause <@user> Suspend tracking without deleting history
$resume <@user> Re-activate a paused target
$label <@user> <text> Set a display label for a target
$note <@user> <text> Append a timestamped note to a target (capped at 4000 chars cumulative)
$tz <@user> [Area/City] Set the target's IANA timezone (defaults to UTC). Omit the argument to show current.
$status <@user> Current presence, platform & activities
$seen <@user> When the target was last online
$uptime <@user> Today's total active time with progress bar
$streak <@user> How long in current status uninterrupted
$history <@user> [n] Last N presence transitions with timestamps
$pattern <@user> 30-day hourly activity heatmap (โ–โ–‚โ–ƒโ–„โ–…โ–†โ–‡โ–ˆ)
$list All active targets with live status
$ping REST & gateway heartbeat latency check
$stats System stats (targets, events, DB size, uptime)
$reload Reload alert rules & runtime config live
$help Full command reference

All commands accept <@mention> or a raw Discord user ID snowflake.

โ†’ Full reference: docs/commands.md


๐Ÿค– AI-Powered Features

๐ŸŒ AI Social Graph Analysis

Uses an LLM to examine the texture of interactions โ€” sentiment, reply speed, topic clustering, initiation balance, voice co-presence times โ€” and classifies relationships:

close friend, romantic interest, group friend, conflict relationship, server contact, and more.

Each classification includes a confidence score and a relationship timeline showing how the connection has evolved over weeks.

๐Ÿท๏ธ Message Categorization

Messages are automatically tagged with categories like gaming, music, venting, humor, planning, questions, etc. Works by batching recent messages through a lightweight LLM call, configurable batch size.

๐Ÿ“ฐ Automated Daily Briefs

Every morning at your configured time, Sentinel generates a plain-text summary per active target:

  • Presence duration and devices used
  • Games and music played
  • Message counts (including deleted / ghost typing)
  • Voice channel activity
  • Profile changes
  • Anomaly flags

๐Ÿ”„ Historical Message Backfill

When you add a target, Sentinel walks backwards through every shared channel to fill in past messages. Configurable depth (max days, max messages per channel). The API exposes live progress per channel.

๐Ÿ”” Alert System

  • 14 alert types โ€” comes online, goes offline, starts activity, joins voice, sends message, ghost types, profile change, unusual hour, new game, keyword mention, and more
  • Per-target timezone-aware โ€” UNUSUAL_HOUR and COMES_ONLINE after_hour match against each target's own clock, not the host server's
  • Digest mode โ€” batch alerts into a single SSE event every N minutes for the dashboard live feed (immediate webhook delivery is unaffected, no double-fire)
  • Fatigue detection โ€” auto-suppress rules that fire too often (configurable threshold)
  • Composite conditions โ€” combine multiple conditions in one rule; rule type + composite shape are validated server-side at create time (bad input returns HTTP 400)
  • Discord webhooks โ€” normal alerts and critical system errors routed to separate channels

Some Screenshots

Sentinel logging multiple targets' messages across servers:

Selfbot collecting data

Sentinel running AI Social Relation/Graph Analysis:

AI social graph analysis

View more: github.com/Privex-chat/sentinel


โšก Quick Start

git clone https://github.com/Privex-chat/sentinel-selfbot.git
cd sentinel-selfbot
npm install
cp .env.example .env
# Edit .env โ€” set DISCORD_TOKEN, API_AUTH_TOKEN, and optionally AI provider
npm run build && npm start

Then connect the plugin or web panel to http://localhost:48923.

Full setup guide: docs/selfbot.md


โš™๏ธ Configuration

Click to expand the full .env reference
# โ”€โ”€ Core (requires restart to change) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
DISCORD_TOKEN=your_account_token_here
API_PORT=48923
API_AUTH_TOKEN=generate_a_random_string_here
DB_PATH=./data/sentinel.db
LOG_LEVEL=info

# RANDOM_JITTER=true โ€” adds ยฑ20% jitter to polling intervals so requests
# don't fire on a predictable schedule. Also randomises the browser/OS
# fingerprint sent in the Discord gateway IDENTIFY and REST headers.
# Recommended for Railway / cloud deployments.
RANDOM_JITTER=false

# โ”€โ”€ API hardening (requires restart) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# Comma-separated CORS allowlist. "*" reflects any origin (use only if you
# front the API yourself with another auth layer). Unset = default allowlist
# (hosted Vercel panel + localhost dev ports).
API_CORS_ORIGINS=https://sentinel-panel.vercel.app,http://localhost:3000,http://localhost:5173

# 32-byte (base64) AES-256-GCM key for at-rest encryption of sensitive
# runtime_config values (Discord token, AI key, Supabase service key, webhook
# URLs). Strongly recommended in DB_MODE=local+cloud and DB_MODE=cloud โ€” without
# it those values are written to Supabase in plaintext.
# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
SENTINEL_DATA_KEY=

# โ”€โ”€ Database mode (requires restart) โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# local       โ€” SQLite only. Default.
# local+cloud โ€” SQLite live DB + async Supabase mirror.
# cloud       โ€” Hydrates SQLite from Supabase on boot. For Railway / Fly.io.
DB_MODE=local
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_SYNC_INTERVAL_MS=300000   # cloud recommended: 30000

# โ”€โ”€ All settings below are hot-reloadable via PATCH /api/config โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
PROFILE_POLL_INTERVAL_MS=300000
STATUS_POLL_INTERVAL_MS=120000
DAILY_SUMMARY_INTERVAL_MS=3600000

# โ”€โ”€ AI Provider โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# Providers: none (default) | gemini | ollama | openai | anthropic
# Gemini recommended โ€” free tier: 15 RPM / 1M tokens per day
# Get a free key: https://aistudio.google.com

AI_PROVIDER=none
AI_MODEL=gemini-2.5-flash
AI_API_KEY=
AI_BASE_URL=http://localhost:11434/v1
AI_ANALYSIS_INTERVAL_MS=86400000
AI_CATEGORIZATION_BATCH_SIZE=50

# โ”€โ”€ Backfill โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
BACKFILL_ENABLED=true
BACKFILL_MAX_DAYS=90
BACKFILL_MAX_MESSAGES_PER_CHANNEL=5000

# โ”€โ”€ Alerts โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
ALERT_WEBHOOK_URL=
CRITICAL_WEBHOOK_URL=        # system errors only (token invalidation, auth failures)
ALERT_DIGEST_MODE=false
ALERT_DIGEST_INTERVAL_MS=900000
ALERT_FATIGUE_THRESHOLD=20

# โ”€โ”€ Daily Briefs โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
BRIEF_GENERATION_TIME=07:00  # UTC โ€” requires AI_PROVIDER != none

OPSEC tip: Set RANDOM_JITTER=true to make your polling patterns and gateway fingerprint less predictable.


๐Ÿ›ฐ๏ธ API Behaviour at a Glance

Concern Default
Authentication Bearer API_AUTH_TOKEN on every /api/* route (constant-time compare).
CORS Allowlist via API_CORS_ORIGINS; defaults to hosted panel + localhost. * opts into reflect-any.
Rate limiting 300 req/min/IP via @fastify/rate-limit. /health is allowlisted. 429s carry Retry-After.
Liveness probe Unauthenticated GET /health โ†’ { status, uptimeMs, gatewayConnected }.
Error responses Unhandled errors return { error: "Internal server error", requestId }. Full detail (with stack) lives in logs keyed by the same id. Schema-validation errors surface as 400 with safe details.
Full export GET /api/export/:userId streams NDJSON (application/x-ndjson) โ€” one row per line, section markers framed by _section. CSV path (/csv) streams row-by-row too.
SSE replay GET /api/events/stream?since=<lastEventId> replays missed events from the 500-entry in-memory buffer.
Search escape ?search= query is escaped against LIKE wildcards โ€” % and _ from the client are literal text.


๐Ÿšข Deployment

Platform Notes
Local / VPS npm start or PM2 (pm2 start npm -- start)
Docker Dockerfile included
Railway One-click deploy โ€” Deploy on Railway
Fly.io fly.toml included. Use DB_MODE=cloud with Supabase

For cloud deployments: set DB_MODE=cloud, SUPABASE_SYNC_INTERVAL_MS=30000, and RANDOM_JITTER=true.


๐Ÿ“š Documentation

Guide Description
docs/selfbot.md Full setup and configuration guide
docs/commands.md Self-command system reference
docs/api.md REST & SSE API reference
docs/presence-tracking.md How real-time presence tracking works

๐Ÿ”— Related


๐Ÿ“œ License

PolyForm Noncommercial License 1.0.0

About

The data collection engine for the Sentinel ecosystem. Connects to Discord as a user account, logs behavioral data on tracked targets, and exposes everything through a local REST/SSE API.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages