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 for | Where you set it up | |
|---|---|---|
| Evidence storage | Keeping 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 bot | Posting 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 provider | AI moderation rules, insights and chat. | Settings, AI tab. See AI settings. |
| A proxy | Reaching 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. |
| Seq | Sending 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
Install script
One command on a machine with a shell. Installs Docker if it is missing and starts Modbot and its database.
Railway
The service and a Postgres database, with the health check and variables already wired.
Docker
Build the image and run it next to PostgreSQL on your own machine or server.
Small machines
A Raspberry Pi or a small VPS: what it needs, what to set on the database, and what it uses.
curl -fsSL https://modbot.co/get.sh | shAfter 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/serverwhat 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:
| Sends | How often | Switch in Settings → Server |
|---|---|---|
| A report. The fields below. | Two minutes after start, then every six hours | This 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 minutes | This install: List this group's public instances on modbot.co |
| Its own log. See Logs. | About once a minute | Keep 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. | Once | Leave the box unticked |
| Reads | Used 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 server | Its public address, if you set one; the Modbot version; the operating system and processor it runs on |
| Your group | Its VRChat id, name, description, icon and banner |
| Connections | Whether a Discord bot token is stored, and whether AutoMod (word lists and AI topics) is switched on |
| Word lists | The ids of the shared lists you imported, never their contents |
| Trouble | How 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=1stops your server sending it at all.