Run Your App on Vega Virtual Device or Fire TV

Learn how to use Vega Virtual Device or a Fire TV device to run your Vega apps. Each tool serves different development needs: Vega Virtual Device for rapid iterations and Fire TV Device for production-ready execution.

Vega Virtual Device
Fire TV Device

Run your app on Vega Virtual Device

The Vega Developer Tools (VDT) features a Vega Virtual Device that lets you test and run Vega apps without a physical device, giving you the following control options:

Mouse interaction directly on the virtual device
Virtual remote control interface
Keyboard shortcuts and commands

Prerequisites

Install the Vega SDK.
A Vega app ready to test. You can use an app you created from Vega SDK project templates, downloaded from a sample app, or built yourself.
(Optional) Register your Vega Virtual Device to use Amazon Services for testing.

Step 1: Start the Vega Virtual Device

At the command prompt, run:

kepler virtual-device start

The command waits until the Vega Virtual Device has booted.

Launching default instance.
Waiting for virtual device to boot.
Launch process complete.
Virtual device shell available.
Virtual device ready.

The Vega Virtual Device might:

Request microphone access on first launch.
Timeout on boot, but the optional --timeout argument allows you to wait longer.

After you start the Vega Virtual Device, the Vega Virtual Device user interface opens on a new window.

Step 2: Load and run your app

To load and run your app on Vega Virtual Device:

kepler run-kepler <vpkg-path> <app-id> -d VirtualDevice

The -d flag specifies that you’re running the app on the Vega Virtual Device.To load and run your app on Fire TV Stick:

kepler run-kepler <vpkg-path> <app-id> -d <Device Serial Number>

Make sure to replace:

with your app’s vpkg file path
with your app ID
with the serial number of your Fire TV Stick

Architecture-specific commands

The architecture of the virtual package (vpkg) must match the architecture of your development machine for proper execution. For example:Mac M-series devices:

kepler run-kepler build/aarch64-release/keplersampleapp_aarch64.vpkg com.amazondeveloper.keplersampleapp.main -d VirtualDevice

x86_64 devices:

kepler run-kepler build/x86_64-release/keplersampleapp_x86_64.vpkg com.amazondeveloper.keplersampleapp.main -d VirtualDevice

Step 3: Stop the virtual device

To stop the Vega Virtual Device, close your virtual device window, or run:

kepler virtual-device stop

Optional configurations

Register the Vega Virtual Device (only if you’re using Amazon services for testing)

To use Amazon Services for testing, register your Vega Virtual Device. When you see the Kepler Virtual Device has launched, follow these steps:

Click “Register this device” on the top right.
Record the registration code shown on screen.
Go to www.amazon.com/code and enter the code. Look for this message to confirm registration:

Your device has successfully been registered

Customize the Vega Virtual Device on launch

The Vega Virtual Device provides customization options on launch. When running the start command:

Suppress the graphical user interface (GUI):
kepler virtual-device start --no-gui
Turn off OpenGL acceleration (Ubuntu x86 only):
kepler virtual-device start --no-gl-accel

Modify the default display resolution:

kepler virtual-device start --display-res=1920,1080

Enable Developer Mode for full inputd-cli functionality

The Vega Virtual Device provides limited inputd-cli commands by default. Enable Developer Mode to access the full command set for automation and testing:

Open the virtual device’s shell:
kepler device shell -d VirtualDevice
Enable Developer Mode:
vsm developer-mode enable
The VVD reboots after this command. Repeat step 1 to reconnect to the virtual device’s shell.
Verify full functionality:
inputd-cli --help
Keyboard shortcuts
Use these keyboard shortcuts to control the Vega Virtual Device instead of clicking with your mouse:
Fire TV Stick remote button Vega Virtual Device keyboard key
Select ENTER
Up, Down, Right, Left Arrow keys
Back ESC
Homepage F1
Menu F2
Rewind F3
Play/Pause F4
Fast Forward F5

Set up Fast Refresh
To automatically detect code changes and display updates in real-time on your Vega Virtual Device, you can set up Fast Refresh.

Troubleshoot
If you encounter issues with the Vega Virtual Device, see Troubleshoot Vega Virtual Device Issues.

Fire TV Stick remote button	Vega Virtual Device keyboard key
Select	ENTER
Up, Down, Right, Left	Arrow keys
Back	ESC
Homepage	F1
Menu	F2
Rewind	F3
Play/Pause	F4
Fast Forward	F5

Run your app on Fire TV

Running your Vega app on a Fire TV device is essential for testing real device performance and ensuring compatibility before submitting to the Amazon Appstore. This section walks you through setting up your Fire TV device for development, enabling Developer Mode, and sideloading your Vega app for testing.Developer Mode allows you to sideload apps and test development builds on your device. All Vega Fire TV devices use the same Developer Mode enablement process.

Prerequisites

Install the Vega SDK.
Ensure you have the latest SDK Manager installed (run vega update to get the latest version).
A Fire TV device running Vega OS (for example, Fire TV Stick HD, Fire TV Stick 4K Select, or Fire TV Streaming Media Player). For a full list of supported devices, see Fire TV device specifications.

Step 1: Set up and register your Fire TV device

Before you proceed, ensure you’re using the remote that came with your Fire TV device. Remotes from other Fire TV devices cause pairing issues during development and testing.

Connect your Fire TV device: a. To your development machine using a USB cable. b. To a display using the HDMI adapter. The remote pairing screen displays.
Complete remote pairing: a. Press the Home button when prompted. b. Follow on-screen instructions. c. Wait for the Fire TV logo. If the Fire TV logo doesn’t appear within a few minutes, see Resolve Fire TV Stick Issues for troubleshooting steps.
Configure settings: a. Press the Play/Pause button on your remote. b. Select your preferred language. c. Connect to your network. d. Enter your network credentials.
Complete device registration: a. Sign in to your Amazon account either online or through QR code. b. Follow on-screen instructions. c. Wait for the “Successfully registered” message.
Press OK when you see “Your Fire TV remote is now successfully set up.”

Step 2: Configure Developer Mode

Developer Mode requires authentication with your Amazon Developer Account using the Vega CLI. The process involves retrieving an authentication code from your Fire TV device, authenticating through your browser, and completing device enablement from the terminal. Your device reboots automatically after enablement.

Access the Fire TV Settings menu: Option 1: Using Home button a. Press the Home button on your remote to go to the Home screen. b. Navigate to the top menu bar. c. Scroll right to find and select the Settings icon (gear symbol). Option 2: Using Home button shortcut (faster) a. Press and hold the Home button on your remote for 3 seconds. b. Select Settings from the quick menu that appears.
Go to Settings > My Fire TV > About.
Select your device name (for example, Fire TV Stick HD, Fire TV Stick 4K Select, or Fire TV Streaming Media Player).
Press the center button on the remote control seven times. A brief “You are now a developer” notification appears on screen after the seventh press.
Press the Back button to return to My Fire TV. Developer options appears in the list.
Select Developer options. Developer Mode (disabled by default) appears in the menu list.
Select Developer Mode to proceed.
Select Continue to proceed (or Cancel to abort). If you select Cancel, the dialog closes and you return to the Developer Options screen without changes. After selecting Continue, the Fire TV screen displays a 6-digit authentication code. You’ll enter this code in #11.
To authenticate with your Amazon Developer Account, run the login command:
vega devmode login
Follow the instructions from the CLI to complete authentication. The CLI automatically opens your default web browser to the Amazon authentication page. If the browser doesn’t open automatically, navigate to the URL provided in the terminal.
Authorize Vega CLI access in your browser. The Amazon OAuth consent screen displays “Vega Authentication Test would like access to:” along with your basic profile information and name. a. Review the requested permissions. b. Select Allow to authorize Vega Authentication Test (or Cancel to deny). If you select Cancel, the CLI denies authorization and displays an authentication error. Re-run vega devmode login to try again. After selecting Allow, a confirmation page appears with a checkmark icon and the message “Device connected to your account.” You can close this page. Return to your terminal. The CLI displays:
Login successful! You are now authenticated with Amazon Developer Services.
Enable the device using the 6-digit code displayed on your Fire TV screen:
vega devmode enable-device --code <6-digit code>
If your Amazon Developer account has only one vendor, the CLI displays:
Using vendor: Amazon ✓ Device enabled successfully
If your account has multiple vendors, the CLI prompts you to select one:
Select a vendor: 1. Amazon (XXXXXXXXXX) 2. Amazon (XXXXXXXXXX)
Enter the number corresponding to your vendor. The CLI then displays ✓ Device enabled successfully.
Wait for the device to reboot.
After the device reboots, navigate to Settings > My Fire TV > Developer Options > Developer Mode. The Developer Mode status displays Enabled.

Check device recognition.

vega device list

Example output with one device connected:

Found the following device:
[Serial Number] : [Device Number]

Example output with multiple devices connected:

Found the following devices:
[Serial Number] : [Device Number]
[Serial Number] : [Device Number]

Connect to the device.

If you have one device connected:
vega device shell

If you have multiple devices connected, specify the Device Serial Number:

vega device -d <Device Serial Number> shell

Example output:

(hostmachine)% vega device -d <Device Serial Number> shell

##################################################

##### Welcome to Developer Mode Shell #####

##################################################

sh(com.amazon.dev.shell):/$

Step 3: Load your app on a Fire TV device

After you configure Developer Mode on your Fire TV device, open a new terminal and use the following commands to load your app:Find your .vpkg fileWhen you build your app with vega build, the build process generates the .vpkg file in your project’s build/ directory. The path follows this pattern:

build/<ARCH>-<BUILD_TYPE>/<APP_NAME>_<ARCH>.vpkg

For Fire TV devices, use the armv7 architecture. For example, if your app is named sampleapp and you built a release variant:

build/armv7-release/sampleapp_armv7.vpkg

One device connected to your computerReplace with the path to your .vpkg file.

vega device install-app --packagePath build/armv7-release/sampleapp_armv7.vpkg

Multiple devices connected to your computerUse the following command to specify the target device. Replace with your device’s serial number and with the path to your .vpkg file.

vega device -d <Device Serial Number> install-app --packagePath build/armv7-release/sampleapp_armv7.vpkg

Example output:

Installing/Updating '/tmp/sampleapp_armv7.vpkg' .. success

Step 4: Run your app on Fire TV

After you load your app on your Fire TV device, use the following commands to run your app.One device connected to your computer

vega device launch-app --appName <component-id>

Multiple devices connected to your computerUse the following command to specify the target device. Replace with your device’s serial number and with your app’s component ID.

vega device -d <Device Serial Number> launch-app --appName <component-id>

Example output:

(hostmachine)% vega device -d <Device Serial Number> launch-app --appName com.amazondeveloper.sampleapp
Launching app 'com.amazondeveloper.sampleapp' .. success

Your app launches and appears on the connected Fire TV screen.

​Run your app on Vega Virtual Device

​Prerequisites

​Step 1: Start the Vega Virtual Device

​Step 2: Load and run your app

​Architecture-specific commands

​Step 3: Stop the virtual device

​Optional configurations

​Register the Vega Virtual Device (only if you’re using Amazon services for testing)

​Customize the Vega Virtual Device on launch

​Enable Developer Mode for full inputd-cli functionality

​Keyboard shortcuts

​Set up Fast Refresh

​Troubleshoot

​Run your app on Fire TV

​Prerequisites

​Step 1: Set up and register your Fire TV device

​Step 2: Configure Developer Mode

​Step 3: Load your app on a Fire TV device

​Step 4: Run your app on Fire TV

​Related topics

Run your app on Vega Virtual Device

Prerequisites

Step 1: Start the Vega Virtual Device

Step 2: Load and run your app

Architecture-specific commands

Step 3: Stop the virtual device

Optional configurations

Register the Vega Virtual Device (only if you’re using Amazon services for testing)

Customize the Vega Virtual Device on launch

Enable Developer Mode for full inputd-cli functionality

Keyboard shortcuts

Set up Fast Refresh

Troubleshoot

Run your app on Fire TV

Prerequisites

Step 1: Set up and register your Fire TV device

Step 2: Configure Developer Mode

Step 3: Load your app on a Fire TV device

Step 4: Run your app on Fire TV

Related topics