How to Sideload a Channel on Roku: Enable Developer Mode and Install Your App

Sideloading is the fastest way to get your channel running on a real Roku. You enable Developer Mode on the device, then upload your channel as a ZIP through a small web page the device hosts - no store submission, no review, and no need to match any particular Roku account. It is the everyday loop you use to test and iterate before you ever package or publish. Here is the whole process, step by step.

What sideloading is (and what it is not)

Sideloading installs an unpacked channel ZIP directly onto a Roku in Developer Mode so you can run and debug it. It is meant for development and testing on your own device.

It is not the same as publishing. Sideloading does not submit anything to the Roku Channel Store, and - importantly - it does not care which Roku account the device is signed into. The account only matters later, when you upload a packaged channel to the developer portal - that requires your developer.roku.com account to have a Roku device associated with it: see linking a device to your developer account.

What you need

• A retail Roku device. Developer Mode is free on any Roku - you do not need a paid account to sideload.
• The device and your computer on the same network.
• Your channel source zipped up, with the manifest file at the root of the ZIP.

Step 1: Enable Developer Mode

On the Roku remote, press this exact sequence:

1. Home x3, Up x2, Right, Left, Right, Left, Right.
2. The Developer Settings screen appears. Read and accept the SDK license agreement.
3. Set a web server password when prompted, and note the device IP address shown on screen.
4. Choose Enable installer and restart. The device reboots into Developer Mode.

You only do this once per device. Developer Mode stays on until you turn it off or factory reset.

Step 2: Confirm Developer Mode is on

On your computer, open http://<device-ip> in a browser, using the IP from Step 1. You should see the Development Application Installer page. Sign in with the username rokudev and the web server password you just set.

If the page does not load, the device is not in Developer Mode yet, or your computer is on a different network or VLAN than the Roku.

Step 3: Package your channel as a ZIP

Roku expects a flat ZIP with the manifest file at the top level, not nested inside a folder. A typical channel looks like this before zipping:

my-channel/
  manifest            ← required, must be at the ZIP root
  source/             ← BrightScript (.brs)
  components/         ← SceneGraph (.xml + .brs)
  images/             ← channel art, splash, icons

Select the contents of the channel folder and compress those, so the ZIP opens straight onto manifest, source/, and the rest. Zipping the parent folder, so the archive contains my-channel/manifest, is the single most common sideload failure.

Step 4: Upload and install

1. On the Development Application Installer page, click Upload and choose your ZIP.
2. Click Install, or Replace if a dev channel is already loaded.
3. The page reports Application Received / Install Success, and the channel launches on the TV.

Your sideloaded channel now appears on the Roku home screen as a dev channel and stays there until you replace or delete it.

Step 5: Iterate and debug

To push a code change, just re-zip and use Replace on the same page - it swaps the running dev channel in seconds.

For logs and a live BrightScript console, open a telnet session to the device on port 8085 (telnet <device-ip> 8085). That is where print output and runtime errors show up while the channel runs.

Automate it: zip and install from the terminal

Once you have done it by hand, you can fold the zip and upload (Steps 3 and 4) into a single command, so your iterate loop becomes one keystroke. Save this as sideload.sh next to your channel folder:

#!/usr/bin/env bash
# sideload.sh - zip a Roku channel and install it to a device in Developer Mode.
# Usage:  ROKU_IP=192.168.1.50 ROKU_PASS=yourpass ./sideload.sh [channel-dir]
set -euo pipefail

ROKU_IP="${ROKU_IP:?set ROKU_IP to your Roku IP (Settings, Network, About)}"
ROKU_PASS="${ROKU_PASS:?set ROKU_PASS to your Developer Mode web server password}"
SRC="${1:-.}"
ZIP="$(pwd)/channel.zip"

# 1. Zip the channel so the manifest sits at the archive root.
test -f "$SRC/manifest" || { echo "No manifest found in $SRC"; exit 1; }
rm -f "$ZIP"
( cd "$SRC" && zip -rq "$ZIP" . -x ".git/*" ".DS_Store" "*/.DS_Store" )
echo "Built $ZIP"

# 2. Upload to the device. "Install" also replaces an existing dev channel.
result=$(curl -sS --user "rokudev:$ROKU_PASS" --digest \
         -F "mysubmit=Install" -F "archive=@$ZIP" -F "passwd=" \
         "http://$ROKU_IP/plugin_install")
echo "$result" | grep -oE "Install Success|Identical to previous version|Failed" \
  || echo "Uploaded - check your Roku screen for the result."

It posts to the same /plugin_install endpoint the web page uses, with HTTP digest auth (rokudev plus your web server password). Make it executable once, set your device IP and password, and run it from your channel folder:

chmod +x sideload.sh        # once
export ROKU_IP=192.168.1.50
export ROKU_PASS=yourdevpassword
./sideload.sh            # zip the current folder and install
./sideload.sh ./out      # or point it at a build directory

Re-run it after every code change - that, plus the telnet console from Step 5, is the whole Roku dev loop. The script needs only bash, zip, and curl, which ship with macOS and Linux (on Windows, use WSL or Git Bash).

Common sideloading errors

• manifest not found. The manifest file is not at the ZIP root - you zipped the parent folder. Re-zip the folder contents instead.
• The installer page will not load. Developer Mode is off, you used the wrong IP, or the computer and Roku are on different networks.
• Login rejected. The username is always rokudev; the password is the web server password you set when enabling Developer Mode. Forgot it? Re-run the dev-mode remote sequence to set a new one.
• Install Failed. Usually a manifest error (missing required keys) or a packaging mistake - check the console on port 8085 for the specific reason.

The bottom line

Sideloading is the everyday loop of Roku development: enable Developer Mode once, then upload a ZIP whenever you want to test a build - on any account, with no store submission. When the channel is ready to ship, that is when you package it and upload to the developer portal. OTT Engine takes it further and builds, packages, and submits production Roku channels for you. Book a demo to see it in action.

Frequently Asked Questions