GETTING_STARTED.MD

Getting Started

This is a library, not a bot - it has no login token of its own and does nothing until you attach it to a discord.js Client you already have running. This guide is written for that: you already have a working bot and want to add GlassFrame Protocol to it.

If you're starting completely from scratch instead, examples/basic-usage.js is a full minimal bot (client creation included) you can copy and run directly.

Prerequisites

  • An existing discord.js v14.16+ bot, already logging in successfully
  • Node.js 18+ and npm - see Step 1 below if you don't have these yet (GlassFrame's optional AI layer uses the global fetch, built into Node 18+)
  • Your bot invited with these permissions: Manage Roles, Kick Members, Ban Members, Manage Channels, Manage Webhooks, View Audit Log, Moderate Members, Manage Messages
  • These gateway intents enabled: Guilds, GuildMembers, GuildMessages, MessageContent, GuildModeration

Step 1 - Install Node.js and npm

npm ships bundled with Node.js, so installing Node.js gets you both. If node -v and npm -v already print version numbers, skip straight to Step 2.

Termux (Android)

pkg update && pkg install nodejs

Use nodejs-lts instead of nodejs if you'd rather track the LTS release line.

Windows / macOS / Linux

Install the LTS release from nodejs.org - npm is bundled in. Linux users can use their distro's package manager instead (apt install nodejs npm on Debian/Ubuntu, etc.), or a version manager like nvm if you need more than one Node version installed side by side.

Verify

node -v
npm -v

Node should report 18 or higher.

Step 2 - Install the package

From your existing bot project (the same folder as its package.json):

npm install glassframe-protocol

discord.js is a listed dependency and installs automatically alongside it. If your project doesn't already have its own copy, install it explicitly too:

npm install glassframe-protocol discord.js

Step 3 - Attach it to your client

In your main bot file, once your client is ready:

const GlassFrame = require("glassframe-protocol");

client.once("ready", () => {
  const frame = new GlassFrame(client, {
    // Required: tell GlassFrame where to send its logs.
    getLogChannel: async (guild) =>
      guild.channels.cache.find((c) => c.name === "security-logs") ?? null,

    // Optional: which layers turn on immediately vs. stay off until
    // someone arms them from the panel. Layers not listed here start OFF.
    autoStart: ["basicSecurity", "antiRaid", "antiNuke"]
  });

  frame.on("warning", (w) => console.warn(`[GlassFrame:${w.layer}]`, w.message));
});

This is the entire integration. You do not write a spam filter, a raid detector, a command handler, or any punishment logic - constructing GlassFrame attaches everything it needs to your existing client internally. Nothing else in your bot's code has to change.

Step 4 - Make a log channel

Create a text channel (matching whatever getLogChannel looks for - the example above uses one named security-logs) and make sure your bot can see and send messages in it. Every alert, every punishment, every layer toggle gets reported there through Components V2 messages.

Step 5 - Turn features on

Two ways, pick either or both:

  • Code: list layer names in autoStart (see Step 3) - applies to every server by default - or call frame.enableLayer("antiNuke", guildId) / frame.disableLayer("antiNuke", guildId) for one specific server anywhere after construction.
  • In Discord: an admin (Manage Server permission) sends !gf panel and gets 5 buttons - Activate/Deactivate AntiRaid, AI Moderation, AntiNuke, Basic Security, and Full Protocol (all four at once) - scoped to the server the command was sent in. This is the only interface most server admins will ever need - no code, no slash commands.

Layer on/off state is per-guild - arming AntiNuke in one server has no effect on any other server this bot is in - and it persists across restarts if you pass a stateStore (a plain JSON file works out of the box, no database needed). See docs/STATE.md for the full model.

Step 6 (optional) - AI Moderation

Off by default. To turn it on:

  1. Get one or more free API keys from console.groq.com
  2. Pass them in config: 
    const frame = new GlassFrame(client, {
  getLogChannel: /* ... */,
  config: {
    aiModeration: { apiKeys: (process.env.GROQ_API_KEYS || "").split(",") }
  }
});
  3. Arm the layer (panel button, or add "aiModeration" to autoStart)

Multiple keys are rotated automatically, and any key that gets rate-limited is benched temporarily rather than breaking moderation. It only calls out to Groq for messages local detection scores as ambiguous - most messages never leave the process.

Step 7 (optional) - Your own bot-wide dashboard

Everything so far is per-server. If you're the one actually running the bot and want a cross-server view instead - busiest servers, bot-wide AI usage, a live activity feed - that's a separate thing:

  1. Add your own Discord user ID to options.owners
  2. Optionally set config.engine.password as a second factor
  3. In a private channel (or DM the bot): !gf engine, adding the password after it if you set one

This is gated completely differently from everything else on this page - by your owner ID, not Manage Server permission - and it's deliberately left out of !gf help so a server admin wouldn't stumble onto it. Full reference: docs/ENGINE.md.

Everyday use, once it's running

Nobody needs this guide again after setup. Server admins use:

Command Does
!gf panel The 5-button control panel
!gf status Which layers are active
!gf scan Checks current roles for name/permission mismatches
!gf metrics Performance and cache health
!gf phishing add/remove/list <domain> Manage the link blocklist
!gf whitelist add/remove <userId> Exempt a user from punitive action in this server
!gf prefix set/reset Change (or reset) this server's own command prefix
!gf help Lists all of the above

Going deeper