Installing the companion
Download and install the Modbot companion on Windows or Linux, keep it up to date, and see exactly what it reads and sends.
The Modbot companion is a small program for moderators, for Windows and for Linux. It reads VRChat's own log file on your PC, works out which instance you are in and who comes and goes, and tells your group's Modbot. That is what fills the Live page and each person's presence history. On Windows it sits in the tray (the icons near the clock) for as long as it runs; on Linux it is an ordinary window.
What you need
- 64-bit Windows 10 or 11, or 64-bit Linux. There is no Mac or Quest version.
- VRChat on the same PC. The client reads the log that VRChat writes on that PC. On Linux, VRChat runs through Steam's Proton, and the client looks for the log in Steam's usual folders, including the Flatpak and Snap ones; if yours is somewhere else, point it there in Settings.
- Nothing else installed first. The client brings its own copy of .NET.
- No administrator rights. It installs into your own user folder and only changes settings for your own account.
- SteamVR, only if you want the overlay. Without SteamVR the client still reports presence as normal.
- A staff account on your group's Modbot holding Pair a companion, to pair the client with it. Until you pair, the client reports to no group server.
Download
Releases are published on the Modbot repository's GitHub Releases page. Each release has these files:
| File | What it is |
|---|---|
Modbot-win-Setup.exe | The Windows installer. Use this one on Windows. |
Modbot-win-Portable.zip | The same Windows program with no installer. Unzip it anywhere and run Modbot.exe. |
Modbot.AppImage | The Linux build. One file: make it runnable and run it. |
Modbot-…-full.nupkg, …-delta.nupkg, releases.win.json, releases.linux.json, RELEASES, RELEASES-linux | What installed clients download when they update. You never need these. |
If somebody sent you a build to try before it is released, that is a preview, and it installs and updates a little differently.
Install on Windows
Run the installer
Run Modbot-win-Setup.exe. There are no questions. It installs to
%LOCALAPPDATA%\Modbot, adds Modbot to the Start Menu and to Windows' list of installed apps,
and opens the client.
Get past SmartScreen if Windows asks
If a blue Windows protected your PC box appears, press More info, then Run anyway. Some browsers also ask whether to keep the download: keep it. See the note below.
Pair it with your group's Modbot
The client opens on its Servers page. Follow Pairing to connect it to your group.
Unsigned builds and SmartScreen
A release is only code-signed when the project has a signing certificate set up. Without one, the build is unsigned, and Windows SmartScreen warns about it because it has no publisher to check. The warning is about the file being new and unsigned, not about anything the file does.
Windows Defender may also, now and then, hold back an unsigned program that reads another program's files and uses the network, which is what this client does. If Modbot disappears right after installing, look in Windows Security → Protection history.
Install on Linux
Download the AppImage
Download Modbot.AppImage from the release and put it wherever you keep programs.
Make it runnable and run it
chmod +x Modbot.AppImage
./Modbot.AppImageMost file managers also offer this as Allow executing file as program in the file's properties, after which a double-click opens it.
Pair it with your group's Modbot
The client opens on its Servers page. Follow Pairing and type the code in: pairing links from a browser only open the client on Windows.
The client finds VRChat's log under Proton on its own, in Steam's usual folders (including Flatpak and Snap installs of Steam), and the overlay works with SteamVR for Linux. With WiVRn or Monado it works through OpenXR instead; see WiVRn and Monado. There is no start-at-sign-in switch on Linux; add the AppImage to your desktop's startup programs if you want that.
The client window
By default, closing the window does not stop the client. It keeps reading and reporting from the tray. Click the tray icon, or choose Open Modbot from its menu, to bring the window back. Quit — stops reporting in the tray menu really does stop it: the log stops being read at once. So does the Quit button at the foot of the window. If you would rather the X button quit, untick Close to tray on the Settings page.
Only one copy runs per Windows account. Opening Modbot again while it is already running just brings up the window.
The window has six pages:
| Page | What it shows |
|---|---|
| Servers | Each paired server, whether it is reporting, and the pairing controls. See Pairing. |
| Audit Log | Every event the client has handled, newest first — one line each, with the group it was for and whether it was sent, waiting, withheld or failed. Events held back, for example while paused, are listed too, along with notes such as "Paused" or "Resumed reporting". An event the server took the batch for but would not keep is failed, with a note saying why. An event that was for no paired server has the time and the sentence and nothing else. It shows the latest 200 events and keeps 1,500 lines on disk. |
| SteamVR | Whether the overlay is attached to SteamVR, what it is showing, how many frames it has drawn, and where the panel sits. Look for SteamVR now attaches without waiting for the next ten-second look. |
| Log | What the client makes of VRChat's log: lines seen, lines Modbot looks at and recognised. You can open the same file in Notepad and check the counts. Also Copy crash details: see below. |
| Settings | The client's switches, the voice and the VRChat log folder. See Client settings. |
| Credits | Sponsors, early adopters and contributors, read from Modbot Cloud. See Credits in the client. |
The line at the bottom of the sidebar says reading VRChat's log, VRChat not running, or log not recognised. It says reading VRChat's log while you are alone in a world too: the Log page adds "Nothing has happened in a while", and that is not a problem. Nobody joining or leaving is nothing to report, not a fault.
Crash details
When somebody crashes an instance, VRChat's staff ask for the instance, the people in it, what they were wearing, and VRChat's own log. Log → Copy crash details puts all of that on your clipboard as one block of text, ready to paste into a VRChat Help Desk ticket:
- the world and the instance, written the way VRChat writes an instance's address,
- everybody the log says was in the instance, with their VRChat user id and the name of the avatar the log last saw them wearing (VRChat's log never has another person's avatar id, so the name is all there is),
- VRChat's own
[Behaviour]log lines from the ten minutes before the log's last line, at most 400 of them.
Press it before you start VRChat again: a new VRChat session starts a new log, and the companion forgets the old instance when it does. The times are your PC's own clock, and the text says which timezone that is.
Nothing is sent. The text goes onto your clipboard and nowhere else — not to your group's Modbot, not to Modbot Cloud, not to VRChat. Where it goes next is wherever you paste it. The secret part of an instance's address is taken out of every line first. The companion never reads what is already on your clipboard; this button is the only thing in it that touches the clipboard at all, and only to write.
Keyboard shortcuts
Press ? in the window for the list. Letters only work when you are not typing in a box.
| Keys | Does |
|---|---|
Ctrl K | Search and commands: every page, and the buttons on the open page, by name |
? | Keyboard shortcuts |
Esc | Close what is open: the palette, the filter picker, an opened row, the selection |
G then S / A / V / L / T | Go to Servers, Audit Log, SteamVR, Log, Settings (G then D for Debug when it is on) |
J / K, ↓ / ↑ | Next or previous row on Audit Log |
Enter | Open the selected row: every field it holds, and the row as JSON |
F | Add a filter on Audit Log (Shift F removes the last one) |
/ | Filter Audit Log by text |
Filters on Audit Log
Filter on the Audit Log page adds a chip: Kind (joined, already there, left, changed avatar,
log stopped, seen, note), State (sent, waiting, withheld, failed), Group, or Text.
Values inside a chip are "any of"; chips combine. Each value shows how many rows it would leave.
The chips are kept in settings.json under eventsFilters, so the page opens the way you left it.
Warnings in the window
Warnings show at the top of every page.
| Warning starts with | What it means | What to do |
|---|---|---|
| VRChat is writing the lines Modbot reads and it has recognised none of them recently. | For 10 minutes VRChat has been writing the kind of line the client reads — joins, leaves, world changes — and none of them matched anything it understands. The client names two causes: VRChat was started without its verbose logging options, or VRChat changed its log format. Being alone in a world does not cause this; no joins or leaves at all is counted as nothing happening, not as a fault. | Check how VRChat is started. If that is not it, update the client. Nothing is recorded until this is fixed. |
| Reading VRChat's log failed: … | The client hit an error while reading. After five failures in a row the reader stops until you restart the client. | Send the client's log file (see where things are) to whoever looks after your Modbot. |
| The saved credential for "…" cannot be decrypted on this Windows account. | The pairings file was copied from another Windows account or PC. Saved tokens only work for the account that saved them. | Pair that server again. |
| "…" rejected this device. | That server refused the client's token, usually because an operator revoked it. | See When a token is revoked. |
| "…" has been upgraded past what this client can speak to. | The server is newer than this client supports. Events are still queued. | Update the client. |
| Modbot … has been downloaded and will be installed the next time Modbot starts. | An update is ready. | Quit from the tray and open Modbot again whenever it suits you. |
If something in the client crashes, Windows shows a Modbot ran into a problem box (the client keeps running) or a Modbot has stopped box (it closed). Both name the folder with the client's log.
What the client reads, and what it sends
What it reads
One folder: VRChat's log folder. On Windows that is %USERPROFILE%\AppData\LocalLow\VRChat\VRChat.
On Linux, VRChat runs under Proton and the same folder sits inside the Proton prefix in your Steam
library, steamapps/compatdata/438100/pfx/drive_c/users/steamuser/AppData/LocalLow/VRChat/VRChat;
the companion looks for it under ~/.local/share/Steam, ~/.steam/steam, the Flatpak and Snap
Steam folders, and last a plain Wine prefix under ~/.wine. A library somewhere else is set under
Settings, VRChat log folder. Inside the folder, only the files VRChat names
output_log_*.txt, and only the newest one. The client opens the file to
read while VRChat is still writing it, never changes it, and makes no copy.
Of all the lines in that file, the client only looks at lines VRChat tags [Behaviour], and inside
those it recognises a handful of shapes:
- you joining an instance (which world and instance),
- the world's readable name, which names a saved clip,
- which display name is yours,
- someone joining or leaving, with their display name and VRChat user id,
- someone switching avatar (VRChat logs the avatar's name, never its id).
Everything else is skipped. Lines that were already in the file when the client started are read only to work out which instance you are in and who is in it with you. None of those comings and goings is reported — an evening of them is over. The people they leave standing in the instance with you are sent once, as already there, as soon as VRChat writes its next line, because those people are still in there and nothing later in the log would ever name them. If VRChat is not running, nothing is sent at all.
It does not read chat, your friends list, your screenshots folder, the clipboard, the keyboard or which other programs are running. (It writes to the clipboard once, when you press Copy crash details, and never reads it.) It does not read Steam's settings. It has no way to attach files to a case on its own: you do that in the web app, by choosing a file. The one file it can send is the answer to a clip request your group's Modbot made, described next.
One thing it can do, and only if you switch it on: Clips keeps the last two to ten minutes of VRChat's window and VRChat's sound while VRChat is running, so you can save those minutes as a video file. It is off unless you turn it on, it records nothing while VRChat is not running, and a clip leaves your PC only in the one case below. A separate box, also off, tells your group's Modbot when you save a clip in its instance, with the file's fingerprint — never the clip — so the clip can be attached to a case later and recognised as yours. A third box, also off, Send clips for my actions automatically, lets your group's Modbot ask your companion for a clip of a ban, kick or warning you made; the companion cuts a clip around the moment and sends it as the answer to that one request. The server takes a file only as the answer to a request it sent to that device, once, within 15 minutes. Anything drawn on top of VRChat while you are in it — a chat overlay, a notification — is inside VRChat's window and so is in the clip; the rest of your screen never is.
The sound is VRChat's own, which in an instance is people's voices. Discord's sound can go in as well, on a second box that is off until you tick it. Nothing else this PC plays is ever recorded — not music, not a browser, not another chat program — because Windows is asked for one named program's sound rather than for what your speakers are playing. No microphone is opened for a clip. That page says exactly what is recorded and what is not.
The other thing it can do, and only if you switch it on: Listening opens your microphone while VRChat is running so that saying "Modbot, clip that" saves a clip, for the times you are in a headset and cannot reach a keyboard. It is off unless you turn it on, and nothing it hears is recorded, kept or sent — the sound is checked against a short list of phrases and thrown away. It shares the microphone the way VRChat does, so VRChat keeps working, and it says so at the top of the window for as long as it is open.
What it sends to your group's Modbot
From what it recognises, and from what you do in it, the client builds six kinds of event:
| Event | Meaning |
|---|---|
| Joined | Someone arrived while you were already in the instance. |
| Already there | Someone was in the instance when you arrived. |
| Left | Someone left. |
| Changed avatar | Someone switched avatar. Carries the avatar's name. |
| Log stopped | VRChat's log stopped growing for about two minutes while you were in an instance. Names you, and is sent once per stop. |
| Clip saved | You saved a clip in the instance. Names you, and carries the file's SHA-256 and size — never the clip, its name or where it is on your PC. Only sent if you ticked Tell the group's Modbot when I save a clip, and never to Modbot Cloud. The server keeps it only if it names the VRChat account linked to your Modbot account. |
Each event carries a random event id, its type, the time it happened (adjusted to the server's clock), the person's VRChat user id and display name, the world id, the instance id and the group that owns the instance. The instance id never includes the secret part of an instance's address that would let someone join it.
A server only ever gets events for its own group's instances. The group is written inside VRChat's instance address, so the client decides this on your PC with no lookup. Public, friends-only and private instances, and other groups' instances, are never sent to any Modbot server. If you moderate two groups, neither group's server hears about the other's instances.
Events go over HTTPS (plain HTTP is only allowed to your own PC, for testing). Someone arriving or leaving is sent within about two seconds. Otherwise the client sends every 30 seconds or when 50 events are waiting. If the server cannot be reached, events wait on disk (up to 50,000 per server, for up to three days) and go out when it is back.
The client also talks to a paired server in these ways:
-
It keeps one small live connection open to each paired server the whole time it runs, with no instance named. It carries your Clips settings and the server's clip requests, and it is how Modbot knows your companion is open and paired.
-
It answers a clip request the server sent it, for one of your own bans, kicks or warnings, with a clip or with a word saying why there is none (always Clips was off unless you ticked Send clips for my actions automatically). It sends nothing of the kind unasked.
-
It asks the server's time soon after it starts or pairs, and every two hours after that, so its timestamps line up with the server's clock.
-
While you are in that group's instance, the overlay asks for the instance's roster (which tells the server the instance id) and waits for flagged-user alerts. The desktop overlay in VRChat's look also asks that server for the picture of each person the roster names one for, from the server's own saved copies, never VRChat.
Everything the client sent to a server is listed on Audit Log.
What it sends to Modbot Cloud
Unless you turn it off, the client also sends the same events, for every instance you are in,
straight to Modbot Cloud (https://cloud.modbot.co) as a backup. That includes public,
friends-only and private instances, where the group is left empty. It works the same before and
after you pair, and a paired server has no say in it. Clip saved is the one event it never
backs up: that goes to your group's Modbot or nowhere. It never sends VRChat's raw log, and never
the secret part of an instance's address.
The backup is not shown in the window. Audit Log lists what the client handled and how each event's own group's server took it; it does not list the backup, does not report its state, and does not let you filter by it. Pausing a paired server does not stop the backup either — it is a separate flow, and only that PC's settings file or environment turns it off. How the backup works, and how to turn it off, is on Client settings; what it sends is in the privacy policy.
Other connections
- Updates. An installed client asks Modbot Cloud whether there is a newer version, and downloads it from GitHub if so. The request does not identify you or your install: nothing is sent, nothing is recorded, and everybody gets the same answer. It is not part of Modbot Cloud backup — turning that off does not stop update checks, and stopping update checks does not turn it off.
- Pairing. Pressing Pair with a server opens a page in your browser. The client itself only contacts the server named in the pairing link. See Pairing.
- The voice. The first time the voice is turned on, the client downloads the voice once from GitHub, with nothing attached. See Voice for the exact file.
The client sends its own log file nowhere.
Updates
An installed client (from Modbot-win-Setup.exe, the portable zip or the AppImage) checks for a
newer version 30 seconds after it starts and every 15 minutes after that. It asks Modbot Cloud,
which keeps one copy of the answer for everybody and refreshes it from GitHub every 15 minutes;
the download itself comes from the GitHub release. A newer version downloads in the
background, and the window shows a line saying it will be installed the next time Modbot starts.
The request sends nothing about you or your pairings. The update library the client uses puts your operating system, your processor type and the version you are on in the request's address. Modbot Cloud ignores them, and its own log keeps only the method, the path, the status and the time. Modbot Cloud and GitHub each see your IP address, as any site does for any request.
Nothing is installed while Modbot is running, so an update never cuts a VRChat session short. Quit
from the tray and open Modbot again whenever it suits you. The update is installed before the
window opens, and the client comes back up. Your pairings and settings are kept: updates never
touch %APPDATA%\Modbot.
Once a newer version has finished downloading, it is also offered in the game, so you do not have to leave VRChat to install it. If the notification overlay is on, a pop-up in the headset, and the one in the corner of the screen on a monitor, names the version with two buttons, Update and Later. It stays until you press one. Update turns into Restart now for five seconds; press it again in that time and Modbot restarts into the new version, the same as the sidebar's Restart to update. Later closes it, and the update installs the next time Modbot starts. It is offered once for each version. On a monitor the corner pop-up takes clicks only while this question is showing, and never takes the keyboard from VRChat.
If a check fails (no connection, or the release feed cannot be read), the client writes
Could not check for updates to its log and tries again 15 minutes later. You can always download
the latest Modbot-win-Setup.exe and run it over your current install, or the latest
Modbot.AppImage in place of the one you have.
To stop the client checking at all, see Check for updates.
A copy you built yourself, or ran from a folder you copied, is not an installed copy and never checks for updates.
Where the client keeps its files
| What | Where |
|---|---|
| The program | %LOCALAPPDATA%\Modbot. The portable zip runs from wherever you unzipped it. |
| A downloaded update waiting to be installed | %LOCALAPPDATA%\Modbot\packages |
| Paired servers and their tokens (tokens encrypted to your Windows account) | %APPDATA%\Modbot\pairings.json |
| Settings | %APPDATA%\Modbot\settings.json |
| Events waiting to go to each server | %APPDATA%\Modbot\queue |
| The Audit Log list | %APPDATA%\Modbot\sent.jsonl |
| The client's own log, one file a day, last seven kept | %APPDATA%\Modbot\logs (companion-YYYYMMDD.log) |
| Events waiting to go to Modbot Cloud (up to 20 MB) | %APPDATA%\Modbot\cloud |
| The client's Modbot Cloud install id (secret encrypted) | %APPDATA%\Modbot\cloud-installs.json |
| The downloaded voice (about 353 MB), only once the voice has been turned on | %APPDATA%\Modbot\voices |
On Linux the program is the AppImage, wherever you put it, and everything else is under
~/.config/Modbot with the same names. Tokens there are encrypted with a key in
~/.config/Modbot/secret.key, a file only your user can read, in place of the Windows account
encryption.
The client also writes two things to the registry, both under your own account and neither needing administrator rights:
HKEY_CURRENT_USER\Software\Classes\modbot-companion, so pairing links from your browser open the client.- A value named
ModbotunderHKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run, so an installed copy starts when you sign in. See Start with Windows.
The client's log is the first thing to send when you report a problem. Paste %APPDATA%\Modbot\logs
into File Explorer's address bar to open the folder. The first line of each run says which version
started.
Uninstall
Go to Settings → Apps → Installed apps → Modbot → Uninstall in Windows. That removes the program, its Start Menu entry and the start-with-Windows entry.
It leaves %APPDATA%\Modbot (pairings, settings, queues, the sent list and the logs), so a
reinstall picks up where you left off. Delete that folder to remove everything. The
modbot-companion registry key is also left behind. It points at a program that is no longer there,
which does no harm, and you can delete it at any time.
On Linux, delete Modbot.AppImage and, to remove everything, ~/.config/Modbot.
Uninstalling does not tell your group's server. The token simply stops being used, and after 90 days unused the server refuses it anyway. To remove it sooner, press Unpair on each server before you uninstall, or remove it in Settings, Paired companions (Paired devices on the server).
Building it yourself
If you would rather not run a downloaded program, build the same folder the installer or the AppImage contains from the source, with the .NET 10 SDK:
dotnet publish src/Modbot.Companion.App -c Release -p:PublishProfile=win-x64
dotnet publish src/Modbot.Companion.App -c Release -p:PublishProfile=linux-x64The output is in artifacts/client/publish. Run Modbot.exe from there. A copy built this way
does not check for updates and does not show the start-with-Windows switch.