Modbot Docs
Self-hosting

Environment variables

Every environment variable each Modbot service reads, starting with the server you host yourself.

If you self-host Modbot, the only service you run is the Modbot server (Modbot.Server, built from the Dockerfile at the root of the repository). Its variables are the first section on this page.

The other sections cover the project's own services: my.modbot.co, Modbot Cloud, the landing page and this documentation site. You do not need them to run Modbot. They are listed so the whole project is documented in one place.

The Modbot server

Almost everything is set in the web app and stored in the database. The environment only holds what Modbot needs before it can reach the database, plus a few switches.

VariableRequiredDefaultWhat it does
DATABASE_URLYesnoneWhere the PostgreSQL database is, as postgres://user:password@host:5432/database or a keyword connection string. Modbot refuses to start without it. See PostgreSQL.
PORTNo8080The port to listen on. A missing value, or one that is not a number from 1 to 65535, means 8080.
SEQ_URLNononeA Seq server to send logs to. Useful when the container's disk does not survive a redeploy, and when Modbot cannot reach its database, which is exactly when settings stored in the database cannot help.
CONSOLE_LOG_MODENoserilogThe shape of the console output: serilog, json or railway_json. See Console log modes.
LOG_LEVELNoInformationThe lowest level written anywhere, the Modbot's log page in the app included: Verbose, Debug, Information, Warning, Error or Fatal. An unknown value means Information. Debug adds a line for every request Modbot answered and every database query it ran; see Logs before leaving it there.
MODBOT_DEBUG_LOGGINGNooff1, true, yes or on turns on the Debug log files and sends Debug detail to Seq and to the Modbot's log page, while the console stays at Information. It also brings back the web server's own per-request log lines, which are left out otherwise. LOG_LEVEL wins over it.
MODBOT_CLOUD_ENDPOINTNohttps://cloud.modbot.coThe Modbot Cloud this server talks to for its own use. A value that is not a full http or https address is ignored and the default is used. It is not passed to companions. See Modbot Cloud.
MODBOT_CLOUD_DISABLEDNooff1, true, yes or on: this server does not talk to Modbot Cloud at all. Nothing is reported, no term lists are fetched, no server is registered, no instances are listed on modbot.co, and its own log is not sent there whatever the setting says. It does not change what companions send. It beats each of the switches in Settings, Server (Send usage report to Modbot Cloud, List this group's public instances on modbot.co, Send logs to Modbot Cloud), which are greyed out while it is set; without it, each of those switches turns off its own part. It does not stop Modbot asking what the newest release is, because that sends nothing about your deployment; the Check for updates switch under Settings, Server is what stops that. See Logs and Updating.
MODBOT_MY_URLNohttps://my.modbot.coWhere the server selector is. Every Add to my.modbot.co link Modbot offers points at it. A value that is not a full http or https address means the default. Modbot never calls it; it is only a link.
MODBOT_CORS_ORIGINSNononeOther web addresses allowed to call the API from a browser, as https://tools.example.org, separated by commas, or * for any. They sign in with an API key; the session cookie is never accepted from another address. A value that is not a full http or https address is left out. See Calling from a web page.
MODBOT_DEMONooff1, true, yes or on starts Modbot as a public demo: made-up data, no sign-in, and every visitor is an administrator. Only on a deployment that was never set up — a staff account or a finished setup wizard makes Modbot ignore it, and nothing is seeded or removed. See Demo mode.
MODBOT_DEMO_RESET_HOURSNo24How many hours between automatic resets of the demo's data. 0 never resets. Anything that is not a whole number from 0 to 8760 means 24. Only read when MODBOT_DEMO is on.
MODBOT_SETUP_CODENoa new random one at each startThe code the setup wizard asks for until the first account exists. Unset, Modbot makes one each time it starts without an account and prints it to the console only. Set it when the console is awkward to read on your host. Case, spaces and dashes do not matter. Ignored once an account exists. See The setup code.

The image clears ASPNETCORE_HTTP_PORTS, so PORT is the only port setting.

Read only to fill in a form

Railway sets the first five when you add a bucket to the service. Modbot reads them only to fill in Settings, Evidence, Where evidence is stored while no evidence storage has been chosen. You still confirm and press Test and save. Once storage is saved, these variables are ignored, so changing them later does not move anything.

BUCKET, ENDPOINT, ACCESS_KEY_ID and SECRET_ACCESS_KEY must all be set for the form to be filled in.

VariableFills in
BUCKETBucket
ENDPOINTEndpoint
ACCESS_KEY_IDAccess key id
SECRET_ACCESS_KEYNot shown in the form. Used as the secret access key if you leave Secret access key empty when you first save.
REGIONRegion (optional)
RAILWAY_PUBLIC_DOMAINThe suggested public address in the setup wizard and in Settings, Server, Public address.

Read to describe the deployment

Your hosting platform sets these, not you. Modbot reads them to fill in the This install card under Settings, Server.

VariableUsed for
RAILWAY_GIT_COMMIT_SHA, GITHUB_SHAVersion commit, when the build did not record one
RAILWAY_GIT_BRANCH, GITHUB_HEAD_REF, GITHUB_REF_NAME (with GITHUB_REF_TYPE=branch)Release branch, when the build did not record one
RAILWAY_ENVIRONMENT, RAILWAY_PROJECT_ID, RAILWAY_SERVICE_IDHost: Railway
FLY_APP_NAME, FLY_ALLOC_ID, FLY_MACHINE_IDHost: Fly.io
RENDER, RENDER_SERVICE_ID, RENDER_INSTANCE_IDHost: Render
DYNO, HEROKU_APP_IDHost: Heroku
VERCEL, VERCEL_ENVHost: Vercel
KOYEB_APP_NAME, KOYEB_SERVICE_IDHost: Koyeb
NF_INSTANCE_ID, NF_PROJECT_IDHost: Northflank
K_SERVICE, K_REVISIONHost: Google Cloud Run
CONTAINER_APP_NAME, CONTAINER_APP_REVISIONHost: Azure Container Apps
AWS_APP_RUNNER_SERVICE_IDHost: AWS App Runner
ECS_CONTAINER_METADATA_URI_V4, ECS_CONTAINER_METADATA_URIHost: AWS ECS / Fargate
KUBERNETES_SERVICE_HOSTHost: Kubernetes

When none of them is set, Host shows self-hosted.

The host also decides one default: on every platform above except Kubernetes, Modbot assumes the container's disk is thrown away on redeploy until it sees proof otherwise, and warns about log files and evidence kept on disk. A disk that survives one restart is treated as lasting from then on.

Read to catch a crash that leaves no log

These belong to the .NET runtime, not to Modbot. Set them only while chasing a crash that restarts the service with nothing in the log; Modbot reads them so it can say on every start whether they are on, and so it can make the folder the dump goes into.

VariableDefaultWhat it does
DOTNET_DbgEnableMiniDumpoff1 writes a dump of the whole process when it dies outright — a fatal runtime error, which no log line survives.
DOTNET_DbgMiniDumpNamethe runtime's ownWhere the dump goes. %p becomes the process id. Point it at a mounted volume, or the dump goes with the container.
DOTNET_DbgMiniDumpType11 mini, 2 with the managed heap, 3 triage, 4 the whole process. 2 is the useful one.

A dump is about the size of the memory the service was using, so turn these off again once you have one. See Catching a crash that leaves no log.

Build settings

SettingWhereWhat it does
RAILWAY_GIT_COMMIT_SHA, RAILWAY_GIT_BRANCHDocker build arguments (--build-arg)Recorded as the version commit and release branch. Railway passes them automatically.
ModbotCommit, ModbotBranch.NET build properties (-p:ModbotCommit=...)The same, and they win over everything else. Without them, a local build asks git.
ModbotRelease.NET build property (-p:ModbotRelease=2026.9.0)Stamps the release version, which must look like year.month.patch with no leading zeros. The root Dockerfile does not set it.
ModbotOpenApiDocument.NET build property (-p:ModbotOpenApiDocument=false)Stops the build rewriting docs/openapi/modbot.json, the API description this site's API reference is built from. Docker builds never write it.

Console log modes

CONSOLE_LOG_MODE is read by every part of Modbot: the server, the companion, my.modbot.co, Modbot Cloud and the landing page. LOG_LEVEL is read by all of them except the companion, which has MODBOT_COMPANION_LOG_LEVEL instead. Both are read when the program starts.

CONSOLE_LOG_MODE changes the console only. Log files and Seq are the same in every mode. Capital letters, spaces, hyphens and underscores do not matter, and a value that is not one of the three means serilog.

ValueWhat a line looks like
serilog[12:30:00 INF] Modbot starting on port 8080
json{"@t":"2026-09-15T12:30:00.0000000Z","@mt":"Modbot starting on port {Port}","Port":8080,"Service":"Modbot","Version":"2026.9.0"}
railway_json{"level":"info","logLevel":"Information","timestamp":"2026-09-15T12:30:00.0000000+00:00","message":"Modbot starting on port 8080","Port":8080,"Service":"Modbot","Version":"2026.9.0"}

serilog is a line of readable text, and the default.

json is Serilog's compact format: one object per line, with the message template under @mt, the time under @t, the level under @l and the exception under @x. Anything that reads Serilog's JSON understands it.

railway_json is the shape Railway reads: message is the text of the line, level is one of debug, info, warn or error, and every other key becomes an attribute you can filter on in the log explorer, such as @StatusCode:500. Serilog has six levels and Railway has four, so Verbose arrives as debug and Fatal as error; the exact level is kept as logLevel, which you can filter on as @logLevel:Fatal.

On Railway, use railway_json. On anything else, serilog for reading and json for collecting.

LOG_LEVEL sets the lowest level anything is written at, for every service but the companion. Verbose and Debug also bring back the web server's per-request lines and the database's query lines.

Every line carries Service — which program wrote it — and Version, the release it came from. That is how one Seq server or one log explorer can hold all of them at once.

The web app

The web app (src/Modbot.Web) reads no environment variables. It is built into the Modbot server's image and served by it.

The companion

The Windows client reads these from the PC it runs on, not from the server it is paired with. A server's own MODBOT_CLOUD_ENDPOINT and MODBOT_CLOUD_DISABLED do not reach its clients.

VariableRequiredDefaultWhat it does
MODBOT_COMPANION_LOG_LEVELNoVerboseThe lowest level written to the client's own log in %APPDATA%\Modbot\logs: Verbose, Debug, Information, Warning, Error or Fatal. An unknown value means Verbose. The client uses this and not LOG_LEVEL.
CONSOLE_LOG_MODENoserilogThe shape of what the client prints to the terminal it was started from: serilog, json or railway_json. Its log files are always text. See Console log modes.
MODBOT_CLOUD_ENDPOINTNohttps://cloud.modbot.coWhere the client sends its Modbot Cloud backup. Wins over cloud.endpoint in the client's settings.json. It must be HTTPS, or plain HTTP to the same PC; anything else is ignored and the default is used.
MODBOT_CLOUD_DISABLEDNooff1, true, yes or on turns the client's Modbot Cloud backup off, and 0, false, no or off turns it on. Wins over cloud.disabled in settings.json. Any other value is ignored. It does not stop the client checking for updates; checkForUpdates in its settings.json does.
MODBOT_DEBUG_MODENooffAdds a Debug page to the client's window, which draws the overlay on the desktop and offers sample screens to put in front of it, and keeps the overlay's last frame instead of clearing it. It is for working on the overlay without a headset and changes nothing the client sends.

The client reads them when it starts. See Client settings and Installing the companion.

The project's own services

You do not run these to self-host Modbot.

my.modbot.co

src/Modbot.My, built by src/Modbot.My/Dockerfile from the root of the repository. It has no database: everything it shows comes from Modbot Cloud.

VariableRequiredDefaultWhat it does
MODBOT_CLOUD_API_KEYYesnoneThe key Modbot Cloud accepts — its PROXY_API_KEY. my.modbot.co reads everything from Cloud and refuses to start without it.
MODBOT_CLOUD_PROXY_URLNohttps://cloud.modbot.coThe Modbot Cloud it reads from, as a full http or https address. Anything else means the default.
PORTNo8080Port to listen on. A missing or invalid value means 8080.
SEQ_URLNononeA Seq server to send logs to.
CONSOLE_LOG_MODENoserilogserilog, json or railway_json. See Console log modes.
LOG_LEVELNoInformationVerbose, Debug, Information, Warning, Error or Fatal.

On Railway: leave the root directory empty and set RAILWAY_DOCKERFILE_PATH=src/Modbot.My/Dockerfile.

Modbot Cloud

src/Modbot.Cloud (cloud.modbot.co), built by src/Modbot.Cloud/Dockerfile from the root of the repository.

VariableRequiredDefaultWhat it does
DATABASE_URLYesnoneThe main PostgreSQL database: installs, admin sessions and settings.
DATABASE_ENGINE_URLYesnoneA second, separate PostgreSQL database that stores the events companions back up and the log lines Modbot deployments send.
ROOT_API_KEYNononeThe key that signs in to /admin. Unset means admin is refused to everyone.
INSTANCES_API_KEYNononeThe read-only key for the open instances feed, which is the key the landing page holds. ROOT_API_KEY opens the feed as well; with neither set, the feed is refused to everyone. Its old name, ROOMS_API_KEY, is still read.
PROXY_API_KEYNononeThe key my.modbot.co and the landing page send when they read through Cloud. Unset means /api/v1/site is refused to everyone, so neither of those sites can show anything.
RESEND_API_KEYNononeThe Resend key Cloud's email is sent with. Unset means the checks still run and record what they found, no email goes, and nobody can register. See Alerts by email.
MAIL_FROMOnly with RESEND_API_KEYnoneThe address Cloud's email comes from, such as Modbot <[email protected]>. Setting RESEND_API_KEY without this one stops Cloud starting at all.
CLOUD_PUBLIC_URLNohttps://cloud.modbot.coThe address links in Cloud's email are built from. A value that is not a full http or https address means the default.
GITHUB_TOKENNononeReads the repository's contributors for the showcase every Modbot shows on its Credits page. Not needed once the repository is public; without it while it is private, the contributor list is empty and nothing else changes.
GITHUB_REPOSITORYNononeThe repository those contributors come from, as owner/name.
GITHUB_RELEASES_REPOSITORYNoGITHUB_REPOSITORYThe repository Cloud reads releases from, when they are not in the same one as the contributors.
DOCKER_IMAGENononeThe Docker Hub image whose tags Cloud reads for the update feed.
PORTNo8080Port to listen on. A missing or invalid value means 8080.
SEQ_URLNononeA Seq server to send logs to.
CONSOLE_LOG_MODENoserilogserilog, json or railway_json. See Console log modes.
LOG_LEVELNoInformationVerbose, Debug, Information, Warning, Error or Fatal.

Cloud refuses to start when either database variable is missing, and when RESEND_API_KEY is set without MAIL_FROM. It names each problem in the log and stops before it listens, so a deployment missing one of these restarts over and over rather than coming up half-working. /health/ready checks both databases.

On Railway: leave the root directory empty, set RAILWAY_DOCKERFILE_PATH=src/Modbot.Cloud/Dockerfile, set the health check to /health/ready, and add two Postgres databases, one for each database variable.

The landing page

src/Modbot.Landing (modbot.co), built by src/Modbot.Landing/Dockerfile. It has no database.

VariableRequiredDefaultWhat it does
PORTNo8080Port to listen on. A missing or invalid value means 8080.
MODBOT_CLOUD_PROXY_URLNononeThe Modbot Cloud the /instances page reads from, as a full http or https address. Anything else is ignored.
MODBOT_CLOUD_API_KEYNononeThe key sent to that Cloud — its INSTANCES_API_KEY. It is read on the server and never written into a page.
MODBOT_MY_URLNohttps://my.modbot.coWhere the page's links to the server selector point. A value that is not a full http or https address means the default.
SEQ_URLNononeA Seq server to send logs to.
CONSOLE_LOG_MODENoserilogserilog, json or railway_json. See Console log modes.
LOG_LEVELNoInformationVerbose, Debug, Information, Warning, Error or Fatal.

With either of the two Cloud variables unset, /instances says no groups are listed and Cloud is never asked.

On Railway: leave the root directory empty, set RAILWAY_DOCKERFILE_PATH=src/Modbot.Landing/Dockerfile, and set the health check to /health/ready.

This documentation site

Built from docs/Dockerfile.

VariableRequiredDefaultWhat it does
PORTNo8080Port to listen on. Its health check path is /health.

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