Modbot Docs
Self-hosting

Checking a deployment

The two health check addresses, the Health page, the This install card, log files and Seq.

There are four places to look when you want to know whether your Modbot is working:

  • two health check addresses your hosting platform can call,
  • the Health page in the web app,
  • the This install card in Settings,
  • the logs, which you can read in the app on the Modbot's log page.

Modbot can also email you when something goes wrong, rather than waiting for you to look. See Alerts by email.

Health check addresses

Modbot answers two addresses. Neither needs you to be signed in.

/health/live

Answers Healthy as long as the Modbot process is running. It checks nothing else, on purpose: if it checked the database, a platform would restart Modbot every time the database blinked, which is exactly when you want Modbot up to read the error.

Use it for checks that restart a container that has stopped responding. The Docker image's own health check calls it every 30 seconds.

/health/ready

Answers whether Modbot can reach its database right now. The reply names the check:

{
  "status": "Healthy",
  "checks": {
    "database": {
      "status": "Healthy",
      "description": "Database is reachable."
    }
  }
}

When the database cannot be reached, status is Unhealthy, the description says Database is not reachable., and the HTTP status is 503.

Use it to decide when a new deployment is ready for traffic. Railway's configuration for Modbot uses this one, with a 300 second timeout. See Railway.

Nothing answers during startup

Modbot updates its database tables before it starts listening. Until that is done, neither address answers. On a first deploy this can take a little while. See PostgreSQL.

The Health page

Health opens from the status rows at the bottom of the sidebar. You need the See the operational log permission, which is also what makes those rows appear.

Each row is a part of Modbot and one word for how it is doing: VRChat, Discord, Database, Sync, and AI once this deployment is using it. Clicking a row opens this page at that part's card.

The page refreshes itself every 20 seconds. It is a stack of cards. Five are always there — VRChat, Database, What Modbot reads, VRChat request limits and Kinds of audit log entry Modbot does not know. The rest appear only when they have something to say, so a Modbot with nothing wrong shows a short page. From top to bottom:

Demo data

Only on a demo Modbot, and only while it is still building its example data. It shows how far it has got.

Alerts

One row for each thing Modbot is currently unhappy about. Nothing is shown when there is nothing.

VRChat

Whether Modbot is reaching VRChat, as one of:

StatusWhat it means
WorkingRequests are going through.
Waiting on purposeModbot has stopped sending for a while: it is waiting out a rate limit, or waiting before it may sign in again. It recovers by itself. Do not restart Modbot to hurry it.
Needs youSomething will not fix itself: Cloudflare is blocking this host, the VRChat account cannot read the group, or a kind of request has stopped after being rate limited again and again. The line below says which.
Not configuredNo VRChat account has been set up yet.

Under it: Last signed in, Sign-ins this hour (out of the limit Modbot allows itself), and Next sign-in when Modbot is waiting before it may sign in again.

To change the VRChat account or the proxy, go to Settings, Modbot's VRChat login.

Database

Whether Modbot can reach its database: online, or unreachable when the process is up and the database is not. It is the same answer /health/ready gives.

Under it, Sync is not running in this process. appears when this copy of Modbot answers the web app but does not read from VRChat.

AI spend

Shown only when an AI spending limit is close or reached. See Limits and spend.

AI

Shown when AI calls have been failing, timing out or falling back in the last hour: how many calls there were, how many failed, how many timed out, how many used the backup model, and which model is answering now.

Email

Shown when any email is queued or has failed: how many are waiting, when the next one goes, and how many failed. See The email limit.

Modbot's log

Stored says whether log lines are being written to the database, how many have been written, and how many were dropped. To Modbot Cloud says Off, or when the last batch was sent, how many are waiting and how many were dropped. See Logs.

Discord bot

Shown when relevant. The bot is not set up, connecting, working, reconnecting, or stopped — needs you. When something is wrong it lists channels the bot cannot post in and the Discord permissions it is missing, and Intents off in the Developer Portal if Discord is not sending it what it needs. See Setting up the bot.

Calendar

Shown only when a planned event failed to reach VRChat's calendar or Discord, or its instance did not open, or a place an event wants is Not set up (no managed group or VRChat account for VRChat, no server id or no connected bot for Discord). A Missing Create Events, Missing Manage Events or Missing Create Events and Manage Events line in the Discord bot card means an event wants a Discord event and the bot cannot make one. See Calendar.

Paused moderation rules

One row for each AutoMod rule that has stopped itself, with the reason and how long ago. See If a rule runs away.

What Modbot reads

The jobs that read from VRChat: Group audit log, Group info, User profiles, User details, Member list and Ban list. Each says when it was last checked and how its last run went. A line underneath says whether the audit log catch-up has finished, and how far it has read.

Modbot Cloud

Whether this Modbot's usage report reached Modbot Cloud: Sent, Failed or Not sent yet, with when it went, the address it used, and the reason if it failed. It says Off when Send usage report to Modbot Cloud in Settings, Server is switched off. The part is left out when MODBOT_CLOUD_DISABLED is set.

VRChat request limits

One row per kind of VRChat request: Limit names it, Requests a second is its current rate, Speed is its pace as a multiple of the normal one (below 1.00× when Modbot has slowed it down), Times refused is how many times VRChat has said "too many requests", and State is running, stopped (paused until the time shown) or given up, needs you.

Kinds of audit log entry Modbot does not know

Kinds of entry from your group's audit log that Modbot has no meaning for yet, with how many it has seen. None seen. is the normal answer.

The This install card

Settings, Server, This install describes what is running. The Server tab needs the Change settings permission.

RowWhat it shows
VersionThe release version, as year.month.patch.
Version commitThe first 7 characters of the git commit the build came from. Point at it to see the whole id. Unknown if the build was not told.
Release branchThe branch the build came from, or Unknown.
HostThe hosting platform Modbot recognised, such as Railway, or self-hosted.
Log filesWritten to disk, or Console and Seq only if the log directory cannot be written to.

When you report a problem, include the version and the commit.

Logs

The console

Modbot prints its main log to the console at Information level and above. This is what your hosting platform's log view shows, and what docker logs shows. The first lines of every start say which port Modbot is using, which host it thinks it is on, and whether its log directory has survived a restart. After that it is the record of what Modbot did — syncs, moderation, settings changed.

A request that failed or answered a 5xx is a warning and is always shown. The rest are at Debug, along with the database queries, so set LOG_LEVEL=Debug for a line per request with the method, path, status and how long it took. See Logs.

CONSOLE_LOG_MODE chooses the shape: serilog for readable lines (the default), json for Serilog's compact JSON, and railway_json for the JSON Railway parses into structured logs. LOG_LEVEL sets the lowest level written. See Console log modes.

Log files

Modbot writes log files into /app/logs in the container. Every start gets its own files, named with the date and the start time:

FileWhat is in it
modbot_log_<date>_<time>.txt and .jsonlThe main record, Information level and above.
modbot_log_http_<date>_<time>.txt and .jsonlOnly the requests Modbot sends to outside services, such as VRChat.
modbot_log_debug_<date>_<time>.txt and .jsonlEverything, in detail. Only written when MODBOT_DEBUG_LOGGING is on.

The .txt files are for reading. The .jsonl files hold the same events with every detail kept separately, for searching with a tool.

A file starts a new part when it reaches 64 MB. Modbot keeps the newest 60 main files, 60 HTTP files and 6 debug files, and deletes older ones.

Files that do not survive. On a platform that throws the container's disk away on redeploy, these files go with it. Modbot writes them anyway and logs a warning at startup, because you may have mounted a volume it cannot see yet. Once a restart shows the directory lasted, the warning stops. To keep logs, mount a volume at /app/logs or set SEQ_URL.

Files that cannot be written. If /app/logs cannot be written to, Modbot writes no files, logs Log files are not being written., and the Log files row says Console and Seq only.

Seq

Set SEQ_URL to the address of a Seq server and Modbot sends its logs there as well, with every detail searchable. This is the one logging setting kept outside the database, because it is how you find out why Modbot cannot reach its database. With MODBOT_DEBUG_LOGGING on, Seq also gets the Debug detail.

See Environment variables.

The database

Modbot also keeps the same lines in its own database, and the Modbot's log page in the app reads them, so a deployment with no Seq and no disk can still search its log. See Logs.

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