Roblox Bridge Agent

<p align="center"> <img src="assets/rba-logo.png" width="168" alt="Roblox Bridge Agent logo"> </p>

<h1 align="center">Roblox Bridge Agent</h1>

<p align="center"> <strong>RBA</strong> is a local-first MCP bridge and script operations layer for authorized Roblox development. </p>

<p align="center"> <img alt="Node 20+" src="https://img.shields.io/badge/Node.js-20%2B-5FA04E?style=flat-square"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square"> <img alt="Protocol" src="https://img.shields.io/badge/RBA_protocol-v4-8B7CFF?style=flat-square"> <img alt="License" src="https://img.shields.io/badge/license-MIT-35D6A4?style=flat-square"> </p>

RBA connects an MCP-capable coding agent to local Luau development clients through a bounded websocket protocol. It combines live execution, structured results, file watching, diagnostics, source snapshots, permission-gated script capsules, crash detection, autoexec synchronization, and a realtime browser dashboard.

Use RBA only in experiences and local environments you own or are explicitly authorized to test. Keep its websocket and dashboard bound to loopback unless you deliberately build a secure remote deployment around them.

Why RBA exists

Editing a script and running it are only two pieces of a dependable workflow. RBA adds the missing operational layer:

• one shared local bridge that multiple MCP sessions can discover instead of fighting over ports;
• structured eval responses, correlated errors, bounded queues, heartbeats, and backpressure protection;
• live file and profile workflows with source validation before dispatch;
• Script Capsules with explicit permissions, automatic snapshots, and reversible rollback;
• a polished local command center with live clients, events, profiles, watchers, screenshots, and capsule controls;
• Roblox process and heartbeat diagnostics, plus a narrowly scoped restart tool;
• guarded Git helpers that stage only named files and never silently sweep the workspace;
• unified autoloader synchronization for configured executor autoexec locations.

Script OS model

RBA behaves like a small operations system around scripts:

MCP client
   │
   ▼
RBA server ─── dashboard / logs / snapshots / Git status
   │
   ├── script capsule policy + preflight + rollback
   │
   ▼
local websocket bridge
   │
   ▼
RBA Luau autoloader ─── authorized Roblox development client

Capsules are an honest policy boundary, not a fake security claim. RBA can block dispatch based on static capabilities, manage source history, and control lifecycle state. It cannot provide OS-grade isolation after arbitrary Lua reaches an executor.

Quick start

Requirements:

• Windows, macOS, or Linux for the Node server (Windows-only helpers are clearly scoped);
• Node.js 20 or newer;
• an MCP-capable client;
• a compatible local websocket-capable Luau environment for the client loader.

Install and verify:

git clone https://github.com/evonar543/roblox_bridge_agent.git
Set-Location roblox_bridge_agent
npm install
npm test

Add the built server to your MCP configuration, replacing the example paths:

{
  "mcpServers": {
    "roblox_bridge_agent": {
      "command": "node",
      "args": ["C:\\path\\to\\roblox_bridge_agent\\dist\\index.js"],
      "env": {
        "RBA_ROOT": "C:\\path\\to\\roblox_bridge_agent",
        "RBA_WS_HOST": "127.0.0.1",
        "RBA_WS_PORT": "33882",
        "RBA_WS_PORT_RANGE": "33882-33920",
        "RBA_AUTO_START_WS": "true"
      }
    }
  }
}

Then run the checked-in loader in your authorized development client:

loadstring(game:HttpGet("https://raw.githubusercontent.com/evonar543/roblox_bridge_agent/main/lua/rba_autoloader.lua"))()

For a pinned or offline workflow, use lua/rba_autoloader.lua directly instead of loading the moving main branch.

Autoloader behavior

The protocol-v4 loader:

• uses a single-instance lifecycle and stops an older RBA generation on reload;
• discovers the active websocket endpoint from a bounded local port range;
• reconnects with exponential backoff and avoids connection-attempt bursts;
• enforces incoming payload, queued evaluation, queued byte, duplicate request, and execution-time limits;
• emits client heartbeats and structured traffic counters;
• exposes _G.RBA.send, _G.RBA.log, _G.RBA.trace, _G.RBA.snapshot, _G.RBA.health, _G.RBA.showStatus, and _G.RBA.stop;
• displays a compact connection panel that fades after successful status updates and reappears on errors;
• can start the separately installed local Instance Manager connector from a loopback-only URL.

To keep RBA separate from Instance Manager, set either value before the loader starts:

getgenv().RBA_MODE = "rba-only"
-- or
getgenv().RBA_ENABLE_INSTANCE_MANAGER = false

Script Capsules

A capsule manages one workspace Lua file with a stable id, display name, explicit permissions, timestamps, and source history.

Available permissions:

Permission	Static capability covered
http	HttpGet, executor request functions, and HttpService requests
filesystem	executor file APIs such as readfile and writefile
remotes	FireServer and InvokeServer
dynamic_code	dynamic source/environment APIs such as loadstring
transform	direct CFrame and PivotTo writes
frame_loop	unbounded or frame/update loops

Typical flow:

1. rba_create_script_capsule
2. rba_script_preflight
3. rba_set_script_capsule_permissions
4. rba_capsule_snapshot
5. rba_run_script_capsule
6. rba_rollback_script_capsule if the experiment needs to be reversed

Snapshots live under .rba-capsules/ and are ignored by Git. Rollback captures the current source first, making the rollback itself reversible.

Dashboard

Start the loopback dashboard with rba_dashboard_start. The default address is http://127.0.0.1:33883/.

The RBA Script OS dashboard provides:

• animated bridge health and live activity state;
• connected client and selected-target visibility;
• direct send/eval controls;
• profiles and file watchers;
• capsule creation, snapshot, and run actions;
• recent events, screenshots, and context snapshots;
• responsive layout and non-blocking success/error notifications.

Tool families

RBA exposes tools in focused families instead of one oversized command:

• Bridge: rba_ws_start, rba_ws_stop, rba_ws_status, rba_connection_info, rba_clients, rba_events
• Execution: rba_send_lua, rba_eval_lua, rba_execute_file, rba_execute_bundle, rba_lua_syntax_check, rba_script_preflight
• Capsules: rba_create_script_capsule, rba_list_script_capsules, rba_set_script_capsule_permissions, rba_capsule_snapshot, rba_list_capsule_snapshots, rba_rollback_script_capsule, rba_run_script_capsule
• Live development: rba_watch_file, rba_start_live_session, rba_list_script_profiles, rba_set_autorun
• Observability: rba_ping_clients, rba_probe_runtime, rba_context_snapshot, console mirroring, screenshots, and structured event logs
• Recovery: rba_health_check, rba_detect_roblox_crash, rba_restart_roblox, rba_development_snapshot
• Source safety: workspace backups, restore, batch file operations, bounded reads, and search
• Workflow: autoexec install/sync/verification, unified status, rba_git_status, and rba_git_sync_files

Use tools/list from the MCP client for the authoritative schema and descriptions.

Experimental workspace

The repository also preserves the development scripts created alongside RBA, including the goalkeeper, solo-player, Chicken Farm, and Luarmor analysis helpers under lua/. They remain source-visible for rollback and continued local work, but they are not part of the RBA runtime, are not included in the npm package, and must only be used in environments you own or are authorized to test.

Keeping them outside the published package gives the Git repository a complete project history without making experience-specific experiments part of the bridge's supported API.

Safety defaults

• Websocket and dashboard hosts default to 127.0.0.1.
• Workspace file tools reject traversal outside RBA_ROOT.
• Instance Manager probes and loader overrides accept loopback addresses only.
• Payload size, rate, buffered-byte, event-memory, log-file, and evaluation limits are bounded.
• Git sync requires explicit file paths, refuses a pre-staged index, and never uses git add --all.
• Roblox restart discovers and validates RobloxPlayerBeta.exe, then stops only processes with that exact executable name.
• Autoexec replacement makes a backup before overwriting changed content.

Development

npm run dev
npm run build
npm test
npm pack --dry-run

The test suite compiles TypeScript, parses the full Luau loader, validates lifecycle and protocol guardrails, exercises normal and oversized websocket traffic, verifies autoexec synchronization, and smoke-tests capsule creation and snapshots through MCP.

Architecture notes live in docs/ARCHITECTURE.md. Security reports should follow SECURITY.md.

License

MIT. See LICENSE.