Run Your App on Vega Virtual Device or Fire TV

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

1. Install the Vega SDK.

   Warning: If your app uses @amazon-devices/kepler-ui-components, you must use the latest SDK version (0.22 or later) for VVD testing. Older VVD versions don't include the required native modules and will fail with module dependency errors. For apps built with older SDKs, test on a physical Fire TV Stick instead.

2. 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.

3. (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

1. Navigate to Vega Studio > Devices and select VirtualDevice:Tv.

2. Select the play button to start the virtual device.

3. Wait for the VVD window to open and the device to finish loading.

   The VirtualDevice:Tv status should show as ready, not "Loading…"

4. 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

1. Start the Vega Virtual Device from the command prompt:

   Copy code Copied to clipboard.

   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.
   

   Note: The Vega Virtual Device might request microphone access on first launch. If the dialog appears, you can allow or deny it. Either choice is safe to make because the Vega Virtual Device doesn't use the microphone. If the dialog doesn't appear, no action is needed and your development or testing experience isn't affected.

   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.

2. Load and run your app:

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

   Example output:

   vega run-app sampleapp.vpkg com.amazon.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:

   Copy code Copied to clipboard.

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

   x86_64 devices:

   Copy code Copied to clipboard.

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

   Tip: After initial installation, use vega device launch-app for subsequent launches. App data persists between launches.

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

1. Navigate to Vega Studio > Devices and select VirtualDevice:Tv.

2. 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:

1. Select the Settings gear icon in the top-right corner of the Vega Virtual Device home screen.

   The Settings screen appears.

   

2. Select Account Settings.

   Two options appear: Amazon Account and Parental Controls.

   

3. Select Amazon Account.

   The Amazon Account screen appears with a Register Account button.

   

4. Select Register Account.

   A registration code appears on screen.

5. Open a browser.

6. Go to www.amazon.com/code.

7. Enter the registration code displayed on the Vega Virtual Device.

8. Back on your Vega Virtual Device screen, wait for the "Your device has successfully been registered" confirmation.

   

9. 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):

  Copy code Copied to clipboard.

    vega virtual-device start --no-gui
  

• Turn off OpenGL acceleration (Ubuntu x86 only):

  Copy code Copied to clipboard.

    vega virtual-device start --no-gl-accel
  

  Tip: OpenGL acceleration improves graphics performance. Turn it off only when troubleshooting display issues on Ubuntu x86 systems.

• Modify the default display resolution:

  Copy code Copied to clipboard.

    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:

1. Open the virtual device's shell:

   Copy code Copied to clipboard.

   vega device shell -d VirtualDevice
   

2. Enable Developer Mode:

   Copy code Copied to clipboard.

   vsm developer-mode enable
   

   The VVD reboots after this command. Repeat step 1 to reconnect to the virtual device's shell.

3. Verify full functionality:

   Copy code Copied to clipboard.

   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:

1. Open the context menu anywhere on the Vega Virtual Device screen.

   

2. 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.

3. 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.

4. 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:

1. Register your Vega Virtual Device (if you haven't already).

   See Register the Vega Virtual Device.

2. From the Account Settings screen, select Parental Controls.

   The Parental Controls screen appears with an Enable Parental Controls button.

   Note: If Enable Parental Controls is grayed out, your Vega Virtual Device isn't registered. Follow the instructions in Register the Vega Virtual Device before proceeding.

   

3. Select Enable Parental Controls.

4. 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).

5. 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:

1. Select the Settings gear icon > Account Settings > Parental Controls.

2. Select Disable Parental Controls.

3. Enter your PIN when prompted.

Keyboard shortcuts

Use these keyboard shortcuts to control the Vega Virtual Device:

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.