> ## Documentation Index > Fetch the complete documentation index at: https://docs.headlesslabs.xyz/docs/llms.txt > Use this file to discover all available pages before exploring further. # Honeypot > Configure one server-scoped trap channel to detect messages from non-exempt members and apply a verified Headless response. ## Detection and exclusions Headless currently supports one Honeypot channel per server. Setup publishes its panel and enables message triggers; reaction triggers are off initially and can be enabled in the Dashboard. Bots, members with `Administrator` or `Manage Server`, and configured exempt roles are ignored. The same member cannot trigger another response during the 45-second repeat-protection window. The internal configuration key is still named `honeyspot`; the public command is `.honeypot`. ## Setup, activation, and permissions Running `.honeypot` only reports the current status; it does not create a channel or enable enforcement. `.honeypot setup [action]` creates or reuses the configured channel, applies the `@everyone` overwrites, publishes the panel, and enables enforcement. The bot needs `Manage Channels` and `Manage Roles`; setup fails instead of reporting success if Discord rejects the channel permissions. Configuration is saved after the panel is published successfully. On a new server configuration, omitting `action` selects a seven-day `timeout`. If a server already has a saved action, setup without an action preserves it. Legacy configurations with a saved action but no duration retain the previous 60-minute fallback; an explicitly saved duration also remains unchanged. When creating a new channel, Headless grants `@everyone` `View Channel`, `Send Messages`, and `Read Message History`. When reusing an existing channel, it changes only `View Channel` and `Send Messages` and preserves the other overwrites; history, reactions, attachments, and embeds follow the channel's existing permissions. Use a dedicated channel and tell staff that interacting there can trigger the configured action. `.honeypot add #channel ` uses an existing text channel without changing its permission overwrites; the bot must be able to view it, read its history, and send the panel. > [!NOTE] > > Before changing an `@everyone` overwrite, Headless saves its allow/deny/inherit state in the server configuration. `.honeypot remove` restores it without deleting the channel or its messages. `.honeypot add` does not modify overwrites. Configurations created before snapshots do not contain the original permission state; Headless disables the trap and keeps the reference so an administrator can review the channel manually. ## Response and notification Accepted actions are `log`, `timeout`, `kick`, and `ban`; any other action is rejected. Timeout can be configured from 1 minute to 28 days. `log` records without punishment. For message triggers, `delete_trigger` is enabled by default: after the response is processed successfully, Headless attempts to delete the triggering message; if processing fails, the message is kept. Deletion is independent of the punishment, and a deletion failure does not undo it. Reaction triggers never delete the source message. Timeout, kick, and ban require the corresponding native bot permission and a role hierarchy that allows acting on the member. Headless also attempts a security DM and records the result; a failed DM does not prevent the response. ### Add, inspect, and remove the trap The current configuration supports one channel. Adding a different channel while one is still configured is rejected; remove the old channel first. Removal disables enforcement, restores saved overwrites, and clears Headless's channel reference; it does not delete the Discord channel, panel message, or channel history. If Discord rejects restoration, Headless keeps the disabled configuration and snapshot so you can retry. ```headless-command Syntax theme={null} .honeypot add <#channel> ``` ```headless-command Example theme={null} .honeypot add #honeypot timeout ``` ```headless-command Syntax theme={null} .honeypot list ``` ```headless-command Example theme={null} .honeypot list ``` ```headless-command Syntax theme={null} .honeypot remove [#channel] ``` ```headless-command Example theme={null} .honeypot remove #honeypot ``` These commands are server-only and require native `Administrator` or its Headless virtual permission equivalent. `setup` and `channel` require the bot's `Manage Roles` permission to configure channel overwrites; `setup` also needs `Manage Channels` when it must create the channel. For `add`, Headless checks that it can view the channel, read its history, and send the panel, plus the native moderation permission required by the selected action. Role hierarchy is checked when an action is applied to a member. ## Optional member-history cleanup Cleanup is off initially. `.honeyspot cleanup on [limit]` (aliases `clean`, `limpieza`, and `cl`) enables cleanup on future triggers; `off` disables it. Omitting the limit uses 250; values must be from 25 to 1,000, and out-of-range values are rejected without changing the setting. Cleanup only runs after a successful punitive action (`timeout`, `kick`, or `ban`), never in `log` mode. Each trigger deletes at most `min(limit, 500)` messages total, and only content younger than 14 days. It scans accessible text channels and threads; Headless needs `View Channel`, `Read Message History`, and `Manage Messages` in each channel. Changing this setting does not start an immediate cleanup. ## Panel and configuration `.honeyspot test` publishes a panel preview in the configured channel, or the current channel if none is set; it does not test the trigger or apply a punishment. `status` reports permission and hierarchy checks. The Dashboard can adjust messages, exemptions, and panel visuals (title, footer, thumbnail, and image/banner); remote images must use HTTPS and the panel accent remains yellow. `message` changes the panel text, and `panel` republishes or updates it. ## Steps **1. Choose a dedicated channel** Tell staff that posting—and reacting if enabled—can trigger an automatic response. Do not use a routine channel without reviewing its permissions. **2. Set up in logging mode** Run `.honeypot setup log`; setup enables the module in a non-punitive logging mode. On a new configuration, setup without an action defaults to a seven-day timeout. **3. Review the configuration** Check `.honeypot list`, `.honeypot status`, channel permission overwrites, exemptions, and bot permissions. `.honeypot test` only previews the panel; test the trigger only with a non-exempt test account and an approved policy. **4. Enable punishment only after review** If server policy allows, run `.honeypot off`, choose an action and duration, confirm permissions and hierarchy, then run `.honeypot on`. Keep history cleanup off unless its scope is separately approved. ## Commands and troubleshooting > **Main commands** > > The canonical command is `.honeypot`; `.honeyspot` and `.honey` remain compatible aliases. The command prefix is configurable per server, so replace `.` in examples if that server changed its prefix. The group includes `add`, `list`, and `remove`, plus the existing `setup`, `spot`, `on`, `off`, `action`, `channel`, `timeout`, `cleanup`, `status`, `panel`, `message`, and `test` management commands. The `.honeyspot` alias accepts the same operations, such as `.honeyspot setup log` and `.honeyspot action log`; `.honeyspot test` only previews the panel. Honeyspot has no slash commands. > **Which permissions are required?** > > Subcommands are server-only and require native `Administrator` or the Headless virtual equivalent. The bot needs `Manage Channels` to create the setup channel and `Manage Roles` to set channel overwrites with `setup` or `channel`; it must also be able to publish the panel. The `add` command checks channel access to view, read history, and send; timeout, kick, and ban also need their corresponding native bot permission. Headless must have a higher role than the member it acts on. Fake Permissions cannot grant Discord permissions to the bot. > **The test command did not trigger the trap** > > That is expected. `test` publishes or previews the panel without simulating a message or reaction event. Use `status` to review state and permissions; the trigger itself requires interaction with the configured channel by a non-exempt test account. > **Cleanup did not remove every message** > > Cleanup is bounded by the per-channel scan limit and a global cap of at most 500 deletions per trigger. It skips old content, inaccessible channels, and deletions rejected by Discord; results can be partial and are reported to Logs. ### `.honeypot setup` ```headless-command Syntax theme={null} .honeypot setup [log|timeout|kick|ban] ``` ```headless-command Example theme={null} .honeypot setup log ``` The `.honeyspot` alias remains supported. ### `.honeyspot action` ```headless-command Syntax theme={null} .honeyspot action ``` ```headless-command Example theme={null} .honeyspot action log ``` Also works: `.honeyspot action timeout` ### `.honeyspot off` ```headless-command Syntax theme={null} .honeyspot off ``` ```headless-command Example theme={null} .honeyspot off ``` ### `.honeyspot timeout` ```headless-command Syntax theme={null} .honeyspot timeout ``` ```headless-command Example theme={null} .honeyspot timeout 60m ``` ### `.honeyspot on` ```headless-command Syntax theme={null} .honeyspot on ``` ```headless-command Example theme={null} .honeyspot on ``` ![Historical screenshot of a Spanish Honeyspot confirmation; current Headless replies in English. The user and channel are redacted.](https://mintcdn.com/headless-labs/ZF85v3KoGVX7saRn/images/headless-replies/honeyspot-setup-redacted.png?fit=max\&auto=format\&n=ZF85v3KoGVX7saRn\&q=85\&s=91100e5bc14763602f69e1c5372c4145) Historical screenshot of an earlier Spanish response; current Headless replies in English. The user and channel are redacted. ### `.honeyspot status` ```headless-command Syntax theme={null} .honeyspot status [member] ``` ```headless-command Example theme={null} .honeyspot status ``` Also works: `.honey status` ### `.honeyspot test` ```headless-command Syntax theme={null} .honeyspot test ``` ```headless-command Example theme={null} .honeyspot test ``` ### `.honeyspot channel` ```headless-command Syntax theme={null} .honeyspot channel ``` ```headless-command Example theme={null} .honeyspot channel #honeyspot ``` ### `.honeyspot message` ```headless-command Syntax theme={null} .honeyspot message ``` ```headless-command Example theme={null} .honeyspot message Security message ``` ### `.honeyspot panel` ```headless-command Syntax theme={null} .honeyspot panel ``` ```headless-command Example theme={null} .honeyspot panel ``` ### `.honeyspot cleanup` ```headless-command Syntax theme={null} .honeyspot cleanup [limit=250] ``` ```headless-command Example theme={null} .honeyspot cleanup on 250 ``` Also works: `.honeyspot cleanup off` > [!WARNING] > > When no action has ever been saved, `.honeypot setup` defaults to a seven-day timeout. On an existing configuration, setup without an action preserves its saved action. Start a new configuration with `.honeypot setup log` if you do not want punishment. History cleanup can irreversibly delete recent messages across channels and is capped at 500 deletions per trigger. **Note:** Honeyspot settings are saved per server. The `test` preview only publishes the panel; it does not verify that the trigger or a punishment will work. ## Related pages * [Moderation](/docs/en/security/moderation.md) * [Logging](/docs/en/server/logging.md) * [Dashboard](/docs/en/dashboard.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.