Skip to content

phenibut645/balkon-obs-agent

BranchesTags

Repository files navigation

Balkon OBS Agent

Balkon OBS Agent is the local desktop bridge between the Balkon backend/relay and the streamer's local OBS Studio instance.

It is part of the Balkon ecosystem:

  • phenibut645/balkon — Discord bot, backend API, MySQL database, migrations and OBS relay
  • phenibut645/balkon-website — Next.js dashboard and Streamer Studio UI
  • phenibut645/balkon-obs-agent — this repository, local Windows desktop agent for OBS Studio

The agent is intended for streamers. They do not need to clone the main bot/backend repository or install database dependencies. They only run the packaged desktop app, connect it to the relay, and connect it to their local OBS Studio WebSocket server.

Role in the System

OBS Studio runs on the streamer's own PC. The backend and Discord bot usually run on a remote server. Directly exposing a local OBS WebSocket port to the internet would be unsafe and unreliable.

Balkon therefore uses an outbound relay model:

Balkon Website / Discord bot
      ↓
Balkon backend API / command queue
      ↓
Balkon OBS relay
      ↓ outbound WebSocket
Balkon OBS Agent on streamer PC
      ↓ local WebSocket
OBS Studio ws://127.0.0.1:4455

The agent connects outward to the relay and then controls OBS locally. This avoids router/NAT problems and prevents the public exposure of the OBS WebSocket port.

Main Features

  • Connects to the Balkon OBS relay with Agent ID and Agent Token
  • Connects to local OBS Studio through obs-websocket
  • Executes OBS commands sent by the backend/relay
  • Reports relay and OBS connection status
  • Shows recent events/logs in the UI
  • Supports English, Russian and Estonian UI languages
  • Runs in the Windows system tray
  • Supports auto-connect and OBS auto-retry behavior
  • Supports packaged Windows releases and GitHub Release auto-updates
  • Masks token/password inputs and avoids printing full secrets in logs

Install for Development

npm install

Run in Development

npm run dev

Auto-update behavior is not active in development mode. It is intended for packaged builds.

Build

npm run build

Package Windows App

npm run dist

The packaged installer is written to:

release/

Do not commit generated release artifacts into Git.

Ignored/generated artifacts include:

release/
dist/
win-unpacked/
*.exe

Enable OBS WebSocket

Before using the agent, OBS Studio must have the WebSocket server enabled.

  1. Open OBS Studio.
  2. Go to:
Tools -> WebSocket Server Settings
  1. Enable the WebSocket server.
  2. Use the default port:
4455
  1. Set a password if desired, or leave it empty for local testing.
  2. Keep OBS Studio open while testing agent commands.

Default local OBS WebSocket URL:

ws://127.0.0.1:4455

Get Agent Credentials

Credentials are generated from the Balkon system, normally through the website Streamer Studio or Discord streamer commands.

Legacy Discord command flow:

/streamer register nickname:<nickname> primary:true
/streamer agent_pair nickname:<nickname>

The website Streamer Studio can also show/generate the Agent ID and token through OBS Agent setup screens, depending on the current backend/dashboard configuration.

Important:

  • Agent Token is sensitive.
  • Do not share real Agent Tokens in screenshots or commits.
  • In streamer/demo mode, token-like values should be hidden or masked.

App Configuration

Enter these values in Balkon OBS Agent:

Field Description
Relay URL WebSocket URL of the Balkon OBS relay
Agent ID Agent identifier generated by Balkon
Agent Token Secret pairing token generated by Balkon
OBS WebSocket URL Local OBS WebSocket URL, usually ws://127.0.0.1:4455
OBS WebSocket Password Optional OBS WebSocket password

Production relay example:

wss://venomancer.aleksandermilisenko23.thkit.ee/

Local OBS example:

ws://127.0.0.1:4455

After filling values:

  1. Click Save.
  2. Click Connect.
  3. Use Test OBS to check local OBS connectivity.

Runtime Flow

Agent connection

agent starts
→ loads saved config
→ connects to Balkon relay
→ sends hello with agentId and agentToken
→ relay validates credentials
→ relay accepts connection
→ agent status becomes online

OBS command execution

backend queues/sends OBS command
→ relay forwards command to connected agent
→ agent executes command against local OBS WebSocket
→ agent returns command result
→ backend/dashboard can display success or failure

Common command categories:

  • get OBS status
  • list scenes
  • switch scene
  • list scene items/sources
  • set source visibility
  • update text source
  • trigger media input action
  • show configured OBS media/effects

UI Tabs and Localization

The agent has a tabbed UI.

Tabs

Tab Purpose
Main Connection settings, relay/OBS status and recent event log
Settings Behavior options, language selection and update controls
Changelog Release history and notable changes

Supported languages

  • English
  • Русский
  • Eesti

Language selection is saved locally and applied without requiring an app restart.

Background / Tray Mode

Balkon OBS Agent is designed to run as a tray application.

Close vs Quit

Action Result
Close window Hide to tray, agent keeps running
Quit from tray Fully exit and disconnect

Tray context menu

Item Action
Open Show the main window
Connect Connect to the relay using saved config
Disconnect Disconnect from relay
Check for Updates Check GitHub Releases for a new version
Quit Disconnect and exit

Behavior settings

Setting Description
Start with Windows Register app as a login item so it starts with Windows
Start minimized to tray Start hidden in the system tray
Auto-connect on launch Connect to relay automatically if credentials are saved
Auto-retry OBS connection Retry local OBS connection every few seconds when OBS is not available

Auto-retry logs only the first retry attempt to avoid log spam.

Testing Checklist

Use this checklist after changing relay, OBS or packaging behavior.

[ ] npm install completed
[ ] npm run build passes
[ ] npm run dev starts the app
[ ] OBS WebSocket is enabled in OBS Studio
[ ] Relay URL is saved
[ ] Agent ID and Agent Token are saved
[ ] OBS WebSocket URL is saved
[ ] Connect succeeds
[ ] Test OBS succeeds
[ ] Agent appears online in Balkon/Streamer Studio
[ ] OBS scenes can be listed from website or bot
[ ] OBS scene switching works
[ ] OBS source visibility update works
[ ] Media/effect command works if configured
[ ] Closing window hides to tray
[ ] Quit fully exits the app

Publish a Release

Balkon OBS Agent uses GitHub Releases for auto-updates.

Patch release flow

npm version patch --no-git-tag-version
npm run dist
git add .
git commit -m "chore: release v0.1.X"
git push

Then create a GitHub Release:

Tag:   v0.1.X
Title: Balkon OBS Agent v0.1.X

Upload these files from release/:

Balkon-OBS-Agent-Setup-0.1.X.exe
Balkon-OBS-Agent-Setup-0.1.X.exe.blockmap
latest.yml

The filename must be exactly:

latest.yml

Auto-updates will fail with a 404 if latest.yml is missing from the latest release.

If using Electron Builder direct publishing, set GH_TOKEN with release permissions and run:

npm run dist:publish

Troubleshooting

Previous build is stuck during installation

Close the app first:

taskkill /IM "Balkon OBS Agent.exe" /F

Agent connects to relay but OBS is unavailable

Check:

  • OBS Studio is open
  • OBS WebSocket server is enabled
  • port is 4455
  • password matches the app configuration
  • local URL is ws://127.0.0.1:4455

Agent does not connect to relay

Check:

  • Relay URL is correct
  • Agent ID is correct
  • Agent Token is correct
  • token was not rotated/revoked
  • backend/relay is running
  • firewall/proxy does not block outbound WebSocket connections

Security Notes

  • Never commit real Agent Tokens.
  • Never print full Agent Tokens in logs.
  • Do not expose OBS WebSocket directly to the public internet.
  • Prefer the relay + local agent model for production.
  • Store secrets only in local app configuration or backend-managed secure storage.

Diploma / Demo Flow

Recommended demonstration flow:

  1. Open OBS Studio and enable WebSocket.
  2. Start Balkon OBS Agent.
  3. Save Relay URL, Agent ID, Agent Token and OBS WebSocket URL.
  4. Connect the agent.
  5. Confirm agent online status in Balkon Website Streamer Studio.
  6. Open OBS control in the website.
  7. Refresh scenes and switch scenes.
  8. Trigger a source visibility or media action.
  9. Show OBS history in the website.

This demonstrates the complete chain:

website → backend → relay → OBS Agent → OBS Studio

About

No description or website provided.

Topics

electron typescript obs-websocket zxc balkon 1000-7

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 10

Balkon OBS Agent v0.2.5 Latest
Apr 30, 2026
+ 9 releases

Packages

 
 
 

Contributors

Languages