IRIDESC E UX · COMMAND

v30 · Program Primary Revision

INTERNALSTEP-BY-STEP

OBS, Server & Broadcast Agent

Every step from OBS WebSocket to trusted agent, service authentication, private test, realtime Worker, and Safety Worker.

OBS WebSocket safety rule

Never expose OBS WebSocket port 4455 directly to the public Internet. Command talks to a trusted local Broadcast Agent; the agent talks to OBS locally/LAN-side. This is the whole purpose of the agent architecture.

Prepare OBS

Open OBS WebSocket settings

OBS → Tools → WebSocket Server Settings

Enable the WebSocket server. Set a strong password.

Keep it local/trusted

OBS computer/network

Bind/use localhost or trusted LAN as appropriate. Do not port-forward 4455 from your router.

Record exact scene/source names

OBS

Command/agent actions depend on exact scene/input names. Rename carefully and update configuration when names change.

Install the Broadcast Agent

Open Terminal in `broadcast-agent`

OBS computer

cd "/path/to/repo/broadcast-agent"
npm install

Expected: Dependencies install.

Create local environment configuration

OBS computer

Use .env.example as a reference. Put real values in local process environment or an ignored .env; never commit them.

Set OBS connection values

Agent environment

OBS_WS_URL=ws://127.0.0.1:4455
OBS_WS_PASSWORD=YOUR_STRONG_OBS_PASSWORD

Set the shared Command/agent secret

Cloudflare Command secret + Agent environment

Generate one high-entropy BROADCAST_AGENT_TOKEN. Store the same value as a Cloudflare Secret on Command and in the trusted agent environment.

If Agent API is behind Access, create machine credentials

Cloudflare Access

Create a Cloudflare Access service token and set CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET in the agent. Do not use a human OTP flow for a headless agent.

Start the agent

Terminal

npm start

Expected: Agent begins polling Command and reporting status.

Agent architecture

Command button
  → protected /api/agent/* + D1 queue
  → Broadcast Agent polls over HTTPS
  → validates Access service credentials + BROADCAST_AGENT_TOKEN
  → OBS WebSocket on localhost/LAN
  → executes scene/stream/mute/record command
  → reports result/status back to Command

First agent test — never start with live stream

Create a harmless OBS test scene.
Start agent.
Confirm Command System Health sees agent online.
Queue a scene switch to the test scene.
Verify OBS changes.
Test mute/unmute on a disposable/test input.
Test record start/stop if used.
Only after those pass, test stream actions on a private/unlisted test destination.
Rehearse backup-feed and emergency-stop behavior.

Optional realtime Worker

Copy hvn-realtime-worker/wrangler.toml.example to a local wrangler.toml.
Create a long random Worker secret PUBLISH_TOKEN.
Deploy Worker.
HVN Pages: set HVN_REALTIME_URL to Worker origin.
Command Pages: set HVN_REALTIME_CONTROL_URL to Worker origin.
Command secret: set HVN_REALTIME_PUBLISH_TOKEN to the same publish secret.
Redeploy both affected projects.
Verify viewer can subscribe but browser JavaScript cannot read the publish token.

D1 stays authoritative; realtime is only the speed layer.

Optional Safety Worker

Review hvn-safety-worker/wrangler.toml.example.
Bind the shared D1 database as required by the Worker configuration.
Set NWS_USER_AGENT to an identifying operational contact string.
Create MANUAL_RUN_TOKEN if the manual run endpoint is enabled.
Leave SAFETY_AI_ENABLED=false unless Workers AI is intentionally configured.
Leave SAFETY_AUTO_TAKE_ENABLED=false until a written/rehearsed policy exists.
Deploy and verify it writes candidate alerts, not automatic on-air presentation.