ZipGuard server guide

Everything a server owner or moderator needs, in the order you will need it. Commands are typed in any channel; replies are visible only to you unless noted.

Before you invite

• You need Administrator in the server to run /setup. Moderators need Moderate Members, Kick Members or Ban Members to use the matching buttons.
• The invite asks for: Manage Roles (quarantine role), Manage Channels (log and verify channels, hiding channels from the quarantine role), Manage Server (reading invites and pausing them in raid mode), Kick Members, Ban Members, Moderate Members (timeouts), View Audit Log (anti-nuke), and the basics to read and post. It asks for nothing else.
• The bot never needs Message Content unless you turn on link defense, and it never reads IP addresses, emails or phone numbers. The full list of what it stores is at zipguard.dev/data.

Install, in five steps

• Apply at zipguard.dev/pilot with your server name and ID. The thanks page has the invite link; invite the bot right away.
• The bot posts "waiting for approval" in your server and does nothing else. A ZipGuard operator approves applications by hand, usually within a day; the bot then posts "approved, run /setup".
• Run /setup. It creates #zipguard-log (private, for moderators), #verify (visible only to held members) and the role "zipguard quarantine", hides every existing channel from that role, and turns on shadow mode for 7 days. Under a minute.
• Drag the zipguard role above "zipguard quarantine" in Server Settings, Roles. Without this the bot cannot apply or remove the quarantine role, and the challenge button does nothing. This is the most common setup mistake.
• Watch #zipguard-log for a week. Every verdict is logged with its reasons and nothing is enforced. When the verdicts look right, run /zipguard shadow on:false.

What members see

• Most members see nothing. A low-risk join passes with zero clicks.
• A medium-risk joiner is given the quarantine role and sees only #verify, which holds one message with two buttons: "I'm human" and "Appeal". One click on "I'm human" removes the role. A click faster than a person can click is held for a moderator instead.
• A high-risk joiner is held for a moderator (or timed out, kicked or banned, if you chose that). They can click Appeal, write a sentence, and it lands in #zipguard-log.
• Any member can run /my-data to see what ZipGuard holds about them, /forget-me to delete it, /privacy for the data statement, and /report member reason to flag someone to the moderators.

What moderators do

• Every log entry shows the member, the score, the rules that fired and the action taken, with Approve, Kick and Ban buttons. Approve removes the quarantine role and any timeout; your decision is recorded and feeds the false-positive rate.
• Right-click any member, Apps: "ZipGuard: verdict" shows their latest record with the same buttons; "ZipGuard: hold for review" quarantines them on the spot.
• Member reports arrive in #zipguard-log with a "Hold for review" button. Three reports from accounts older than a week inside 24 hours hold the member automatically.
• Anti-nuke and raid mode act on their own and post what they did. Both can be turned off.

Settings

Each one is a /zipguard subcommand. Defaults are safe for most servers.

How the score works

• Each rule adds or subtracts points: account under a day old +40, under a week +25, under a month +10, default avatar +10, public badges -15, five or more joins in a minute +25, three or more through the same invite +20, two or more recent joiners created within a day of this one +30, raid mode +30, banned in a sibling server +70.
• 0 to 29 is low (nothing happens), 30 to 69 is medium (one-click challenge), 70 and up is high (your chosen action). Change the bands with /zipguard thresholds.
• Raid mode checks everyone regardless of score. Every log entry lists the exact rules, so you can see why.

Raid mode

• Starts on its own when the join threshold is reached inside one minute (10 by default).
• For 10 minutes every joiner is held, and server invites are paused if the bot has Manage Server. A log entry says so.
• Ends by itself after 10 quiet minutes and re-enables invites, or at once with /zipguard raid end:true.

Anti-nuke

• Three channel deletes, three role deletes or three webhooks created by one account inside a minute: the account loses all its roles, deleted channels and roles are re-created from the bot's cache, and #zipguard-log gets an alert. Ten bans or kicks in a minute raise an alert only.
• The server owner is never touched, and neither is the bot itself. An account whose roles sit above the bot's cannot be stripped; the alert says so.
• Re-created roles come back empty: members need them assigned again. Channel history cannot be restored.

Link defense

• Needs the Message Content intent on the bot application and LINK_DEFENSE=on on the hosted bot; servers under 10,000 users can turn the intent on in the Developer Portal without review.
• When on, a member who posts a link that imitates discord.gg or steamcommunity.com, a link next to scam wording, a link with @everyone or five or more mentions, or the same link in three channels inside a minute is quarantined and the messages are deleted. Moderators with Manage Messages are never held.
• Nothing about messages is stored. The one-minute window lives in memory.

Dashboard and stats

• /zipguard stats prints the scorecard: zero-click pass rate, challenge completion, flagged and removed counts, moderator overturns (your false-positive rate), median time to verdict.
• /zipguard dashboard publishes the same numbers plus per-day counts, rule frequencies and settings to zipguard.dev and returns a link that works for 24 hours. The page holds no member names or IDs. Anyone with the link can read it, so share it with moderators only.

For ZipGuard operators

• /zipguard pilot-inbox in a channel makes it the inbox: every application from zipguard.dev appears there within a minute as a card with Approve and Reject. Run it again elsewhere to move the inbox; off:true turns it off. Only the owner of the bot application can set an inbox.
• Approve flips the gate for that server: if the bot is already in it, it posts "approved, run /setup"; if not, it says so the moment it joins. Reject leaves the bot dormant there.
• Applications are kept on the website host for 90 days; the card shows the server name, ID, the applicant's Discord username, size and note.

Troubleshooting

• The "I'm human" button does nothing, or a held member keeps the role: drag the zipguard role above "zipguard quarantine".
• A held member can still see some channels: a role with an explicit View Channel allow on those channels wins. /setup lists such roles; remove the allow or accept it.
• Commands are missing: they register the moment the bot joins and again at every restart. If they still do not appear, kick and re-invite the bot.
• Nothing is being enforced: shadow mode is on. /zipguard stats says so in its first line; /zipguard shadow on:false ends it.
• Anti-nuke fired on a legitimate admin doing cleanup: give the roles back by hand; next time run /zipguard antinuke on:false first.
• /setup again is safe: it repairs missing channels and roles and keeps your settings.

Support

• help@myagents.email, an agent-triaged inbox. Security reports: subject "zipguard security".
• If an AI agent is helping you, point it at zipguard.dev/support/agent.md first.