Roku Distribution

Roku distribution is more involved than iOS or Android because the Roku Channel Store does not accept the build artifact directly. You must:

1. Build a sideload ZIP in the admin panel.
2. Install (sideload) that ZIP onto a real Roku device in developer mode.
3. Use the device’s on-device packager to wrap the installed channel into a signed .pkg file.
4. Upload the signed .pkg (not the ZIP) to the Channel Store.

Before starting, make sure you’ve completed the shared Prerequisites in App Configuration.

Follow the steps below in order. They are written assuming you have never done this before.

Caution

The three passwords you will encounter are different and not interchangeable. Mixing them up is the most common reason Roku packaging fails:

#	Password	Where you set it	Where you use it	Looks like
1	Developer install code	Typed on the TV during dev-mode setup	One-time, on the TV, to enable developer mode	6-digit number
2	rokudev web password	You choose it in the dev-mode setup screen	Browser login at http://<roku-ip> (username = rokudev)	Whatever you chose
3	Signing key password	Roku generates it when you run genkey over telnet on port 8080	The Packager form, every time you produce a .pkg	Random ~6-char string

Most “Failed: Invalid Password” errors during packaging are caused by typing #2 into the Packager form when it wants #3.

Step 1 — Create a Roku Developer Account

Register at developer.roku.com if you haven’t already. Developer accounts are free.

Step 2 — Enable Developer Mode on Your Roku Device

You need a physical Roku device (or a supported emulator). On the device:

1. From the Roku home screen, press the remote sequence: Home × 3, Up × 2, Right, Left, Right, Left, Right

2. A “Developer Settings” screen appears. Enable installer, then accept the developer agreement

3. The screen asks you to set up the developer web server. Choose a password — this is the rokudev web password (#2 in the table above). Write it down

4. Note the device IP address shown on screen — you’ll use it as <roku-ip> throughout the rest of this guide

5. The device reboots into developer mode

Roku’s Developer Setup Guide has screenshots if you get stuck.

Step 3 — Upload Roku Branding Assets in the Admin Panel

In the admin panel, go to App Studio → Distribution → Roku and upload the following images:

Image	Size	Description
Channel Poster (FHD)	540 x 405 px	Main channel icon on Roku home
Channel Poster (HD)	290 x 218 px	Channel icon for HD displays
Splash Screen (FHD)	1920 x 1080 px	Loading screen on FHD displays
Splash Screen (HD)	1280 x 720 px	Loading screen on HD displays

Step 4 — Set Store URL (Skip if Your Channel Is Not Published Yet)

If your channel is already live on the Roku Channel Store, paste its public listing URL (for example, https://channelstore.roku.com/details/<channel-id>/<channel-name>) into the Store URL field. You can find this URL in your Roku Developer Dashboard under the channel’s listing details.

Leave this blank for the first submission — it’s not required to build or to submit.

Step 5 — Build the Sideload ZIP in the Admin Panel

1. In App Studio → Distribution → Roku, click Build. The build typically completes in under a minute

2. When it finishes, click Download Build and save the ZIP file to your computer

This ZIP is the sideload artifact. You cannot submit it to the Channel Store as-is — the next steps wrap it into a signed .pkg.

Step 6 — Generate a Signing Key on the Device (First Time Only)

You only need to do this once per device. The signing key identifies your developer account on the Channel Store — every channel you ever publish from this device shares one identity, and you cannot recover the key if you lose it.

Roku’s official method uses a genkey command over telnet on port 8080:

1. Open a terminal on your computer (Mac/Linux: built-in Terminal; Windows: PuTTY or any Telnet client)

2. Connect to the Roku:

   telnet <roku-ip> 8080

   On macOS, the system telnet was removed in Catalina. Install one with brew install telnet, or use nc <roku-ip> 8080 instead.

3. At the prompt, type the command:

   genkey

4. Wait for the process to finish (typically under a minute). The device prints something like:

   Password: aB3xY9Qz
   DevID:    1a2b3c4d5e6f7g8h9i0jklmnopqrstuvwxyz1234

5. Copy both values into a password manager immediately. The Password is the signing key password (#3 in the table at the top) — you’ll need it every time you re-package. Roku does not have a recovery flow if you lose it.

6. Close the telnet session

Caution

Do not lose the signing key password. If you lose it:

• Running genkey again creates a brand-new key with a different DevID.
• The Channel Store treats any submission signed with a different key as a brand-new channel — you cannot publish updates to your existing live channel under the old identity.
• There is no recovery: Roku staff cannot restore a lost key.

Step 7 — Sideload the Channel ZIP onto Your Roku Device

1. On a computer on the same network as the Roku, open a browser and go to http://<roku-ip> (use the IP from Step 2)

2. A login dialog appears. Enter:

   • Username: rokudev (always this exact string — you do not choose it)
   • Password: the rokudev web password you set in Step 2 (password #2 in the table at the top)

3. You land on the Development Application Installer page. Use the file picker to select the ZIP from Step 5, then click Install

4. The channel launches automatically on the TV. Verify it works correctly before continuing

Tip

If the browser login fails with an authentication prompt, you typed the developer install code (the 6-digit number from Step 2 #1) instead of the rokudev web password (password #2).

Step 8 — Package the Sideloaded Channel into a Signed .pkg

After sideloading in Step 7, click the Packager link in the upper-right corner of the Development Application page (or navigate directly to http://<roku-ip>/plugin_package).

1. On the Application Packager page, confirm the Dev ID at the top matches the one you saved in Step 6

2. Fill in the form:

   • App Name: the user-visible channel name (e.g. My Streaming App)
   • Version: must match the version in your channel’s manifest (the admin panel sets this automatically during the build)
   • Password: the signing key password from Step 6 (password #3 in the table at the top) — not the rokudev web password from Step 7

3. Click Package. After a few seconds, a link to the signed .pkg file appears in the Currently Packaged Application section. Click it to download

Caution

If you see “Failed: Invalid Password” here, you almost certainly typed the rokudev web password (password #2 — the one you just used to log into the browser) instead of the signing key password (password #3 — the value genkey printed in Step 6). They are completely separate. Open your password manager and paste #3 exactly.

If you’ve lost the signing key password, your only option is to re-run genkey from Step 6 — but see the warning in Step 6 about what that means if you already have a live channel on the Channel Store.

Step 9 — Submit the .pkg to the Channel Store

1. Go to the Roku Developer Dashboard and sign in

2. Create a new app (or open the management page for an existing one to publish an update)

3. On the app’s management page, click App package, then upload the .pkg from Step 8 in the “Upload your .pkg or .zip file” field — not the ZIP from Step 5

4. Fill in the remaining store listing sections (Streaming store assets — app name, descriptions, poster, screenshots — and Listing setup — countries, region, made-for-kids status, category, age rating) and submit for review. See Roku’s Channel Publishing Guide for the exact field requirements

Tip

The sideload ZIP from Step 5 is reusable: as long as the underlying code hasn’t changed, you can re-run Steps 6–8 to produce a new .pkg without rebuilding in the admin panel.

Troubleshooting

Missing branding assets

Upload the required channel poster and splash screen images in App Studio → Distribution → Roku. All four images (Channel Poster FHD/HD, Splash Screen FHD/HD) are required for a successful build.

”Package file has an invalid header” on Channel Store upload

You uploaded the sideload ZIP from Step 5 directly instead of the signed .pkg from Step 8. The Channel Store only accepts signed .pkg files. Go back through Steps 6–8 to produce one.

”Failed: Invalid Password” in the Packager form

See the caution callout under Step 8. You almost certainly typed the rokudev web password (#2) when the form expects the signing key password generated by genkey (#3).