Modbot Docs
Self-hosting

What you run

The one service and one database Modbot needs, what is optional, and what the project's own central services are used for.

Modbot runs as one service plus one PostgreSQL database. There is no Redis, no search server, no message queue and no outside sign-in service to set up.

The service needs one setting to start: DATABASE_URL, which tells it where the database is. Everything else, from the VRChat account to the Discord bot, is entered in the web app through the setup wizard and Settings, and stored in the database.

What is required

The Modbot server

One container, built from the Dockerfile at the root of the repository. It holds:

  • the web app your staff open in a browser,
  • the API,
  • the VRChat sync, which reads your group's audit log, members, bans and profiles,
  • the Discord bot, which only starts once you give it a token.

Run exactly one copy. Modbot signs in to VRChat with one account and paces its requests to stay inside VRChat's rate limits. A second copy would send twice as many requests against the same limit, and neither copy could see what the other was doing.

The server listens on the port in PORT (8080 if you do not set one) and answers two health checks, /health/live and /health/ready. See Checking a deployment.

PostgreSQL

The database holds everything: settings, staff accounts, the history Modbot records, and the keys Modbot uses to protect stored passwords and keep people signed in. Modbot creates and updates its own tables every time it starts. See PostgreSQL.

What is optional

What it is forWhere you set it up
Evidence storageKeeping screenshots and videos attached to case files. You can use an S3-compatible storage bucket, a folder on disk, or the database itself. Until you choose one, uploads are turned off and everything else works.Settings, Evidence tab. See Storage buckets.
The Discord botPosting events to Discord, instance announcements, account linking, and reading your Discord server.The setup wizard, or Settings, Discord tab. See Setting up the bot.
Email (SMTP)Sending email, such as password reset links.The setup wizard, or Settings, Email and alerts tab.
An AI providerAI moderation rules, insights and chat.Settings, AI tab. See AI settings.
A proxyReaching VRChat from a host whose network VRChat's Cloudflare protection blocks. Common on VPS and datacentre hosting.The setup wizard's connection check, or Settings, Modbot's VRChat login tab.
SeqSending logs to a Seq server, so you keep them when the container's disk does not survive.The SEQ_URL environment variable.

A Modbot with none of these is complete and working: it syncs your group, and your staff can use every page that does not depend on one of them.

Ways to deploy

Deploy on Railway
curl -fsSL https://modbot.co/get.sh | sh

After it is running, open its address in a browser. A new Modbot sends every visitor to the setup wizard.

The project's central services

The Modbot project runs a few services of its own. A self-hosted Modbot does not need any of them to sync your group or run your moderation. Here is what each one is used for.

my.modbot.co

A page that remembers the Modbot addresses you use, so you can pick one from a list instead of hunting for a URL.

  • When you finish the setup wizard for the first time, and when somebody you invited makes their account, Modbot opens https://my.modbot.co/register?url= followed by your Modbot's address, in a new tab. The link also carries your group's id, name, icon and banner, so the page can show which Modbot it saved. That page saves the address in your browser. my.modbot.co also records that the address was registered; if it cannot right then, the page says Saved on this device and sends the address later, while the tab is open or the next time you open the page.
  • my.modbot.co checks the group for itself. It asks your Modbot at /api/server what group it moderates instead of believing the link, because anyone can write a link. If your Modbot does not answer, only the address is saved.
  • Your account in the web app has an Add to my.modbot.co button that does the same thing later.
  • The companion's pairing button opens https://my.modbot.co/go?redir=/pair, which lists your saved Modbots and sends you to the pairing page on the one you pick. See Pairing.
  • AI moderation can use shared term lists published on my.modbot.co. Modbot fetches a list only if you choose to use one. See AutoMod.

If you would rather not use it, skip the tab it opens and bookmark your Modbot's address instead.

Modbot Cloud

cloud.modbot.co keeps a backup of what companions read from VRChat's log: presence events for every instance their moderator is in, never raw log lines. Each client sends this straight to Modbot Cloud, whether or not it is paired, unless the person using that PC turns it off in the client's own settings. Your Modbot server has no say in it. See Client settings.

Your Modbot server's own MODBOT_CLOUD_ENDPOINT and MODBOT_CLOUD_DISABLED are only about your server: which Modbot Cloud it talks to, and whether it talks to one at all. See Environment variables.

Your server sends Modbot Cloud four things, and reads two:

SendsHow oftenSwitch in Settings → Server
A report. The fields below.Two minutes after start, then every six hoursThis install: Send usage report to Modbot Cloud
Open instances. Which of your group's instances anyone can join, so they can be listed on modbot.co. See Open instances.Every five minutesThis install: List this group's public instances on modbot.co
Its own log. See Logs.About once a minuteKeep for (days): Send logs to Modbot Cloud
An email address, if somebody ticked Receive emails from Modbot about new features and updates when making an account.OnceLeave the box unticked
ReadsUsed for
The word lists. They are downloaded when you open the shared word lists in Settings → AutoMod, and every six hours for each one you imported. A plain download: nothing about your group is sent.AutoMod
The credits. The names of sponsors and contributors.The credits page

What the report carries:

Your serverIts public address, if you set one; the Modbot version; the operating system and processor it runs on
Your groupIts VRChat id, name, description, icon and banner
ConnectionsWhether a Discord bot token is stored, and whether AutoMod (word lists and AI topics) is switched on
Word listsThe ids of the shared lists you imported, never their contents
TroubleHow many rate-limit cold stops and WAF blocks there have been since the last report

Never how many people anything has. There is no field in the report for the number of users, the number of group members, or the number of people in a VRChat instance, and none for any member, any moderation record, any credential or any log line.

What Cloud keeps. The first report registers your server and gets it a random id. Every report is stored as a row of its own, with the address it came from, and nothing deletes those rows on a schedule. Only Modbot Cloud administrators can read them. See Privacy.

Turning the report off. Send usage report to Modbot Cloud is on when Modbot is installed. With it off nothing is built or sent, and Last report reads Off. A Modbot that has not registered stays unregistered, so it also sends no log, because the log is sent under the id registration makes. Get link code still registers it, sending only the address, the version and the operating system.

Set MODBOT_CLOUD_DISABLED=1 and none of it happens: the switches are greyed out and nothing is sent or read.

One thing it does not stop: checking for a newer Modbot release. That question sends nothing about your deployment — no id, no group, no version — and everyone gets the same answer, so it is not one of the things that variable is protecting you from. The Check for updates switch under Settings, Server is what turns it off, and it is on by default. Modbot never updates itself. See Updating.

Settings → Server, on the This install panel, shows when the last report went, has the switches above and a Get link code button, which you type into cloud.modbot.co to claim this server on your Cloud account. The code lasts 15 minutes and works once; Cloud is told only its SHA-256. Health shows the last report too.

Modbot Cloud also keeps two things your Modbot does not:

  • What my.modbot.co learned about your server's address when somebody opened its register page: your group's id, name, icon and banner, and the email address your Modbot gives out as its owner's, along with the visitor's IP address and when it was seen. Only the project's own admin area can read that email address. Turn off Show the owner's email address in Settings → Server to keep the email out of it.
  • The Modbot mailing list. When somebody registering an account on your Modbot ticks Receive emails from Modbot about new features and updates, your server passes the address to Modbot Cloud, which keeps the address, where it came from, an unsubscribe token and when it was first and last seen. Nothing else about them is kept, and MODBOT_CLOUD_DISABLED=1 stops your server sending it at all.

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