Modbot Docs

The setup wizard

Every step Modbot walks you through the first time you open it, what each one checks, and who can come back to it later.

The first time you open a new Modbot, it sends you to /setup: a wizard of six steps that connects Modbot to VRChat and to your group. Nothing here is set with environment variables; every answer is stored in Modbot's database.

StepTitle on screenRequired
1Create your administrator accountYes
2Connect a VRChat accountYes
3Check the connectionYes
4Link your VRChat accountYes
5Choose the group to manageYes
6Public address, Discord and emailNo

Press Continue (or Enter) to move on, and Back to return to an earlier step. If you close the browser part way through, Modbot remembers what is done and opens the wizard at the first step that is not.

The setup code

Until the administrator account exists there is nobody to sign in as, so step 1 asks for a setup code instead. Modbot prints it to its log each time it starts without an account:

Setup code: 7KXM-P2QD-RW4H

It is there so that the first person to reach a new Modbot's address cannot take it over by being first: only someone who can read the server's log can create the account.

Where Modbot runsHow to see the code
Docker Compose, or the install scriptdocker compose logs modbot | grep "Setup code" in the folder with docker-compose.yml
docker rundocker logs modbot | grep "Setup code"
RailwayThe deployment's logs. Search for Setup code.
  • It is only printed to the console. It is not in the log files, not in Seq, not on the Modbot's log page and not in anything sent to Modbot Cloud.
  • Capitals, spaces and dashes do not matter when you type it.
  • A restart before the account exists prints a new code, and the old one stops working.
  • To choose the code yourself instead, set MODBOT_SETUP_CODE on the server. It then stays the same across restarts. See Environment variables.
  • Once the administrator account exists, the code is not asked for again: the wizard needs you to be signed in instead.

Before you start

Have these ready:

  • The setup code from Modbot's log. See The setup code.
  • A VRChat account for Modbot to use. Use a dedicated account, not your personal one. Modbot signs in as this account and reads your group through it.
  • That account's two-factor secret, if two-factor authentication is on. This is the text code you are shown when you set up an authenticator app, not the 6-digit code the app shows.
  • That account in your group, with a role that has at least one of the group permissions listed in step 5.
  • Your own VRChat account, to link to your administrator account in step 4.

1. Create your administrator account

FieldNotes
Setup codeThe code from Modbot's log. See The setup code. Only asked for while no account exists. A wrong one shows Wrong setup code.
UsernameOne of the two things you can sign in with. Up to 64 characters. Not case-sensitive.
EmailThe other. Required, and no two accounts can share one. Modbot includes this first account's address in how it identifies itself to VRChat on every request, so VRChat has someone to contact; it is also shown as this server's owner, which you can turn off under Settings, Server, Public address. Password reset links for this account go here.
PasswordAt least 12 characters. There are no other rules, so a long phrase is best.
Confirm passwordMust match.
Receive emails from Modbot about new features and updatesOptional, off unless you tick it. Ticking it sends your address to Modbot Cloud, which sends the mail. Not shown if this Modbot has Modbot Cloud switched off.

The first account gets the Administrator role, which allows everything, and you are signed in straight away.

If two people open a new Modbot at the same moment, only one administrator account is created.

2. Connect a VRChat account

This is the account Modbot acts as.

FieldNotes
Email or usernameThe VRChat account's email address or username.
PasswordThe VRChat account's password.
Two-factor secretOnly if the account has two-factor authentication. Spaces are fine; Modbot removes them.

When you press Continue, Modbot signs in to VRChat with these details right away, so a problem shows up now rather than hours later.

Modbot keeps the details, encrypted, even when the sign-in fails. That way, if the problem turns out to be your network rather than the password, you can add a proxy in step 3 without typing them again. Pressing Continue again with the same details reuses the session Modbot already has instead of signing in again.

If it fails, you see what went wrong:

MessageWhat to do
VRChat rejected these credentials.Check the account by signing in at vrchat.com, then enter the details again.
VRChat asked for a two-factor code.The account has two-factor authentication. Add its two-factor secret. Modbot runs on its own and cannot ask you for a code.
Cloudflare is blocking this network.Your host's network cannot reach VRChat. This is common on VPS and datacentre hosting, and it is not a problem with your account. Continue to step 3 and add a proxy.
VRChat's address could not be resolved.A DNS problem on your host. A proxy will not help.
The connection timed out.Outgoing HTTPS from your host is being blocked or dropped, or a proxy is not responding.
The connection could not be established.Usually a wrong proxy address or proxy password.
VRChat is rate limiting this account.Wait, then try again. Do not retry over and over; that makes the wait longer.
Waiting to sign in to VRChat.Modbot is waiting before it may sign in again. A banner at the top of the page says how long.

3. Check the connection

This step finds out whether Modbot can reach VRChat from where it is hosted, and whether it needs a proxy to do it.

Press Test connection. The test uses the VRChat session from step 2, so it does not spend another sign-in. The result appears above the button, with how long it took. When it passes, Continue moves on. Until it passes, Continue tells you why it cannot.

Using a proxy

A proxy only helps with one problem: Cloudflare is blocking this network. When the test finds that, the proxy fields open by themselves. For any other failure, a proxy will not help, and the message says so.

To add one, open Use a proxy and fill in:

FieldNotes
Proxy URLStarts with http://, https:// or socks5://, and includes the port, such as http://proxy.example.com:11202.
UsernameIf your proxy needs one.
PasswordIf your proxy needs one. After it is saved the label says stored; leave it empty to keep it.

Then press Test again. The proxy is saved when you test, so what passes is what Modbot uses. Test without the proxy removes it and tests again.

Modbot supports one proxy. The message for a Cloudflare block names iproyal.com as a provider known to work.

You can come back to this later: if your host gets blocked after Modbot has been working, change the proxy under Settings, Modbot's VRChat login, Outgoing address.

This connects your own VRChat account to your administrator account. It is not the account from step 2. Every staff member links their own VRChat account the first time they sign in; this is where you do yours.

  1. Press Open my VRChat profile if you need to find your profile.
  2. Paste your VRChat user id (it starts with usr_) or your profile's address into Your VRChat user id or profile address, and press Continue under the field.
  3. Modbot shows a short code. Press Copy, and put the code in your VRChat bio.
  4. Press Check. Modbot reads your bio through VRChat and confirms the link.

A code lasts 30 minutes and can be checked 6 times, at most once every 10 seconds. The screen shows how many checks are left. Start over lets you enter a different account.

When it says you are linked, press Continue at the bottom. If you press it before the link is confirmed, the wizard says Link your VRChat account first.

5. Choose the group to manage

Modbot lists the groups the step 2 account belongs to where it has at least one of these group permissions:

VRChat group permissionWhat Modbot uses it for
group-members-viewallSeeing the full member list. Without it Modbot cannot sync members at all.
group-audit-viewReading the group's audit log, which is Modbot's main record of what happened.
group-bans-manageReading and applying bans.
group-members-removeRemoving members from the group.

The biggest groups come first. Each shows its name, its id and its member count. If the account is missing some of the permissions in a group, the group says Missing and lists them, so you can see before choosing which features will not work until you grant them.

Choose one group and press Continue. One Modbot manages one group.

If no group qualifies, the wizard says This account is not in any group. or None of your groups qualify. and lists the permissions needed. Give the account a role with them in VRChat, then press Check again.

6. Public address, Discord and email

Everything on this step is optional. A Modbot with none of it is complete.

Public address

Address is the address people use to open your Modbot, such as https://modbot.example.com. Links Modbot sends by email or Discord, such as password reset and invite links, are built from this address and nothing else.

It is filled in for you: with the address you saved before, or on Railway with the domain Railway gave the service, or with the address you have the wizard open at. Check it before you finish. Enter only the start of the address, with no path after the host.

Discord bot

FieldNotes
Bot tokenYour Discord bot's token. Once saved, the label says stored; leave it empty to keep it.
Server IDThe id of your Discord server.

The bot starts shortly after a token is saved, without a restart. See Setting up the bot for creating the bot and the settings that come after.

Email (SMTP)

FieldNotes
HostYour mail server, such as smtp.example.com.
Port587 if you leave it empty.
UsernameFor your mail server.
PasswordFor your mail server.
From addressThe address emails are sent from.

Nothing on this step is tested when you save. Modbot uses TLS for email unless told otherwise. You can check it later with Send a test email under Settings, Email and alerts, Email sending.

Finishing

Finish setup saves this page and finishes the wizard. Skip this step finishes without saving anything on this page.

Modbot will only finish once the VRChat account from step 2 has signed in successfully and a group is chosen. If either is missing, it says which.

The first time you finish, Modbot opens my.modbot.co/register in a new tab. That page saves your Modbot's address in your browser, so you can pick it from a list later, and shows your group's name and pictures — which it checks with your Modbot rather than taking from the link. You can close the tab; your Modbot does not depend on it. See What you run.

Then you land in Modbot. Next steps:

Coming back to the wizard later

Each step can be run again. There are two ways.

In Settings, most steps have a place of their own:

StepIn Settings
VRChat accountModbot's VRChat login, Change the login
Connection check and proxyModbot's VRChat login, Outgoing address
Public addressServer, Public address
Discord botDiscord, Bot
EmailEmail and alerts, Email sending

The wizard itself, by opening /setup on your Modbot's address. This is the place to choose a different group. On a Modbot that is already set up, it opens at the last step; use Back to reach the others, and Back to Modbot to leave. Changing the group points every sync at a different group's data.

Who can do it

  • Before any account exists: anyone who can open the address and has the setup code from Modbot's log.
  • After that: only someone signed in with the Change settings permission, or the Administrator role. Anyone else who opens /setup is asked to sign in.
  • Steps 5 and 6, and finishing, also need that person's own VRChat account to be linked.
  • Seeing what is saved follows the same rule. The web app asks Modbot for setup's state before anyone has signed in, and Modbot answers that with only whether setup is finished, which step is next and the group's name and pictures. The VRChat account's username, the proxy, the Discord and email details and the public address are sent only before the first account exists, and after that only to a signed-in account with Change settings or Administrator.

A signed-in person on a Modbot whose setup was never finished is sent back to the wizard at the first unfinished step.

On a Modbot that already has accounts, step 1 does not replace the administrator. It creates an extra staff account with the Viewer role, and needs the Manage users permission. To add staff, use Users instead. See Staff accounts.

See Roles and permissions for every permission.

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