How to debug a Roku channel in VS Code without a Roku

Normally, debugging BrightScript needs a Roku on your desk. You switch it to developer mode, set a password, put its IP address in launch.json, and keep your laptop on the same network as the device. That works when you sit next to the device. It doesn’t when the Roku is in the office and you are at home, when a contractor needs to fix a crash, or when the only Roku in the team is plugged into someone else’s TV.

vibeview dev --roku-debug keeps the debugging workflow you already have, and the device comes from VibeView. The BrightScript Language extension behaves as it would with a Roku on your desk. The channel runs on a physical Roku that streams to your browser.

What you need

• VS Code with the BrightScript Language extension installed
• A Roku channel project that you can already package, for example one with a bsconfig.json or an existing BrightScript launch configuration
• The VibeView CLI, version 0.63.0 or later, signed in:

npm install -g vibeview
vibeview login

Start debugging

Run the command again while it is running and it prints the link to the session that is already up. It doesn’t start a second one.

What works

In VS Code	On the VibeView Roku
Breakpoints	The channel stops on the line, and the stream freezes with it
Pause, continue, step in/over/out	The channel pauses, resumes, or moves on one statement at a time
Variables and expressions	Locals, m, and expressions evaluated while the channel is stopped
Runtime errors	The channel stops on the crash line with the error and the call stack
Restart	Your new build is packaged, installed and started under the debugger
Debug Console	Your channel’s print output, plus the session link when the debugger attaches

The session’s Logs tab and vibeview logs keep working while you debug, so you can share the console output with someone who is watching the session rather than running VS Code.

What doesn’t work yet

• SceneGraph debug commands. The extension’s SceneGraph debug commands, and the features built on them such as rendezvous tracking, are not available. The generated configuration turns rendezvous tracking off.
• Telnet-mode debugging. The configuration always uses the BrightScript debug protocol.
• Remote keys from the extension. Keys and Home sent from VS Code do nothing, because the session keeps the device inside your channel. Use the remote in the browser instead.

How it fits into a session

• Each start is a build. Each time you start or restart debugging, your package is uploaded as a build of the channel’s app, as a vibeview dev reload does. If the project has no VibeView app yet, the first start creates it.
• VS Code drives reloads. There is no r key and no --watch in this mode. Start, restart and stop from VS Code.
• A breakpoint counts as use. While the channel is stopped at a breakpoint or on an error, the session counts as in use for up to 30 minutes, so the idle timeout doesn’t end it while you read the stack. After that, the usual idle timeout applies.
• Stopping doesn’t end the session. When you stop the debugger, the channel closes. VibeView relaunches it, and it runs normally again after about 35 seconds. End the session with vibeview dev-stop. Use vibeview dev-status to check on it.
• Local ports. The extension expects to find a Roku on your own computer, so ports 8060, 80, 9801, 9803 and 9805 must be free there. The command tells you if one is taken. On Linux, or when another program already uses port 80, the extension fails at its password check.

When this helps most

• No Roku nearby. Debug a crash from home, while traveling, or on a laptop that can’t reach the office network.
• A crash a teammate found. Turn on Collaborate and send them its link so they can watch while you step through the code. Only the session’s owner and organization admins can attach the debugger.
• Agent-written code. If a coding agent wrote the channel change, let it test the channel on a VibeView Roku first. Then step through whatever it got wrong yourself.

Frequently asked questions

Do I need a Roku in developer mode? No. The channel runs on a Roku in VibeView’s cloud, and VibeView handles developer mode, sideloading and the device password. The configuration in your launch.json points at your own computer and holds only a placeholder password, never a device’s address or password.

Which VS Code extension does this use? The BrightScript Language extension from the RokuCommunity project, the extension most Roku developers already use. VibeView doesn’t need a separate debugger extension.

Is it a Roku emulator? No. The channel runs on a physical Roku, so playback, performance and crashes are what a viewer’s device does. Every Roku emulator option compares the alternatives.

Does it work with my build setup? Usually without changes. The VibeView configuration copies the build settings of your existing BrightScript configuration, including rootDir, files, bsConfig and packageTask. Make build changes in your own configuration: the command copies its settings again each time it runs.

Can I use it with a regular vibeview dev session? Not at the same time for the same project. Stop the regular session first, then run vibeview dev --roku-debug. The full reference is in Debugging a channel in VS Code.

Try it on your channel

Install the BrightScript Language extension, run vibeview dev --roku-debug in your channel project, and set a breakpoint on the line you’re unsure of. Roku sessions are on every plan. The free plan needs no card, but its sessions end after five minutes, so longer debugging needs a paid plan.