Modbot Docs
Self-hosting

Docker

Building the Modbot image from the repository and running it next to PostgreSQL and Seq with docker run or Docker Compose.

Modbot is one container plus a PostgreSQL database. Pull the published image, or build it yourself from the Dockerfile at the root of the repository, then run it with DATABASE_URL pointing at your database.

This page is the long way round, and every step of it is yours to change. The install script does the same thing in one command if you would rather not.

What the image needs

DATABASE_URLRequired. Where the database is, as postgres://user:password@host:5432/database or a keyword connection string. See PostgreSQL.
PORTOptional. The port Modbot listens on inside the container. Defaults to 8080.
Port 8080Publish it (or whatever you set PORT to) so you can reach the web app.
/app/logsWhere log files are written. Mount a volume here if you want to keep them when the container is replaced.
/health/liveAnswers while the process is running. The image's own Docker health check uses it.
/health/readyAnswers healthy only when Modbot can reach its database.

Every other setting is entered in the web app and stored in the database. See Environment variables for the few optional ones.

Run one Modbot container per database. Modbot holds one VRChat session and paces its own requests, and a second container would send twice as many against the same rate limit.

Pull the published image

Every named release is published to GitHub's container registry as ghcr.io/modbot/modbot:

TagWhat it is
latestThe newest release. This is the one to run a group on.
latest-previewThe newest preview: a build handed out for testing before it is released. Try it on a spare Modbot, not on the one your group depends on. latest never points at a preview.
v2026.9.1One release, by its version. A preview version has -preview.1 on the end, as in v2026.9.3-preview.1.
edgeThe newest commit on master, ahead of any release.
sha-1af5e1aOne commit.
docker pull ghcr.io/modbot/modbot:latest

Every tag serves both linux/amd64 and linux/arm64, so docker pull gets a working image on an Intel or AMD machine, on an Apple Silicon Mac, on an arm64 server and on a Raspberry Pi alike. For a Pi, see Small machines.

While the image is private, sign in first with a GitHub token that has the read:packages scope:

echo "$GITHUB_TOKEN" | docker login ghcr.io -u your-github-username --password-stdin

Wherever the rest of this page says modbot, the published image is ghcr.io/modbot/modbot with the tag you chose.

Build the image

The build needs the whole repository, because the image contains both the server and the web app. Run this from the root of a copy of the repository:

git clone https://github.com/Modbot/Modbot.git
cd Modbot
docker build -t modbot .

The This install card in Settings shows the commit and branch the image was built from (point at Version), if the build is told. A plain docker build has no access to git, so pass them in if you want them shown:

docker build -t modbot \
  --build-arg RAILWAY_GIT_COMMIT_SHA="$(git rev-parse HEAD)" \
  --build-arg RAILWAY_GIT_BRANCH="$(git rev-parse --abbrev-ref HEAD)" \
  .

The build arguments have Railway in their names because Railway sets them automatically. They work the same anywhere.

Run it with docker run

This creates a private network, a PostgreSQL 16 database with its own volume, and Modbot:

docker network create modbot

docker run -d --name modbot-db --network modbot \
  -e POSTGRES_USER=modbot \
  -e POSTGRES_PASSWORD=choose-a-long-password \
  -e POSTGRES_DB=modbot \
  -v modbot-db:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:16-alpine

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 \
  -v modbot-data:/app/data \
  --restart unless-stopped \
  modbot

Modbot can start before the database is ready. It tries to connect up to 10 times, 3 seconds apart, before giving up.

Run it with Docker Compose

The repository ships docker-compose.yml in its root. It runs Modbot, PostgreSQL 16 and Seq together, with a volume for each:

ServiceVolumeHolds
modbotmodbot-logs → /app/logsLog files
modbotmodbot-data → /app/dataEvidence, when it is stored on disk (/app/data/evidence)
postgrespostgres-dataThe database
seqseq-dataSeq's stored logs and settings

Copy .env.example to .env, set POSTGRES_PASSWORD and SEQ_ADMIN_PASSWORD, then start it:

cp .env.example .env
docker compose up -d --build
  • Modbot waits until the database is ready before starting.
  • Modbot is at http://localhost:8080, from the same computer only, like Seq. To publish it on a different port, set MODBOT_PORT in .env. A reverse proxy running on the same computer reaches it as it is. To open it to other computers, which a proxy in its own container or on another machine needs, set MODBOT_BIND=0.0.0.0 in .env.
  • Seq is at http://localhost:5380, reachable from the same computer only. Sign in as admin with SEQ_ADMIN_PASSWORD. Seq reads it only the first time it starts with an empty volume. Modbot sends its logs to Seq over the Compose network.
  • The database connection uses the keyword form, so the password needs no escaping, but it must not contain ;.
  • .env also takes these optional settings:
    • MODBOT_DEBUG_LOGGING
    • CONSOLE_LOG_MODE and LOG_LEVEL, covered in Console log modes
    • MODBOT_CLOUD_ENDPOINT
    • MODBOT_CLOUD_DISABLED
    • MODBOT_DEMO and MODBOT_DEMO_RESET_HOURS, to run this Modbot as a public demo
    • MODBOT_SETUP_CODE, to choose the setup code yourself
    • MODBOT_COMMIT and MODBOT_BRANCH, to show the version commit and release branch in Settings

Open it

Open http://localhost:8080 on the same computer. A new Modbot sends you to the setup wizard, whose first step asks for the setup code Modbot prints to its log:

docker compose logs modbot | grep "Setup code"   # Docker Compose
docker logs modbot | grep "Setup code"           # docker run

Use HTTPS from anywhere but localhost

Modbot's sign-in cookie is marked secure, so browsers only keep it over HTTPS. Browsers make an exception for localhost. To reach Modbot from any other address, put a reverse proxy that provides HTTPS in front of it. The proxy must also pass WebSocket connections through if you use live events over WebSocket.

Logs

The container prints its log to the console, so docker logs modbot shows it. It also writes log files to /app/logs. With the volume above, those files survive when the container is replaced. See Checking a deployment.

Keeping evidence on disk

If you choose A directory on disk for evidence under Settings, Evidence, the default directory is /app/data/evidence. Mount a volume there, or the files are lost when the container is replaced.

Add -v modbot-data:/app/data to the docker run command for Modbot; the Compose file already mounts it. The image creates /app/data owned by the container's user, so a new named volume there can be written to straight away.

A volume created by an older image, or a host folder mounted instead, may belong to root. If Test and save says the directory cannot be written, give it to the container's user:

docker run --rm -v modbot-data:/data alpine \
  chown -R "$(docker run --rm --entrypoint id modbot -u)":0 /data

Then recreate the container. See Storage buckets for the other choices.

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