Modbot Docs
Companion

Client settings

Every setting in the companion, including starting with Windows, the voice, Modbot Cloud backup, and the ones kept in its settings file.

The client's Settings page has the start-with-Windows switch, the Close to tray box, the Tell me about, Voice, Clips, Listening and Talk in Discord or VRChat cards, and the VRChat log folder. The rest is set in the client's settings file or in environment variables on your PC.

Nothing on this page is sent to any server. These settings decide what the client does on your PC.

Voice

Off by default. With Voice on, the client says out loud what it sees, so a moderator in a headset hears it rather than having to look at the overlay. The speech is made on your PC by a small open-source text-to-speech engine that runs inside the client; nothing you hear, and nothing about who joined, is sent anywhere to make it.

What it says is the Voice column of Tell me about:

KindWhat is saidWhere it comes from
JoinedRin joined your world. Several people arriving together become Rin and Kai joined your world, or five people joined your world.The client's own reading of VRChat's log, the same events the Audit Log page shows.
Already thereRin was already in your world when you arrived, folded together the same way.The same.
LeftRin left your world, folded together the same way.The same.
Changed avatarRin switched to the avatar “Tall Cat”.The same.
Flagged joinFlagged user Rin joined.Your group's server, when it raises the same alert the overlay shows as a card. Only for the instance you are in.
Log stoppedVRChat's log stopped while you were in this world.The client, when VRChat stops writing and it can no longer see who is there.
ProblemCat Lounge rejected this device. Modbot has stopped reporting to it.The client, when a paired server rejects its token and reporting has stopped.

A fresh client says joins, leaves, flagged joins and problems, and keeps quiet about the rest.

It never announces you. It says nothing while reporting to any server is paused, and drops anything it did not get to within a few seconds rather than reading out old news. Lines never play over each other.

Volume is 0 to 100. Test speaks one line.

Voice is who speaks: Bella, Nicole, Sarah, Sky, Adam, Michael, Emma, Isabella, George or Lewis. All ten come in the one download, so changing your mind costs nothing and fetches nothing. A fresh client speaks as Bella.

Output device lists every output on your PC. Windows default (or System default on Linux) follows whatever your operating system currently uses, and moves with it when that changes, the way a voice chat program does. Pick a device and the client remembers it by its id; if it is not plugged in when a line is due, the line plays on the default instead, the client's log says so, and the device is used again as soon as it is back.

The one download

The first time you turn the voice on or press Test, the client downloads the voice, once, from the sherpa-onnx project's release on GitHub:

VoiceKokoro 82M, version 0.19, English: ten voices in one file, Apache-2.0
Fromhttps://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-en-v0_19.tar.bz2
Size319,625,534 bytes to download (about 305 MB); about 353 MB unpacked
SHA-256912804855a04745fa77a30be545b3f9a5d15c4d66db00b88cbcd4921df605ac7
Kept in%APPDATA%\Modbot\voices

The request carries nothing: no token, no id, nothing about you or your pairings. GitHub sees your IP address, as it does for any download. A file whose size or SHA-256 does not match the one above is thrown away, and the Voice card says so. The voice is not part of the installer, so a client that never has the voice turned on never fetches it. The card shows the download's progress and the size it is working through, and then Voice ready.

Clients before 2026-09-18 spoke with a smaller voice, en_US-kristin-medium from the Piper project, which did not sound good enough. A client that has it fetches the new one the next time the voice is turned on or Test is pressed, and deletes the old one once the new one is in place — not before, so a download that fails leaves your PC as it was. While that is happening the card says Getting the new voice.

On a PC with no sound output, or a Linux PC without OpenAL's library, the card says so and the voice cannot speak; everything else in the client is unaffected.

The voice settings are kept in the settings file's voice object, listed below.

Modbot Cloud backup

On by default. The client sends a copy of its presence events to Modbot Cloud, for every instance you are in. Separately, each group's Modbot still gets only its own group's instances, at the address you paired with. The two never mix.

This does not send VRChat's log. It sends the events the client builds from the log, the same ones described in What it sends to your group's Modbot:

  • someone joined, was already there when you arrived, left, or changed avatar, and VRChat's log stopping while you were in an instance;
  • for each: a random event id, the time, the person's VRChat user id and display name, the world id and instance id, the avatar's name for an avatar change, and the group that owns the instance.

The differences from what a Modbot server gets:

  • It covers public, friends-only and private instances too. For an instance that belongs to no group, the group is left empty.
  • It works the same whether the client is paired with no server, one, or several. A paired server has no say in where it goes or whether it is sent.
  • Pausing a paired server does not pause it. Pausing stops the client reporting to that server; the backup is a separate flow and keeps going until it is turned off here.
  • The client's window does not show it. The Audit Log page says what happened to each event's own group's record — sent, waiting, withheld or failed — and nothing about the backup: no line of its own, no state, no filter, and no error if a batch of it fails. What the backup did is in the client's log file and in %APPDATA%\Modbot\sent.jsonl.

It never sends VRChat's raw log, the secret part of an instance's address that would let someone join it, your pairing tokens, the client's own log, your computer's name or your Windows account name.

Each batch also carries a batch id, the client's version, your PC's clock time, and how far your clock is from Cloud's.

Turning it off, or sending it somewhere else

Only the person using the PC can change this, in one of two places:

  • In %APPDATA%\Modbot\settings.json, the cloud field:

    {
      "cloud": {
        "endpoint": "https://cloud.example.org",
        "disabled": true
      }
    }

    Both parts are optional.

  • In Windows environment variables for your account:

    VariableWhat it does
    MODBOT_CLOUD_ENDPOINTThe Modbot Cloud to send to, instead of https://cloud.modbot.co.
    MODBOT_CLOUD_DISABLED1, true, yes or on turns the backup off. 0, false, no or off turns it on.

Which one wins, for the address and for on or off separately:

  1. The environment variable, if it is set.
  2. settings.json, if it has the field.
  3. The default: on, sending to https://cloud.modbot.co.

Things to know:

  • The address must be a full HTTPS address. Plain HTTP is only accepted to your own PC (localhost, 127.0.0.1 or ::1), for testing. Any other address is ignored and https://cloud.modbot.co is used instead. The client's log says when that happens.
  • A value of MODBOT_CLOUD_DISABLED that is not one of the words above is ignored, and settings.json decides.
  • The client reads these when it starts. Quit it from the tray and open it again after changing them.
  • A client that starts with the backup off sends nothing, keeps nothing, and deletes anything left waiting from before. Turning it on again sends only what happens from then on.

How Cloud knows your client

The first time the client sends to a Cloud address, it registers with it, sending only its version and the word windows. Cloud gives back a random install id and a secret. The id is not your name, your VRChat account or your PC. The client keeps both in %APPDATA%\Modbot\cloud-installs.json, with the secret encrypted so only your Windows account can read it, and sends them with every batch. If Cloud stops recognising the install, the client registers again.

Batches, queue and retries

  • Events are gathered into batches. A batch closes at 500 events, 256 KB, or 60 seconds after its first event, whichever comes first, and is sent compressed. A quiet instance sends nothing.
  • While Cloud cannot be reached, events wait: up to 10,000 in memory, then on disk in %APPDATA%\Modbot\cloud, up to 20 MB. When either fills, the oldest are dropped.
  • After a failure the client waits before trying again, a little longer each time up to five minutes, or as long as Cloud asks.
  • A batch Cloud refuses as broken or too large is deleted, not retried.
  • The client only asks Cloud's time when it has something to send, at most every two hours.
  • Cloud backup runs on its own, so a slow or missing Cloud never holds up reporting to your group's server or the overlay.

Modbot Cloud keeps events for 365 days by default. See Privacy.

Start Modbot Companion when my computer starts

On by default, and only shown in a copy installed with Modbot-win-Setup.exe. The portable zip, and a copy you built yourself, do not show this switch and never touch the Windows startup list.

While it is on, Modbot adds itself to your own Windows startup list and starts in the tray, with no window, when you sign in to Windows. The client checks the entry every time it starts and fixes it if needed, so it keeps working after an update.

Turning it off removes the entry. The choice is saved in the settings file as startWithWindows.

If you turn Modbot off in Task Manager → Startup apps, Modbot respects that: it never turns itself back on, and the switch shows off and cannot be changed from the client. Turn it back on in Task Manager if you want it again.

Uninstalling the client removes the startup entry.

Close to tray

A tick box on the Settings page, on by default, shown in every copy. It decides what the window's X button does, and whether the Quit button at the foot of the window asks first.

Close to tray onClose to tray off
The X buttonHides the window. The client keeps running and reporting from the tray.Quits the client.
The Quit buttonAsks first: "Modbot will stop reporting and won't stay in the tray." Choose Quit to quit, or Cancel to carry on.Quits straight away.

Quitting from the window does the same as Quit — stops reporting in the tray menu: everything the client runs is stopped, then it exits. The choice is saved in the settings file as closeToTray; a settings file from before this box existed reads as on.

Settings in the settings file

The client keeps its settings in %APPDATA%\Modbot\settings.json. Every field is optional. The switches and the Voice card write their own fields here, and the rest can only be set by editing the file:

FieldDefaultWhat it does
pairingPagehttps://my.modbot.co/go?redir=/pairThe page Pair with a server opens. See Pairing page.
checkForUpdatestrueWhether an installed client looks for newer versions. See Check for updates.
startWithWindowstrueThe Start Modbot Companion when my computer starts switch.
closeToTraytrueThe Close to tray box. false makes the X button quit.
vrchatLogFolderblankThe VRChat log folder.
overlayOntrueThe Overlay on switch on the SteamVR page. false stops the main headset panel entirely. See Turning it off.
overlayButtonPlacecornerWhere the show and hide button sits, the Button place choice on the SteamVR page: corner or wrist. Anything else is the corner. Whether the panel is hidden is not saved.
overlayButtonOntrueThe Show VR button switch on the SteamVR page and on the Modbot tab in the SteamVR dashboard. false takes the show and hide button out of the headset; the stick shortcut still works. A file without it reads as on.
overlayButtonSpotsnoneWhere you left the button in each place, written when you move it or press Lock or the hand on its bar: a corner and a wrist object, each shaped like the overlay object. A place missing from it, and a file with no such field, start from that place's own spot.
overlayButtonStickrightWhich thumbstick the button's stick shortcut listens to, the Shortcut choice on the SteamVR page: right, left or off. Anything else is the right one.
overlayButtonDirectionbackWhich way that stick is held: back, forward, left or right. Anything else is back. It is kept while the stick is off.
overlayButtonHold5How many seconds the stick is held, the Hold time choice on the SteamVR page. The page offers 2, 3, 5 and 8; the file may say any whole number from 1 to 30, and anything outside is moved to the nearest.
overlayGripSensitivity10How lightly a squeeze takes hold of the panel, the Grip sensitivity slider on the SteamVR page and on the dashboard tab: 1 to 14, the higher the lighter. Anything outside is moved to the nearest.
notifyOverlay.ontrueWhether the notification overlay is drawn. See Notification overlay.
notifyOverlay.spottoprightWhere on the screen it sits: topleft, topmiddle, topright, bottomleft, bottommiddle or bottomright.
notifyOverlay.across0Fine adjustment left or right, in metres, -1 to 1.
notifyOverlay.down0Fine adjustment up or down, in metres, -1 to 1.
notifyOverlay.distance1.0How far ahead of your head it sits, in metres, 0.3 to 3.
notifyOverlay.width0.35How wide the pop-ups are, in metres, 0.1 to 1.5.
notifyOverlay.opacity0.950.1 to 1.
notifyOverlay.seconds6How long one pop-up stays, 2 to 30.
notifyOverlay.placedabsentWhere you put it with a controller, relative to your head. Absent means it sits on its spot.
notifyOverlay.lockedfalseThe lock on its bar.
notifyOverlay.clickThroughfalseThe hand on its bar.
notifyOverlay.wide1How many times wider than ordinary the panel was made with its resize corner, 1 to 2.
notifyOverlay.tall1How many times taller, 1 to 2. A taller panel shows more pop-ups at once.
desktopOverlay.onfalseWhether the window over VRChat is available. See Desktop overlay.
desktopOverlay.shortcutmod+alt+mThe keys that bring it up, mod meaning Ctrl. A combination the client cannot ask Windows for falls back to the default.
desktopOverlay.dictateShortcutabsentThe keys that start and stop Dictate, written the same way. Absent means none; a combination the client cannot ask Windows for is read as none.
desktopOverlay.opacity9020 to 100.
desktopOverlay.lockedfalseThe lock in its strip: the window cannot be dragged.
desktopOverlay.clickThroughfalseThe hand in its strip: clicks on the panel go to VRChat.
desktopOverlay.showButtontrueWhether Modbot's button shows in VRChat's row of key hints.
desktopOverlay.wide, desktopOverlay.tall1How many times wider and taller than ordinary the window was made with its resize corner, 1 to 2.
desktopNotifyOverlay.ontrue on a new install, false if you already had a settings fileWhether notifications appear in a corner of your screen. See Notification overlay on a monitor.
desktopNotifyOverlay.spotbottomrightWhich corner: topleft, topmiddle, topright, bottomleft, bottommiddle or bottomright.
desktopNotifyOverlay.seconds6How long one notification stays, 2 to 30.
desktopNotifyOverlay.wide, desktopNotifyOverlay.tall1How many times wider and taller than ordinary the pop-ups' window was made with its resize corner, 1 to 2.
notifications.bleeptrueWhether a short sound plays when you are told something. See Notification sound.
notifications.volume70The sound's own volume, 0 to 100, separate from the voice's.
notifications.trayNoticesShown0How many times you have been told the client is still in the tray. It stops after three.
notifications.soundabsentA .wav file of your own to play instead of all five of Modbot's sounds. Absent means Modbot's own. See Notification sound.
notificationFilters.popUp["flagged join", "problem"]Which kinds raise a notification, in the headset and on a monitor alike. See Tell me about.
notificationFilters.sound["flagged join", "problem"]Which kinds play the sound.
notificationFilters.voice["joined", "left", "flagged join", "problem"]Which kinds the voice says.
voice.onfalseThe Voice on switch. See Voice.
voice.joinstrueKept in step with notificationFilters.voice, which is what the voice reads. Clients before 2026-09-19 used this.
voice.leavestrueThe same, for left.
voice.flaggedJoinstrueThe same, for flagged join.
voice.volume80Volume, 0 to 100.
voice.outputDeviceabsentThe chosen Output device, by the id the operating system gives it. Absent means the system default.
voice.nameBellaWhich of the download's ten voices speaks. A name that is not one of them falls back to Bella.
cloud.endpointhttps://cloud.modbot.coWhere Modbot Cloud backup goes. MODBOT_CLOUD_ENDPOINT wins over it. See Modbot Cloud backup.
cloud.disabledfalsetrue turns Modbot Cloud backup off. MODBOT_CLOUD_DISABLED wins over it.
clips.onfalseThe Keep the last few minutes, with VRChat's sound switch. Off until you turn it on; nothing is recorded while it is off. See Clips.
clips.minutes3How many minutes are kept, 2 to 10. Anything else is brought inside that range.
clips.discordSoundfalseThe Discord's sound too box. VRChat's sound has no setting of its own — it is what Clips means. Nothing else this PC plays can be recorded, and there is no setting for it. See the sound.
clips.tellServerfalseThe Tell the group's Modbot when I save a clip box. Ticked, saving a clip in a group's instance sends that group's paired server when, where and the file's SHA-256 and size — never the clip. See Telling your group a clip exists.
clips.sendForActionsfalseThe Send clips for my actions automatically box. Ticked, the companion answers your group's Modbot's request for a clip of a ban, kick or warning you made by sending one. Unticked, it answers every request with Clips was off. See Clips for your own actions.
clips.folderabsentWhere saved clips are written. Absent means your Videos folder plus Modbot Clips.
clips.keepGigabytes5How much room saved clips may take before the oldest are deleted, 1 to 200. There is no control for this on the screen.
listenForPhrase.onfalseThe Listen for "Modbot" switch. Off until you turn it on; no microphone is opened while it is off. With it on, saying the name and then clip that, show overlay or hide overlay does those things. See Listening.
listenForPhrase.microphoneabsentWhich microphone to listen on, by Windows' own id for it. Absent means the Windows default, followed wherever Windows moves it. Pick it on the Listening card rather than typing it here.
talk.onfalseThe On switch on the Talk in Discord or VRChat card. Off until you turn it on; nothing is announced to VRChat, no key is pressed and no hotkey is claimed while it is off. See Talk in Discord or VRChat.
talk.discordMuteKeyabsentThe key you recorded for Discord's Toggle Mute, which Modbot presses for you, written the way the other keys here are: f13, mod+shift+m, num0. Absent means none is recorded, and the buttons that need it say so.
talk.discordDeafenKeyabsentThe same for Discord's Toggle Deafen.
talk.swapHotkeyabsentThe hotkey for the Talk in Discord/VRChat button, claimed from Windows while Talk is on. Absent means none. It needs Ctrl or Alt, or must be a function key; anything else is read as not recorded. See On the keyboard.
talk.muteHotkeyabsentThe hotkey for the Discord Mute button, with the same rules.
talk.deafenHotkeyabsentThe hotkey for the Discord Deafen button, with the same rules.

For example:

{
  "pairingPage": "https://modbot.example.org/pair",
  "checkForUpdates": false
}

Quit the client from the tray and open it again after editing the file.

Things to know:

  • If the file is missing, or cannot be read as JSON, every setting in it uses its default. That includes Cloud backup and starting with Windows being on. The environment variables still apply.
  • When you flip a switch, the client changes only that switch's field and leaves the rest of the file as it was; a change on the Voice card rewrites the whole voice object, and the same goes for notifyOverlay, desktopOverlay, desktopNotifyOverlay and notifications. It never writes the cloud field.
  • If the file is broken, the client does not overwrite it. A switch you flip then only lasts until the client restarts.

Pairing page

Set pairingPage to your own server's pairing page, for example https://modbot.example.org/pair, to make Pair with a server go there directly instead of through my.modbot.co.

The address must be HTTPS. Plain HTTP is only accepted to your own PC (localhost, 127.0.0.1 or ::1), for testing. Any other address is ignored and the default is used. The Servers page shows which address the button opens.

You never have to set this: you can always open your server's /pair page in the browser yourself.

Check for updates

Set checkForUpdates to false to stop the client asking for newer versions at all, for example if your group keeps everyone on one version, or the PC must not contact anything it does not have to. Update checks are described under Updates.

This is separate from Modbot Cloud backup: turning the backup off leaves update checks running, and this setting leaves the backup running.

VRChat log folder

Blank means the usual folder: the Windows profile, or on Linux the Proton prefix inside whichever Steam layout the machine has (which ones). The folder the companion is watching is shown under the box and on the Log page. Name a folder to watch that one instead -- a Steam library on another drive, say. It takes effect straight away; a log already in the new folder is treated as history and not reported, the same as at a fresh start. The field in the settings file is vrchatLogFolder.

Client log level

The client writes a detailed log of what it is doing to %APPDATA%\Modbot\logs. To make it write less, set the Windows environment variable MODBOT_COMPANION_LOG_LEVEL for your account, then restart the client:

The values, from most to least: Verbose, Debug, Information, Warning, Error, Fatal. Each writes that level and everything more serious. The default, Verbose, writes everything, including a line each time the client reads new lines from VRChat's log. An unknown value means Verbose. The log never leaves your PC unless you send it to someone.

CONSOLE_LOG_MODE changes the shape of what the client prints to a terminal it was started from — serilog, json or railway_json, described in Console log modes. The log files are always text.

Overlay placement

overlayOn is the switch, and it is a field of its own so that moving the panel never rewrites it. The placement can be set with the panel switched off, so you can arrange it before you turn it on.

The Modbot tab in the SteamVR dashboard writes the same fields as the window: overlayOn, the overlay object's anchor, the whole notifyOverlay object and the popUp list of notificationFilters.

Where the main headset panel sits, set on the SteamVR page or by holding it with a controller, and saved as the overlay object in settings.json:

"overlay": {
  "anchor": "head",
  "offset": { "x": 0.35, "y": -0.28, "z": -1.0, "qx": 0, "qy": 0, "qz": 0, "qw": 1 },
  "width": 0.45,
  "opacity": 1,
  "curve": 0,
  "wide": 1,
  "tall": 1
}
FieldMeansRange
anchorWhat the panel is fixed to: head, lefthand (your left wrist), righthand (your right wrist) or world (left in the room)one of those four
offsetWhere it sits from that anchor: metres as x, y, z, and a turn as qx, qy, qz, qwany
widthHow wide it is in the headset0.12 to 1.5 m
opacityHow solid it is0.1 to 1
curveHow far it wraps around you0 to 1
wide, tallHow many times wider and taller than ordinary it was made with its resize corner; a panel on a wrist is always 11 to 2

A value outside its range is brought inside it when the file is read.

Choosing a wrist moves the panel to the wrist position and sets width to 0.16, and leaving a wrist gives back 0.45 — unless you had chosen a width of your own, which is kept.

The show and hide button is placed by its own field, overlayButtonPlace, not by the overlay object, so moving the panel never moves the button. Show VR button on the SteamVR page, just above Button place, switches the button on or off (overlayButtonOn). Button place, next to Look, chooses Corner (low and to the left of your view) or Wrist (your left wrist), the spot the button starts from. Moving the button yourself is saved per place in overlayButtonSpots. Shortcut and Hold time beside it choose the stick shortcut: overlayButtonStick, overlayButtonDirection and overlayButtonHold.

Notification overlay

A second headset panel, fixed in your view, where pop-ups appear: a flagged arrival, a Modbot fault. It has its own switch and its own placement, and it is drawn whether or not the main panel is. Nothing on it can be tapped except the bar under it.

spot names the corner or edge it sits in; across and down move it from there by a few centimetres; distance is how far ahead of you it floats. seconds is how long one pop-up stays before it fades. On a monitor at most three pop-ups are drawn at once; on the headset three, and more when the pop-up panel is made taller (up to six at twice its height). Older ones fall off the bottom. The pop-ups are drawn in VRChat's look when the headset panel is.

You can also place it with a controller, the same way as the main panel: squeeze the grip on it, carry it, push, pull and resize it, then let go. It stays where you let go of it, still fixed to your view. While it is unlocked a dashed box shows where it is, even with no pop-ups up, so there is something to take hold of; lock it and the box goes. Choosing a spot on the SteamVR page puts it back on that spot, and two quick grips on it send it back to its spot too.

"notifyOverlay": {
  "on": true,
  "spot": "topright",
  "across": 0,
  "down": 0,
  "distance": 1.0,
  "width": 0.35,
  "opacity": 0.95,
  "seconds": 6,
  "wide": 1,
  "tall": 1
}

Desktop overlay

The same roster, events and person card as the headset panel, in a window that sits over VRChat on a monitor. With a VRChat palette selected it is drawn like VRChat's own Users list, with pictures, a banner for your own row and cards. Press the shortcut to bring it up and press it again to send it away, or use the Close button on the window. Escape does not close it, because Escape is how VRChat opens its own menu.

The shortcut is asked of Windows by name, so it works while VRChat has the keyboard. Another program may already own the combination, and then the Desktop overlay card on the Settings page says so and the Open button on that card is the way in.

Write the shortcut with mod for Ctrl, alt for Alt, then the key: mod+alt+m. Shift is not written for a key that prints a character.

The Dictate row on the same card records a second shortcut, one that starts and stops Dictate. It has no default and is written the same way, as dictateShortcut.

"desktopOverlay": {
  "on": false,
  "shortcut": "mod+alt+m",
  "opacity": 90,
  "locked": false,
  "clickThrough": false,
  "showButton": true,
  "wide": 1,
  "tall": 1
}

The lock and the hand in the window's top strip work like the ones under the headset panel: locked, the strip no longer drags the window; with the hand on, clicks on the panel go through to VRChat, while the strip itself still takes clicks so you can turn it back off.

While VRChat's window is showing, the window sits in the free space beside VRChat's Esc menu and follows VRChat's size, and a small Modbot bubble with the shortcut's key sits in VRChat's top-left row of key hints (see The desktop overlay and its bubble). To do that the client asks Windows where VRChat's window is, how big it is and whether it is minimised. It reads no pixels, no keys and nothing from inside VRChat's window, and nothing about it is sent anywhere.

Untick Show Modbot button in VRChat on the Desktop overlay card to hide that bubble, on a monitor and in VR; the shortcut and the overlay keep working.

VRChat in exclusive fullscreen will hide the window. Run VRChat in borderless windowed mode if you want the overlay over it.

Notification overlay on a monitor

Notifications in a corner of your screen, on top of whatever is there: a flagged arrival, a Modbot fault, and anything else you have ticked in the Pop-up column of Tell me about. It has its own switch, and it is separate from the window above — the shortcut does not open it and closing that window does not take it away.

spot is which corner it sits in, on the screen VRChat's window is on while VRChat is open and not minimised, and goes with it if you move VRChat to another screen. With no VRChat window it is on the screen the Modbot window is on. seconds is how long one notification stays. Nothing is drawn while there is nothing to say, and it never takes the keyboard from VRChat. A click where it is goes through to the game, except while the question about installing an update is showing: then a click on the Update and Later buttons is answered here. When Modbot can read the colour palette you picked in VRChat's settings, the notifications are drawn in VRChat's look; when it cannot, in Modbot's own.

It is on when you install Modbot. If you were already running Modbot before 2026-09-19 it stays off until you turn it on, because a window appearing over your screen after an update is not something you asked for. The notification panel in the headset has been on from the start.

"desktopNotifyOverlay": {
  "on": true,
  "spot": "bottomright",
  "seconds": 6,
  "wide": 1,
  "tall": 1
}

Notification sound

A short sound when you are told something, with its own switch and its own volume, separate from the voice. It plays through the same output device the voice uses. The same thing about the same person does not sound twice within half a minute, and nothing sounds again until two seconds after the last sound finished, so a rush of arrivals is one sound rather than ten.

"notifications": {
  "bleep": true,
  "volume": 70,
  "trayNoticesShown": 0
}

trayNoticesShown counts how many times closing the window with the X has told you the client is still running in the tray (only while Close to tray is on). After three it stops. Set it back to 0 to be told again.

Which sound plays for what

There are five, and they are the same instrument saying different things: struck notes that come up softly and decay with a tail, made by the client rather than read from a file, so there is no audio file in the download whose origin anybody has to check.

SoundPlays when
Chime — one soft noteSomebody joined, left, was already there, or changed avatar, if you have ticked those in Tell me about. Also when a clip is saved because you said "Modbot, clip that" and the voice is off.
Alert — two notes, risingYour group's server flagged somebody who has just arrived.
Alert twice — the same, twiceMore than one different flagged person arrived within ten seconds.
Urgent — three notes, climbingA paired server rejected this device so reporting has stopped, or VRChat's log stopped growing so the client can no longer see who is in the instance.
All clear — two quiet notes, fallingNothing yet. It is built and you can hear it with the All clear button, but the client has nothing today that means "this is over".

Nothing needs learning: the sounds get longer, higher and harder struck as the news gets worse. The Urgent one is not louder than Alert — it is exactly the same height — it is brighter and struck faster, which is what your ear reads as urgency.

A more serious sound is allowed to start inside the two-second gap a less serious one left behind it, which is how two flagged people walking in together are heard as two. It only ever goes up, so it cannot run away: a flood of flagged arrivals is about one sound every three seconds. Nothing ever interrupts a sound that is already playing.

The sounds changed on 19 September 2026. Before that there was one, and before that it was two bare sine tones, 880 then 1245 hertz, each switched on and off in six milliseconds — a smoke alarm rather than a notification, and a moderator hearing it forty times an evening said so.

Settings → Notifications → Test has a button for each of the five.

Using a sound of your own

Settings → Notifications → Sound file. Point it at a .wav file on your PC and that plays instead — for all five, not one of them, so you lose the difference between them. Leave it empty, or press Use Modbot's sound, to go back.

  • .wav only. A WAV file is a header and the samples, which the client can read in sixty lines and no extra library. Any program on your machine will save one.
  • Plain WAV, 8, 16, 24 or 32-bit, mono or stereo, at any sample rate. An MP3 renamed to .wav is refused rather than played as noise.
  • At most 10 seconds is played, and files over 16 MB are refused.
  • A file that has gone missing, or that cannot be read, plays Modbot's own sound and says why on the Notifications card. Press one of the Test buttons to see it.

The file is read once and then held, so forty sounds in an evening is one read. It is never copied anywhere and no server is told it exists.

Tell me about

The Tell me about card on the Settings page is one row per kind of event and one tick per way of being told: a pop-up, the notification sound, and the voice.

Pop-up covers both notification overlays — the one in the headset and the one in a corner of your screen — because they are the same choice made once. Each has its own switch, so you can have either, both or neither.

KindPop-upSoundVoiceWhat it is
Joined✓Somebody joined the instance you are in.
Already thereSomebody was already in the instance when you arrived.
Left✓Somebody left the instance you are in.
Changed avatarSomebody in the instance changed avatar.
Flagged join✓✓✓Your group's server raised a flagged-join alert for the instance you are in.
Log stoppedVRChat stopped writing to its log, so the client can no longer see who is there.
Problem✓✓✓A paired server rejected this device, or cannot be reached.

The ticks above are what a fresh client does. The first five kinds come from the client's own reading of VRChat's log — the same events the Audit Log page lists, under the same names. Flagged join comes from your group's server, and Problem from the client itself.

Each way keeps its own switch and its own volume: turning a kind on here does nothing while the sound is off, the voice is off, or both notification overlays are off. Your own arrivals and departures are never announced, whatever is ticked.

The card writes the notificationFilters object:

"notificationFilters": {
  "popUp": ["flagged join", "problem"],
  "sound": ["flagged join", "problem"],
  "voice": ["joined", "left", "flagged join", "problem"]
}

A word the client does not know is ignored rather than breaking the file.

Filtering on who arrived — everybody who is not age verified, say, or everybody who is 18+ verified — is not possible. These ticks choose kinds of event, not people. Your group's server does send each person's trust rank and 18+ mark to the client, and every pop-up about a person shows them once the server has said them, but nothing here decides by them.

Debug mode

Set the environment variable MODBOT_DEBUG_MODE to 1 for your account and restart the client, and the window gains a Debug page:

  • Show overlay window opens a window showing the overlay's last drawn frame: the same picture SteamVR is handed, so you can see the panel without a headset.

  • Look for SteamVR now attaches to a running SteamVR at once.

  • Sample screens pin a made-up screen into the overlay: idle, roster, flagged join or problem. Live lets the real screen back. Samples are built from constants in the client; nothing is fetched or sent for them.

  • Test events make up something happening, so you can try the pop-ups, the sound, the notification overlay and the main panel without waiting for anybody to walk in. Pick a Kind (joined, left, already there, changed avatar, flagged join, moderation row, avatar change row, problem, update ready, or one of the heads-up kinds), give a Name, a Rank and the 18+ tick if you like, and a Reason for a flagged join, a problem or a heads-up (for a moderation row or an avatar change row, the sentence the row says), then press Send. Send a run plays a join, a flagged join, an avatar change and a leave, three seconds apart. Update ready shows the update card with a made-up version; on it Restart now only closes the card, and nothing restarts.

    A test event goes through the same parts of the client a real one does, so your notification ticks still decide which ones pop up. A flagged join, a join, a leave, a moderation row and an avatar change row reach the main panel only while you stand in an instance one of your paired servers covers; anywhere else the pop-up and the sound still come (the two row kinds have neither, so there they show nothing). Each moderation row says it comes from VRChat, Discord or Modbot in turn. Test events send nothing to anybody: no server is told, no server is asked, and nothing is written to the queues, the sent journal, the Cloud backup or settings.json. Tapping a made-up person on the panel opens their card from what the panel already holds, and a heads-up cannot be placed on them.

    Test events do not come from VRChat's log, so they never show on your Events page.

Everything else runs as normal in debug mode, and the setting is read once, at start.

A test copy with its own folder

Set MODBOT_DATA_FOLDER to a folder and the client becomes a test copy that keeps everything there instead of in %APPDATA%\Modbot: settings, pairings, logs, queues, the sent journal, the Cloud backup's batches and the downloaded voice and phrase models. Your real copy's pairings and settings are never touched. A test copy also:

  • leaves modbot-companion:// links to your real copy, so pairing from the browser always reaches that one (pair a test copy by pasting the token);
  • adds nothing to start with Windows and does not look for updates;
  • makes no request of its own: no event backup to Modbot Cloud (whatever settings.json or MODBOT_CLOUD_DISABLED say), no Cloud install, no Credits read, and no voice or phrase model download. Only a server you pair in the test copy itself is ever talked to;
  • has its own one-copy lock, so starting it never hands anything to your real copy;
  • says Test copy in the window's title and the tray icon's tooltip;
  • has a Restart button that does nothing: quit it from the tray and start it again.

It refuses to start if the folder is %APPDATA%\Modbot, sits inside it, or holds it, however the folder is written (a short name, a \\?\ path, or a link or junction to it). It says why in the terminal it was started from, or in a message box when there is no terminal.

Only one copy can own the SteamVR overlay, so quit your real copy before starting a test copy, and quit the test copy before starting the real one again.

Set the variable just for the one start, from a terminal in the folder with Modbot.exe:

$env:MODBOT_DATA_FOLDER = "$env:LOCALAPPDATA\ModbotTest"
$env:MODBOT_DEBUG_MODE = "1"
.\Modbot.exe

The test remote

A test copy started with MODBOT_DEBUG_MODE=1 as well also has a test remote: a way for a program on the same PC, such as a script or a coding assistant, to use the companion's headset panels while you play, with nobody holding the controllers. It can press the SteamVR dashboard tab's controls, point and click on the main panel with a made-up controller, send test events, and read what every panel is showing.

  • It exists only in a test copy in debug mode. Your real copy never has one, and nor does a test copy started without debug mode: nothing listens at all.
  • It is local to your Windows account: a named pipe named after the test copy's folder, which only your account can open (a Unix socket only you can open on Linux). There is no network port, and it never crosses the network.
  • It sends nothing to any server and never starts SteamVR. It refuses to tap a real person's row or card, and Place or Clear on a heads-up; test events only ever make up people. Settings it changes are the test copy's own.

Send it commands with the tool in the repository, giving the test copy's folder:

dotnet run --project tools/modbot-remote -c Release -- "$env:LOCALAPPDATA\ModbotTest" state
dotnet run --project tools/modbot-remote -c Release -- "$env:LOCALAPPDATA\ModbotTest" press "Overlay on"

Each command prints one line of JSON with "ok": true, or "ok": false and an error.

CommandWhat it does
stateWhat each panel shows: the main panel, the notification overlay, the dashboard tab and the desktop overlay, with where each is and the dashboard's controls
press <label>Presses a dashboard tab control by its label, as SteamVR's laser does
slide <label> <0..1>Presses a dashboard slider's track that far along
tap-panel <x> <y>Clicks the main panel at a point of its picture, in pixels
scroll-panel <rows> [x y]Scrolls the main panel's list; negative is up
put-backPut it back in front of me
event <kind> <name> [rank] [18+] [reason]One test event, as the Debug page's Send
run [name] [rank] [18+]The Debug page's Send a run
clear-cardsTakes every pop-up down
grab-panel, move-panel <x> <y> <z>, release-panelHolds the main panel, carries it to a place in front of your head (metres: right, up, back), and lets it go
wait <ms>Waits, up to a minute

The panel and dashboard commands need SteamVR running with the panels attached.

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