Skip to content

RbxOS

Latest
Latest

Choose a tag to compare

View all tags
@SillyDev2026 SillyDev2026 released this 30 Aug 09:33
RbxOS
e197c47

RbxOS Backend & Companion v1.2.0

This folder contains the Python side of RbxOS v1.2.0.

For most users, you do not need to manually configure the backend. The easiest setup is to run the RbxOS Companion, which starts the local Studio bridge automatically on 127.0.0.1:8000.

What the Backend does

The Backend/Companion provides optional desktop-side features for RbxOS:

  • PySide6 RbxOS Companion application
  • Studio-local FastAPI/Uvicorn bridge
  • authenticated Roblox runtime delivery to the Studio plugin
  • release/version alignment checks
  • Discord Rich Presence integration
  • PC CPU/RAM diagnostics and activity information
  • pairing and security status
  • Explorer/VFS source mirroring support
  • backend latency and uptime tests
  • RPC preview/session logging
  • optional standalone production backend

The Studio-native RbxOS desktop can still run without the Python companion, but features that require the bridge will show as offline/unavailable.

Quick Start — Recommended

Requirements

  • Windows 10 or Windows 11
  • Python 3.11 or newer
  • Roblox Studio
  • RbxOS Studio Plugin v1.2.0

When installing Python, enable Add python.exe to PATH.

1. Download and extract the repository

Download the GitHub source ZIP or clone the repository, then open the Backend folder.

The important files are:

Backend/
├─ companion_app.py
├─ server.py
├─ diagnostics.py
├─ requirements.txt
├─ setup_and_run_companion.bat
├─ run_companion.bat
├─ run_companion_safe.bat
├─ build_companion.bat
├─ build_release.bat
└─ runtime/

2. Run the automatic setup

Double-click:

setup_and_run_companion.bat

This script will:

  1. check that Python is installed;
  2. create a .venv virtual environment when needed;
  3. install the packages from requirements.txt;
  4. start companion_app.py;
  5. start the Studio-local backend used by the RbxOS plugin.

On a successful launch, the local bridge runs on:

http://127.0.0.1:8000

Keep the Companion open while using features in Roblox Studio that require the backend.

3. Install/open the RbxOS Studio plugin

The plugin source is located at:

StudioPlugin/RbxOS.plugin.lua

Use the same release version for the Plugin, Companion, and Roblox runtime. For this source package, all components should report:

1.2.0

Open RbxOS Manager in Studio and use Check Companion / Update Center to verify that the versions match.

4. Install or update the in-game RbxOS runtime

With the Companion running:

  1. Stop Play/Test mode in Roblox Studio.
  2. Open RbxOS Manager.
  3. Click Install / Update Runtime or Repair Runtime.
  4. The plugin requests the authenticated v1.2.0 runtime payload from the local Companion.
  5. Start Play/Test and launch RbxOS.

The installer manages these six runtime sources:

Backend/runtime/RbxOS.lua
  -> ReplicatedStorage/RbxOS

Backend/runtime/RbxOSServer.server.lua
  -> ServerScriptService/RbxOSServer

Backend/runtime/RbxOSBoot.client.lua
  -> StarterPlayer/StarterPlayerScripts/RbxOSBoot

Backend/runtime/persistence/NexusDataStore.lua
  -> ServerStorage/RbxOSPersistence/NexusDataStore

Backend/runtime/persistence/Compression.lua
  -> ServerStorage/RbxOSPersistence/NexusDataStore/Compression

Backend/runtime/persistence/BufferUtil.lua
  -> ServerStorage/RbxOSPersistence/NexusDataStore/BufferUtil

RbxOS v1.2.0 includes version-alignment guards, so an old LocalScript/server/runtime should not silently run as if it were the current release.

Run from PowerShell / Command Prompt

If you prefer to run the source manually:

cd Backend
python -m pip install -r requirements.txt
python companion_app.py

Using a virtual environment is recommended:

cd Backend
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe companion_app.py

After the first setup, you can normally use:

run_companion.bat

Safe Start

If the Companion crashes during startup, try:

run_companion_safe.bat

Safe Start temporarily disables Discord RPC auto-start for that run while keeping the Studio-local backend enabled.

Crash logs are written under:

%LOCALAPPDATA%\RbxOS\logs\companion_crash.log

Run only the local backend

For backend testing without the full PySide6 Companion UI, use:

run_backend_local.bat

This is intended for local development/testing. The normal user workflow should use companion_app.py or setup_and_run_companion.bat.

Production Backend

server.py can also run as a standalone production backend.

Before using production mode, define a private API key with at least 24 characters:

$env:RBXOS_BACKEND_API_KEY="replace-this-with-a-long-random-secret"

Then run:

run_backend.bat

or:

python server.py --mode production --host 0.0.0.0 --port 8000

Security warning

The default Companion bridge is designed for local Studio use on 127.0.0.1.

Do not expose a development/local key to the public internet. If you intentionally deploy the production backend, use a strong private RBXOS_BACKEND_API_KEY, HTTPS/reverse-proxy protection, firewall rules, and normal server hardening.

The .env.example file documents the production API-key variable.

Build the Windows Companion

To build the PySide6 Companion with PyInstaller:

build_companion.bat

The executable is generated under:

Backend/dist/RbxOS-Companion/

To create the packaged Windows release ZIP, use:

build_release.bat

The expected release asset is:

RbxOS-Companion-v1.2.0-Windows.zip

GitHub Actions Build

This repository contains:

.github/workflows/build-windows.yml

Pushing a version tag such as:

v1.2.0

runs the Windows build workflow. It validates the Python/release sources, builds the Companion, creates the Windows ZIP, and uploads the Companion ZIP, Studio plugin, and release manifest to the GitHub Release.

You can also run the workflow manually with Actions -> Build RbxOS Companion -> Run workflow.

Python Dependencies

Dependencies are stored in requirements.txt:

FastAPI
Uvicorn
Pydantic
PySide6
psutil
requests
pypresence

Install them with:

python -m pip install -r requirements.txt

Version Matching

RbxOS is designed to keep the following components on the same release:

  • Studio plugin
  • Python Companion/backend
  • RbxOS.lua
  • RbxOSServer.server.lua
  • RbxOSBoot.client.lua
  • runtime persistence payload

For this branch/release:

RbxOS Version:       1.2.0
Protocol Version:    1.2.0
Studio Plugin:       1.2.0
Python Companion:    1.2.0

Use Verify Version Match in the Companion or Update Center in the Studio plugin if something reports an older version.

If Roblox still reports v1.1.9 or v1.1.10, stop Play/Test mode and use Repair Runtime so the current v1.2.0 payload replaces the stale managed runtime sources.

Troubleshooting

python was not found on PATH

Install Python 3.11+ from Python.org and enable Add python.exe to PATH, then reopen Command Prompt/PowerShell.

Missing Python package / ModuleNotFoundError

Run:

python -m pip install -r requirements.txt

or rerun setup_and_run_companion.bat.

Companion says the backend is offline

Make sure another program is not already using port 8000, close duplicate RbxOS backend processes, then restart the Companion.

Studio says Companion offline

Confirm the Companion is running and that its local backend is listening on:

127.0.0.1:8000

Then use Check Companion again in RbxOS Manager.

Version mismatch

Do not mix files from different RbxOS releases. Use the Studio plugin and Backend/runtime files from the same GitHub tag/release and run Repair Runtime.

Runtime install/update is blocked

Stop Roblox Studio Play/Test mode first. RbxOS intentionally refuses to rewrite managed runtime sources while the game is running.

Companion crashes when Discord RPC starts

Run:

run_companion_safe.bat

Then inspect:

%LOCALAPPDATA%\RbxOS\logs\companion_crash.log

Backend Folder Reference

File / Folder Purpose
companion_app.py Main PySide6 Companion application and local Studio bridge
server.py FastAPI backend / standalone production server
diagnostics.py PC/backend diagnostic helpers
requirements.txt Python dependencies
setup_and_run_companion.bat Recommended first-time setup and launch
run_companion.bat Normal source launch after setup
run_companion_safe.bat Recovery launch with Discord RPC auto-start disabled
run_backend_local.bat Local backend-only development run
run_backend.bat Production backend launcher
build_companion.bat Build the Windows Companion with PyInstaller
build_release.bat Build/package the Windows release
runtime/ Roblox v1.2.0 runtime payload sent to the Studio plugin
VERSION.txt Backend release version
suspicious_names.txt Data used by Companion diagnostics/security checks
PYTHON_SETUP.md Short Python-specific setup reference

RbxOS v1.2.0

RbxOS v1.2.0 is a synchronized release. Keep the GitHub source, Studio plugin, Python Companion, and Roblox runtime from the same release together to avoid protocol/version mismatches.

Assets 3
Loading