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 (VVD) 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.

Options for running apps on Vega Virtual Device

You can run your Vega app using Vega Studio’s user interface (UI) or Vega CLI.

Option 1: Using Vega Studio UI

Navigate to Vega Studio > Devices and select VirtualDevice:Tv.
Select the play button to start the virtual device.
Wait for the VVD window to open and the device to finish loading. The VirtualDevice:Tv status should show as ready, not “Loading…”
Select the play button next to your project name. Your app launches and appears in the Vega Virtual Device window.

Option 2: Using Vega CLI

Start the Vega Virtual Device from the command prompt:

vega virtual-device start

The command waits until the Vega Virtual Device has booted.

Launching virtual device.
Waiting for virtual device to boot.
Virtual device ready.

The Vega Virtual Device might time out during boot. Use the --timeout flag to extend the wait time if needed.Example:

vega virtual-device start --timeout 120

This command allows the virtual device to wait 120 seconds to complete the boot process.After you start the Vega Virtual Device, the UI opens in a new window.

Load and run your app:

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

Example output:

vega run-app sampleapp.vpkg com.amazondeveloper.sampleapp.main -d VirtualDevice

The -d flag specifies that you’re running the app on the Vega Virtual Device. 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:

vega run-app build/aarch64-release/sampleapp_aarch64.vpkg com.amazondeveloper.sampleapp.main -d VirtualDevice

x86_64 devices:

vega run-app build/x86_64-release/sampleapp_x86_64.vpkg com.amazondeveloper.sampleapp.main -d VirtualDevice

Options for stopping apps on Vega Virtual Device

You can stop your Vega app using Vega Studio’s UI or the command line.

Option 1: Using Vega Studio UI

Navigate to Vega Studio > Devices and select VirtualDevice:Tv.
Select the stop button. The VirtualDevice:Tv status changes to stopped and the VVD window closes.

Option 2: Using Vega CLI

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

vega virtual-device stop

The Vega Virtual Device window closes and the process terminates.

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. After the Vega Virtual Device launches, follow these steps:

Vega Virtual Device home screen showing the Register this device option in the top-right corner.

Select the Settings gear icon in the top-right corner of the Vega Virtual Device home screen. The Settings screen appears.
Select Account Settings. Two options appear: Amazon Account and Parental Controls.
Select Amazon Account. The Amazon Account screen appears with a Register Account button.
Select Register Account. A registration code appears on screen.
Open a browser.
Go to www.amazon.com/code.
Enter the registration code displayed on the Vega Virtual Device.
Back on your Vega Virtual Device screen, wait for the “Your device has successfully been registered” confirmation.
Select OK.

Customize the Vega Virtual Device on launch

The Vega Virtual Device provides customization options on launch. When running the start command, you can use the following flags:

Suppress the graphical user interface (GUI):
vega virtual-device start --no-gui
Turn off OpenGL acceleration (Ubuntu x86 only):
vega virtual-device start --no-gl-accel
Modify the default display resolution:
vega 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:
vega 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

Dump rendered contents

The Dump Rendered Contents feature lets you inspect the content currently displayed on the Vega Virtual Device screen. It provides two output formats: a complete XML render tree of the UI hierarchy and a plain text extraction of visible text. Use it for debugging layout issues, verifying UI content, auditing accessibility properties, or extracting text for localization testing.To dump rendered contents:

Open the context menu anywhere on the Vega Virtual Device screen.
Select one of the following options from the context menu:
- Dump Render Tree: Exports the complete XML representation of the UI hierarchy, including all component properties, positions, and attributes. This output is the same as the App Source available in Appium Inspector. Use this option to debug layout issues, audit accessibility properties like focusable states and roles, or understand the UI structure for writing automation tests.
- Dump Rendered Text: Extracts only the visible text content from the UI.
Use this option for quick content verification, such as checking error messages, validating localized strings, or reviewing on-screen copy.
In the file save dialog that appears, choose a location and filename.
- Render Tree saves as .xml by default.
- Rendered Text saves as .txt by default.
The file opens automatically in your default application after saving.

Dump Render Tree output example (XML):

<?xml version="1.0"?>
<root id="1">
  <app id="4294967297" appName="com.amazon.myapp">
    <window x="0" y="0" width="1920" height="1080" id="4294967298">
      <child x="100" y="200" width="300" height="50" role="button" focusable="true">
        <text>Click Me</text>
      </child>
    </window>
  </app>
</root>

Dump Rendered Text output example (TXT):

Click Me
Welcome to the App
Settings

Enable Parental Controls

Parental Controls let you test how your app behaves when app launch protection is active on the device. Use this feature to verify your app handles the PIN gate correctly during development.To enable Parental Controls:

Register your Vega Virtual Device (if you haven’t already). See Register the Vega Virtual Device.
From the Account Settings screen, select Parental Controls. The Parental Controls screen appears with an Enable Parental Controls button.
Select Enable Parental Controls.
Create or enter your Prime Video PIN using the circular dial on screen. This is the PIN associated with your Amazon account. If you haven’t set one up, the device prompts you to create a new 5-digit PIN. You can also manage your PIN at amazon.com/pin. Use the virtual remote’s directional pad to navigate numbers (0–4 displayed by default, select 5-9 to toggle the higher digits).
Wait for the PIN to validate. After successful validation, the Parental Controls settings screen appears with the following options:
- Disable Parental Controls: Turns off parental controls.
- Change PIN: Updates your Prime Video PIN.
- Protect App Launches: ON: When enabled, a PIN prompt appears every time an app is launched on the device.

To test the app launch protection:After enabling Parental Controls with Protect App Launches: ON, navigate to the home screen and launch any app. The PIN entry dialog appears over the “Your apps” screen. The app only launches after the user enters a valid PIN.To disable Parental Controls:

Select the Settings gear icon > Account Settings > Parental Controls.
Select Disable Parental Controls.
Enter your PIN when prompted.

Keyboard shortcuts

Use these keyboard shortcuts to control the Vega Virtual Device:

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

Provide feedback about the Vega Virtual Device

You can share feedback about your Vega Virtual Device experience directly from the emulator or terminal. The system doesn’t collect personally identifiable information. Only session metadata (VVD version, image type, host OS) accompanies the feedback.From the emulator (macOS and Linux):Open the context menu anywhere on the Vega Virtual Device screen and select Send Feedback…. A short survey opens in your desktop browser.From the macOS menu bar:Select Feedback > Provide Feedback… in the application menu bar while the Vega Virtual Device is running.From the terminal:Run the following command to open the feedback survey at any time:

vega virtual-device feedback

Additionally, after running vega virtual-device stop, a one-line prompt asks how the session went. Press 1 (positive), 2 (negative), or Enter (skip). On negative feedback, the survey opens in your browser.

How was this VVD session? 👍 👎 [Skip]

After you provide feedback, the CLI prompt won’t appear again for 7–14 days. The GUI entry points (menu bar, context menu) are always available and never interrupt your workflow.To disable the CLI prompt:Set the following environment variable:

export KEPLER_CSAT_DISABLED=true

The prompt also auto-skips in CI/CD pipelines and non-interactive terminals.

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.

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

​Options for running apps on Vega Virtual Device

​Option 1: Using Vega Studio UI

​Option 2: Using Vega CLI

​Options for stopping apps on Vega Virtual Device

​Option 1: Using Vega Studio UI

​Option 2: Using Vega CLI

​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

​Dump rendered contents

​Enable Parental Controls

​Keyboard shortcuts

​Provide feedback about the Vega Virtual Device

​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

Options for running apps on Vega Virtual Device

Option 1: Using Vega Studio UI

Option 2: Using Vega CLI

Options for stopping apps on Vega Virtual Device

Option 1: Using Vega Studio UI

Option 2: Using Vega CLI

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

Dump rendered contents

Enable Parental Controls

Keyboard shortcuts

Provide feedback about the Vega Virtual Device

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