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:
| Kind | What is said | Where it comes from |
|---|---|---|
| Joined | Rin 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 there | Rin was already in your world when you arrived, folded together the same way. | The same. |
| Left | Rin left your world, folded together the same way. | The same. |
| Changed avatar | Rin switched to the avatar “Tall Cat”. | The same. |
| Flagged join | Flagged 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 stopped | VRChat's log stopped while you were in this world. | The client, when VRChat stops writing and it can no longer see who is there. |
| Problem | Cat 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:
| Voice | Kokoro 82M, version 0.19, English: ten voices in one file, Apache-2.0 |
| From | https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/kokoro-en-v0_19.tar.bz2 |
| Size | 319,625,534 bytes to download (about 305 MB); about 353 MB unpacked |
| SHA-256 | 912804855a04745fa77a30be545b3f9a5d15c4d66db00b88cbcd4921df605ac7 |
| 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, thecloudfield:{ "cloud": { "endpoint": "https://cloud.example.org", "disabled": true } }Both parts are optional.
-
In Windows environment variables for your account:
Variable What it does MODBOT_CLOUD_ENDPOINTThe Modbot Cloud to send to, instead of https://cloud.modbot.co.MODBOT_CLOUD_DISABLED1,true,yesoronturns the backup off.0,false,nooroffturns it on.
Which one wins, for the address and for on or off separately:
- The environment variable, if it is set.
settings.json, if it has the field.- 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.1or::1), for testing. Any other address is ignored andhttps://cloud.modbot.cois used instead. The client's log says when that happens. - A value of
MODBOT_CLOUD_DISABLEDthat is not one of the words above is ignored, andsettings.jsondecides. - 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 on | Close to tray off | |
|---|---|---|
| The X button | Hides the window. The client keeps running and reporting from the tray. | Quits the client. |
| The Quit button | Asks 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:
| Field | Default | What it does |
|---|---|---|
pairingPage | https://my.modbot.co/go?redir=/pair | The page Pair with a server opens. See Pairing page. |
checkForUpdates | true | Whether an installed client looks for newer versions. See Check for updates. |
startWithWindows | true | The Start Modbot Companion when my computer starts switch. |
closeToTray | true | The Close to tray box. false makes the X button quit. |
vrchatLogFolder | blank | The VRChat log folder. |
overlayOn | true | The Overlay on switch on the SteamVR page. false stops the main headset panel entirely. See Turning it off. |
overlayButtonPlace | corner | Where 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. |
overlayButtonOn | true | The 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. |
overlayButtonSpots | none | Where 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. |
overlayButtonStick | right | Which 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. |
overlayButtonDirection | back | Which way that stick is held: back, forward, left or right. Anything else is back. It is kept while the stick is off. |
overlayButtonHold | 5 | How 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. |
overlayGripSensitivity | 10 | How 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.on | true | Whether the notification overlay is drawn. See Notification overlay. |
notifyOverlay.spot | topright | Where on the screen it sits: topleft, topmiddle, topright, bottomleft, bottommiddle or bottomright. |
notifyOverlay.across | 0 | Fine adjustment left or right, in metres, -1 to 1. |
notifyOverlay.down | 0 | Fine adjustment up or down, in metres, -1 to 1. |
notifyOverlay.distance | 1.0 | How far ahead of your head it sits, in metres, 0.3 to 3. |
notifyOverlay.width | 0.35 | How wide the pop-ups are, in metres, 0.1 to 1.5. |
notifyOverlay.opacity | 0.95 | 0.1 to 1. |
notifyOverlay.seconds | 6 | How long one pop-up stays, 2 to 30. |
notifyOverlay.placed | absent | Where you put it with a controller, relative to your head. Absent means it sits on its spot. |
notifyOverlay.locked | false | The lock on its bar. |
notifyOverlay.clickThrough | false | The hand on its bar. |
notifyOverlay.wide | 1 | How many times wider than ordinary the panel was made with its resize corner, 1 to 2. |
notifyOverlay.tall | 1 | How many times taller, 1 to 2. A taller panel shows more pop-ups at once. |
desktopOverlay.on | false | Whether the window over VRChat is available. See Desktop overlay. |
desktopOverlay.shortcut | mod+alt+m | The keys that bring it up, mod meaning Ctrl. A combination the client cannot ask Windows for falls back to the default. |
desktopOverlay.dictateShortcut | absent | The 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.opacity | 90 | 20 to 100. |
desktopOverlay.locked | false | The lock in its strip: the window cannot be dragged. |
desktopOverlay.clickThrough | false | The hand in its strip: clicks on the panel go to VRChat. |
desktopOverlay.showButton | true | Whether Modbot's button shows in VRChat's row of key hints. |
desktopOverlay.wide, desktopOverlay.tall | 1 | How many times wider and taller than ordinary the window was made with its resize corner, 1 to 2. |
desktopNotifyOverlay.on | true on a new install, false if you already had a settings file | Whether notifications appear in a corner of your screen. See Notification overlay on a monitor. |
desktopNotifyOverlay.spot | bottomright | Which corner: topleft, topmiddle, topright, bottomleft, bottommiddle or bottomright. |
desktopNotifyOverlay.seconds | 6 | How long one notification stays, 2 to 30. |
desktopNotifyOverlay.wide, desktopNotifyOverlay.tall | 1 | How many times wider and taller than ordinary the pop-ups' window was made with its resize corner, 1 to 2. |
notifications.bleep | true | Whether a short sound plays when you are told something. See Notification sound. |
notifications.volume | 70 | The sound's own volume, 0 to 100, separate from the voice's. |
notifications.trayNoticesShown | 0 | How many times you have been told the client is still in the tray. It stops after three. |
notifications.sound | absent | A .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.on | false | The Voice on switch. See Voice. |
voice.joins | true | Kept in step with notificationFilters.voice, which is what the voice reads. Clients before 2026-09-19 used this. |
voice.leaves | true | The same, for left. |
voice.flaggedJoins | true | The same, for flagged join. |
voice.volume | 80 | Volume, 0 to 100. |
voice.outputDevice | absent | The chosen Output device, by the id the operating system gives it. Absent means the system default. |
voice.name | Bella | Which of the download's ten voices speaks. A name that is not one of them falls back to Bella. |
cloud.endpoint | https://cloud.modbot.co | Where Modbot Cloud backup goes. MODBOT_CLOUD_ENDPOINT wins over it. See Modbot Cloud backup. |
cloud.disabled | false | true turns Modbot Cloud backup off. MODBOT_CLOUD_DISABLED wins over it. |
clips.on | false | The 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.minutes | 3 | How many minutes are kept, 2 to 10. Anything else is brought inside that range. |
clips.discordSound | false | The 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.tellServer | false | The 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.sendForActions | false | The 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.folder | absent | Where saved clips are written. Absent means your Videos folder plus Modbot Clips. |
clips.keepGigabytes | 5 | How much room saved clips may take before the oldest are deleted, 1 to 200. There is no control for this on the screen. |
listenForPhrase.on | false | The 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.microphone | absent | Which 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.on | false | The 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.discordMuteKey | absent | The 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.discordDeafenKey | absent | The same for Discord's Toggle Deafen. |
talk.swapHotkey | absent | The 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.muteHotkey | absent | The hotkey for the Discord Mute button, with the same rules. |
talk.deafenHotkey | absent | The 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
voiceobject, and the same goes fornotifyOverlay,desktopOverlay,desktopNotifyOverlayandnotifications. It never writes thecloudfield. - 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
}| Field | Means | Range |
|---|---|---|
anchor | What the panel is fixed to: head, lefthand (your left wrist), righthand (your right wrist) or world (left in the room) | one of those four |
offset | Where it sits from that anchor: metres as x, y, z, and a turn as qx, qy, qz, qw | any |
width | How wide it is in the headset | 0.12 to 1.5 m |
opacity | How solid it is | 0.1 to 1 |
curve | How far it wraps around you | 0 to 1 |
wide, tall | How many times wider and taller than ordinary it was made with its resize corner; a panel on a wrist is always 1 | 1 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.
| Sound | Plays when |
|---|---|
| Chime — one soft note | Somebody 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, rising | Your group's server flagged somebody who has just arrived. |
| Alert twice — the same, twice | More than one different flagged person arrived within ten seconds. |
| Urgent — three notes, climbing | A 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, falling | Nothing 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.
.wavonly. 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
.wavis 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.
| Kind | Pop-up | Sound | Voice | What it is |
|---|---|---|---|---|
| Joined | ✓ | Somebody joined the instance you are in. | ||
| Already there | Somebody was already in the instance when you arrived. | |||
| Left | ✓ | Somebody left the instance you are in. | ||
| Changed avatar | Somebody in the instance changed avatar. | |||
| Flagged join | ✓ | ✓ | ✓ | Your group's server raised a flagged-join alert for the instance you are in. |
| Log stopped | VRChat 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.jsonorMODBOT_CLOUD_DISABLEDsay), 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.exeThe 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.
| Command | What it does |
|---|---|
state | What 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-back | Put 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-cards | Takes every pop-up down |
grab-panel, move-panel <x> <y> <z>, release-panel | Holds 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.