Modbot Docs
Self-hosting

Data and retention

What Modbot keeps, for how long, how to set a retention window, how to read the storage estimate and the machine usage charts, and what deleting does.

Modbot records what happens in your group as a log of facts: one short record per thing that happened, such as a ban, a join, a role change or a sign-in. From those facts it builds daily totals for the charts. This page says what is kept, for how long, and what happens when you choose to delete older data.

Modbot deletes nothing by default

Out of the box every retention window is set to 0, which means keep forever. A Modbot that nobody has configured keeps all of its history, and that is the intended way to run it.

The reason is simple: group history cannot be filled in later. Whatever Modbot did not record while it was happening is gone, and no amount of asking VRChat brings it back. A default that quietly removed old join and leave records would also remove the answer to "is this person a regular?" for anyone who joined a few months ago.

If storage is a real cost for you, you can set a window. The settings page shows what keeping everything actually costs first, so it is a choice you make with the numbers in front of you.

What Modbot keeps

Retention sorts facts into two kinds, plus stored Discord messages.

KindWhat is in itDefault
Moderation factsBans, kicks, warnings, role changes, members joining and leaving the group, the group's audit log, case file changes, evidence, Discord moderation, Discord account links, Modbot's own sign-ins, account and settings changes, Discord bot commands (who looked up whom), and anything Modbot does not recognise.Forever
Presence factsInstance joins and leaves, avatar changes, Discord voice sessions, and Modbot's own routine notices (sync problems, rate limits, connection blocks, retention runs, AI limit notices, the Discord bot's posting markers and new-member link prompts).Forever
Discord messagesThe messages Modbot stores from your Discord server, including earlier versions of edited messages and messages that were later deleted.Forever

Moderation facts arrive at a few hundred a day; in a busy group, presence facts can arrive around a thousand times faster. That is why they can be given different windows: a ban from three years ago is exactly what a moderator needs, while a join from three years ago usually is not.

A new kind of fact that Modbot has not been told about always counts as a moderation fact. Keeping something longer than intended costs a little disk; deleting it early cannot be undone.

What retention never touches

Retention only removes facts and stored Discord messages. These are not affected by any retention setting:

  • Daily totals. Charts keep their full history even after the facts behind them are removed.
  • Case files, their written reasons and the profile snapshot taken at the time. See Bans and case files.
  • Evidence files attached to case files. See Evidence.
  • Staff accounts. They are never deleted, only disabled. See Staff accounts.
  • Which invite each Discord member joined with. With invite tracking on, Modbot keeps the invite used, the member's Discord id and the time they joined, until a purge removes that member.
  • Who was welcomed. With welcome steps on, Modbot keeps the member's Discord id, whether the welcome was sent or is waiting for the join gate, and when, so nobody is welcomed twice, until a purge removes that member.
  • Ko-fi supporters. With Ko-fi supporters on, Modbot keeps each supporter's name, tier, Discord id, payment dates and transaction ids, and a one-way fingerprint of their email address (never the address), and the code each person got from /supporter-code, until a purge removes the supporter matched to that Discord account.
  • Patreon supporters. With Patreon supporters on, Modbot keeps each supporter's name, tier, Discord id, Patreon member id and the date of each charge (never an email address), until a purge removes the supporter matched to that Discord account; a patron who is still pledging comes back at the next daily catch-up. If you save a Patreon client's keys, it also keeps your campaign's id, when the access token runs out, and when the last catch-up finished, until you save new keys.
  • Who was sent the link reminder. After staff start the link reminder, Modbot keeps the member's Discord id, whether it was sent, and when, so nobody is sent it twice, until a purge removes that member.
  • New staff checklists. A new staff member's written answers, their buddy's sign-offs and note are kept with the checklist until it is removed or the account is deleted. See New staff checklist.
  • Discord server snapshots. Role and channel names and permissions, never members. At most 100 are kept, and the schedule deletes its own beyond the 24 newest. See server snapshots.

Modbot's own log

Modbot's log lines are not facts and have their own window: Settings, Server, Keep for (days), Modbot's log, which is 180 days out of the box rather than forever. They are Modbot talking about itself, not a record of what happened to a member, and six months is longer than any question anybody asks of them. 0 keeps them forever. See Logs.

Setting a retention window

Open Settings, then the Server tab. You need the Change settings permission.

The Keep for (days) panel has four record fields, alongside Modbot's own log:

  • Moderation
  • Who was where
  • Discord messages
  • Closed reports: how long a closed member report keeps what the member wrote and the copy of the message they reported. 365 days out of the box.

Type a number of days, or 0 to keep forever, and press Save. Shortening any of the windows asks you to confirm with a red Delete older records button, because the save also removes whatever now falls outside it.

Deleted means gone

Anything past a retention window is destroyed permanently. There is no undo, no recycle bin, and Modbot cannot fetch it again. If you might want it later, take a database backup before you shorten a window. See PostgreSQL.

When data is actually removed

  • Modbot checks retention once a day. If a check fails it tries again an hour later, and keeps running normally in the meantime.
  • Facts are stored in one table per calendar month (UTC), and Modbot removes whole months, never single records. A month is only removed once its last day is past the window. So with a 90-day window, facts from early in a month can stay a few weeks longer than 90 days before their month goes.
  • If a month holds both kinds of fact and only one kind has passed its window (for example presence at 90 days and moderation kept forever), Modbot rebuilds that month with only the facts that are still kept, and removes the rest.
  • Discord messages work the same way: a month of messages is removed once its last day is past the window. When Modbot catches up on messages it missed, it does not store messages that are already older than the window.
  • Closed reports are not months of anything: the same daily check finds each report closed more than the window ago and empties its text and message copy, one report at a time. The bare record stays: who, about whom, when, and the close note. A report that is still open is never touched. How many were emptied is written to Modbot's log, not to the Retention pruned entry.
  • Every run that removes something is recorded as a Retention pruned entry in the operational log.

Shortening a window removes the old data at the next daily check. Lengthening it, or setting it back to 0, cannot bring back anything already removed.

The storage estimate

The Storage card, folded under Settings, Server, Storage and machine usage, shows what your own Modbot is storing. The numbers are measured from your database, not taken from a table.

LabelWhat it shows
DatabaseThe size of Modbot's recorded history on disk: all facts and daily totals, indexes included.
RecordsHow many facts are stored. On a large history this is PostgreSQL's own close estimate rather than an exact count.
Per recordThe measured size of one fact, indexes included.
ArrivingHow many facts a day are arriving, measured over recent history. It says Not measurable yet until Modbot has at least a day of facts.

Two inputs turn this into your own terms:

  • Cost per GB a month: what your host charges per GB per month. The chart adds a second line showing the estimated monthly cost.
  • Disk size (GB): the size of your disk if you host at home. The chart shows when the disk would fill.

Both inputs are remembered by your browser only. They are not saved in Modbot and change nothing about how it behaves.

Reading the chart

  • The left side is the size Modbot recorded each day over the past year. Modbot records one size a day, starting from the first day it recorded one, so a new Modbot has a short history and today sits further left.
  • The right side is an estimate for the next year, drawn dashed. It is a straight line at the current growth rate.
  • With less than a month of history the estimate also has a shaded band, showing the same line at a slower and a faster rate, because the rate is still uncertain.

Treat the estimate as a rough size, not a forecast. Real growth is rarely a straight line: a group that opens more instances records more facts per member.

What the estimate does not include

The Storage card covers facts and daily totals. It does not include:

  • Evidence files. Their count and size are shown under Settings, Evidence, in What this store is doing, as Evidence held. A single video can be larger than months of facts, so once you attach evidence, it is usually the evidence that decides your storage bill. Where it is kept is your choice: see Storage buckets.
  • Stored Discord messages.
  • The rest of the database, such as settings, accounts, case files and member lists.

Your hosting provider's own dashboard shows the full size of the database.

Machine usage

Folded under Settings, Server, Storage and machine usage is a Machine usage card: how hard the machine Modbot runs on has been working over the last half hour, as one small chart per figure with its current value above it. You need the See the operational log permission to see it; for anybody else the card is not there.

ChartWhat it shows
ProcessorHow much of the processor Modbot has been using, where 100% is every processor it has been given, flat out.
MemoryHow much memory Modbot is holding. When something sets a memory limit — which a container usually does — the value reads 384 MB of 2.0 GB and the chart is drawn against that limit.
DiskBytes a second Modbot has read from and written to disk.

Two things are worth knowing before you read too much into it.

  • These are Modbot's own figures, not the whole machine's. They cover the Modbot process and nothing else. If your database runs beside Modbot rather than inside it — which it does on Railway, and in most Docker setups — then the database's own processor time, memory and disk activity are not in these charts. Your hosting provider's dashboard is where you see the whole machine.
  • A figure the host will not report is left out rather than shown as zero. The disk counters exist on Linux only, so a Modbot running on Windows shows processor and memory and no disk chart at all. The whole card is missing for the first few seconds after a restart, because processor use and disk activity are rates and a rate needs two readings.

Modbot takes a reading every ten seconds and keeps the last thirty minutes in memory. Nothing about machine usage is written to the database, and nothing survives a restart: it is there to answer "is this server struggling right now", and a question about last week is one it was never meant to answer. The screen refreshes itself while you have it open.

Deleting other things

  • Case files are never deleted. A case file can be withdrawn, with a note; it stays readable. See Bans and case files.
  • Evidence files can be destroyed one at a time by somebody holding Destroy evidence, with the Destroy button on the case file. The file is deleted permanently and a reason is required. The record that it existed stays: its size, type, who destroyed it, when and why. A file that is on more than one case file has to be taken off the others first. Taking a file off a case file only ends that case file's hold and keeps a line saying so. See Evidence.
  • Staff accounts are never deleted, because every recorded action points at the account that did it. Disable them instead.

Personal information

Presence data (who was in which instance, for how long, wearing what) and stored Discord messages are personal information, even though your group could see them at the time. They live on your own server and database, and how long they are kept is up to you. For what Modbot protects and how, see Security.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page