Modbot Docs
Self-hosting

Updating

How to update a self-hosted Modbot, what happens to the database when the new version starts, and what the version numbers mean.

Updating Modbot means running a newer build of the server image against the same database. There is no update command and no database step for you to run: the new version updates the database's tables itself when it starts.

How you find out there is one

Modbot checks for a newer release a minute after it starts and every six hours after that, and shows what it found on the This install card under Settings, Server:

RowWhat it is
VersionThe release this server is running. Point at it to see the exact commit and branch.
InstallThe hosting platform Modbot recognised, such as Railway, or self-hosted.
NewestThe newest release there is.
PullThe image and tag to pull, shown only when there is a newer release.

Modbot never updates itself. It never pulls an image, never restarts itself and never touches your host. It tells you a newer version exists and what to pull; everything below is yours to do when it suits you.

The question goes to cloud.modbot.co. Nothing about your deployment is sent — no id, no group, no version, no account — and nothing is recorded: everyone gets the same answer out of one cached copy. For that reason MODBOT_CLOUD_DISABLED does not turn it off; that variable turns off the things that do send something, and an operator who turned those off should still hear about a security fix. The Check for updates switch on the same card is what turns it off, and turning it off clears what Modbot last heard.

If a check fails, the card shows why and keeps the version it last heard of, because "we could not ask today" is not "you are up to date".

Before you update

Take a backup of the database. The new version may change its tables when it starts, and going back to an older version does not undo those changes. See PostgreSQL.

Note the Version on the This install card under Settings, Server — point at it to see the commit — so you can tell afterwards that the update took.

Updating on Railway

Deploy the newer commit of the repository to your Modbot service, the same way it was deployed the first time. If your service is connected to your own fork, bring the fork up to date first.

Railway builds the image and starts the new deployment. It counts as healthy once /health/ready answers, which only happens after the database has been updated. With the 300 second timeout from Modbot's Railway configuration, a slow update is not mistaken for a failed one. See Railway.

Updating with Docker

If you set Modbot up with the install script, go to the folder it wrote and pull:

docker compose pull
docker compose up -d

With the published image, pull the newer tag and replace the container:

docker pull ghcr.io/modbot/modbot:latest
docker stop modbot && docker rm modbot
docker run -d --name modbot --network modbot   -e DATABASE_URL=postgres://modbot:choose-a-long-password@modbot-db:5432/modbot   -p 8080:8080   -v modbot-logs:/app/logs   --restart unless-stopped   ghcr.io/modbot/modbot:latest

To move to one release and stay on it, use its version as the tag instead of latest. See Docker for the tags.

With an image you built yourself, get the newer code, build it again, and replace the container:

git pull
docker build -t modbot .
docker stop modbot && docker rm modbot
docker run -d --name modbot --network modbot \
  -e DATABASE_URL=postgres://modbot:choose-a-long-password@modbot-db:5432/modbot \
  -p 8080:8080 \
  -v modbot-logs:/app/logs \
  --restart unless-stopped \
  modbot

Use the same docker run options you started it with the first time, including any volume for evidence. With Docker Compose it is:

git pull
docker compose up -d --build

Your data is in the database's volume, so replacing the Modbot container loses nothing. See Docker.

What happens when the new version starts

  1. Modbot connects to the database, waiting for it if needed.
  2. It compares the database's tables with what this version expects. If they match, the log says Database schema is up to date. If not, it logs how many changes it is applying, and applies them.
  3. Only then does it start answering requests and health checks.

If applying the changes fails, the new version logs why in one sentence and does not start. It will not run against a half-updated database. Restore your backup, or fix the cause named in the log and start it again.

Version numbers

Modbot has two version numbers, and they answer different questions.

The release version

A calendar version, year.month.patch, such as 2026.9.1:

  • the year and the month the release was made,
  • a patch number that starts again at 0 each month.

The parts are not padded with zeros, so compare them part by part as numbers: 2026.9.10 is newer than 2026.9.2.

It is shown as Version on the This install card, and returned by GET /api/version, which needs no sign-in.

An image built with the repository's Dockerfile does not set a release number, so Version shows the default written in the source at that commit. Pointing at Version shows the exact commit you are running.

The API version

A whole number that only goes up when something the companion depends on changes in a way older clients cannot handle. It does not change with every release.

Each server speaks a range of API versions, not just one. GET /api/version returns it:

{
  "version": "2026.9.0",
  "apiVersion": 1,
  "apiVersionMinimum": 1
}

A companion picks the highest version both sides speak. The project's rule is that a server keeps speaking the current API version and at least the two before it, and never drops one less than 12 months old. That is why installing the newest companion is always the right choice, even for a moderator whose groups run Modbots on different versions.

If a client and a server have no version in common, the client is told This server speaks API versions followed by the range.

The companion updates separately

Updating your server does not update anyone's companion. Because servers speak a range of API versions, a client does not need to match the server's release. The client checks for its own updates. See Installing the companion.

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