Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

AWS

Documentation

Support

My Cases

Console

Vega Developer Docs

Home

Get Started

Design and Develop

Publish

Reference

Support

Run Your App on Vega Virtual Device or Fire TV Stick

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the Release Notes.

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

Important: You can use Vega Virtual Device for initial development and testing, but you must test your app on a Fire TV Stick before submitting to the Amazon Appstore.

Vega Virtual Device
Fire TV Stick

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.

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 (VirtualDevice:Tv status should be ready, not 'Loading…')
Select the play button next to your project name.

Option 2: Using Vega CLI

At the command prompt, start the Vega Virtual Device:
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.
```
The Vega Virtual Device might:
- Request microphone access on first launch.
- Time out during boot. Use the --timeout 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 Vega Virtual Device user interface opens on a new window.
Load and run your app:
Copied to clipboard.
```
vega run-app <vpkg-path> <app-id> -d VirtualDevice
```
The -d flag specifies that you're running the app on the Vega Virtual Device.

Example:
```
vega run-app sampleapp.vpkg com.amazon.sampleapp.main -d VirtualDevice
```
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:
Copied to clipboard.
```
vega run-app build/aarch64-release/sampleapp_aarch64.vpkg com.amazondeveloper.sampleapp.main -d VirtualDevice
```
x86_64 devices:
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

Navigate to Vega Studio > Devices and select VirtualDevice:Tv.
Select the stop button.

Option 2: Using Vega CLI

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

Copied to clipboard.

vega 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 Vega 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):
Copied to clipboard.
```
 vega virtual-device start --no-gui
```
Turn off OpenGL acceleration (Ubuntu x86 only):
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:
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:

Open the virtual device's shell:
Copied to clipboard.
```
vega device shell -d VirtualDevice
```
Enable Developer Mode:
Copied to clipboard.
```
vsm developer-mode enable
```
The VVD reboots after this command. Repeat step 1 to reconnect to the virtual device's shell.
Verify full functionality:
Copied to clipboard.
```
inputd-cli --help
```

Note: Developer Mode enables advanced inputd-cli commands like touch, swipe, button_press, and send_text. Without Developer Mode, you can only use basic commands (get_camera_cover_open_close, get_mic_state, get_screen_size).

Configure the keyboard language settings

The virtual device supports English (EN) and Japanese (JP).

To switch to Japanese keyboard:

Start the virtual device:
Copied to clipboard.
```
 vega virtual-device start
```
Open the virtual device’s shell:
Copied to clipboard.
```
 vega device shell -d VirtualDevice
```

Switch to Japanese:

Copied to clipboard.

 vdcm set com.amazon.devconf/system/configuration/locale ja-JP

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.

Run your app on Fire TV Stick

Running your Vega app on a Fire TV Stick 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 Stick 4K Select for development, enabling Developer Mode, and sideloading your Vega app for testing.

Warning: Fire TV Stick might restart if underpowered through computer USB. If you encounter this issue, see Resolve Fire TV Stick Issues.

Prerequisites

Step 1: Set up and register your Fire TV Stick

Warning: Ensure you're using the remote that came with your Fire TV Stick 4K Select. Fire OS device remotes from other Fire TV devices aren't compatible with Vega devices and cause pairing issues during development and testing.

To set up and register your Fire TV Stick

Connect your Fire TV Stick:

a. To your development machine using USB cable.

b. To a display using the HDMI adapter.

The remote pairing screen appears.
Complete remote pairing:

a. Press Home button when prompted.

b. Follow on-screen instructions.

c. Wait for Fire TV logo to appear.
Configure settings:

a. Press Play/Pause on your remote.

b. Select your preferred language.

c. Connect to your network.

d. Enter your network credentials.

Warning: The device checks for over-the-air (OTA) updates. Don't power off or restart your device until updates complete. Interrupting the update might prevent network discovery.
Complete device registration:

a. Sign in to your Amazon account either online or through QR code.

b. Follow on-screen instructions.

c. Wait for "Successfully registered" message.
Press OK when you see "Your Fire TV remote is now successfully set up."

Step 2: Register Fire TV Stick for Developer Mode

Developer Mode allows you to sideload apps and test development builds on your Fire TV device. Users with Administrator or Developer roles may automatically receive access to Developer Options for enabling Developer Mode.

To find your Device Serial Number (DSN):

Go to Settings > My Fire TV > About.
Look for "Serial Number" in the device information.

You can also find the DSN on the original packaging box or in your Amazon account under "Manage Your Content and Devices."

Important: Registration applies only to the Fire TV 4K Select model.

To register the Fire TV Stick:

Sign in using your Amazon developer account.
Paste your DSN into Device Serial Number (DSN) and select Add Device.

The DSN appears in the Registered Devices list.

Step 3: Configure Developer Mode

Note: When you enable Developer Mode, the device automatically reboots.

Access Settings using the Home button or the Home button shortcut.

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

Using Home button shortcut

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.

My Fire TV
Select Fire TV Stick.
Press the center button on the remote control 7 times.

Note: If you register the Fire TV Stick with an EU account, the Developer Options menu appears in My Fire TV.
Press the Back button to return to My Fire TV.

The Developer Options appears in the menu list.
Select Developer Options.

The display indicates the Developer Mode status, which is Disabled by default.
Click Developer Mode to enable it.
After device reboot, use the Back button on your remote and navigate to My Fire TV > Developer Options > Developer Mode.

The Developer Mode status should show Enabled.

Check device recognition.

Copied to clipboard.

 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:
Copied to clipboard.
```
vega device shell
```

If you have multiple devices connected, specify the DSN:

Copied to clipboard.

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):/$

Tip: Perform a factory reset of the device to hide the Developer option menu.

Step 4: Load your app on a Fire TV Stick

After you configure Developer Mode on your Fire TV Stick, open a new terminal and use the following commands to load your app:

One device connected to your computer

Replace <my-package.vpkg> with your package name.

Copied to clipboard.

vega device install-app --packagePath <my-package.vpkg>

Multiple devices connected to your computer

Use the following command to specify the target device. Replace <Device Serial Number> with your device's serial number and <my-package.vpkg> with your package name.

Copied to clipboard.

vega device -d <Device Serial Number> install-app --packagePath <my-package.vpkg>

Example output:

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

Note: The path to your .vpkg file may vary depending on your project structure and build configuration.

Step 5: Run your app on Fire TV Stick

After you load your app on your Fire TV Stick, use the following commands to run your app.

One device connected to your computer

Copied to clipboard.

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

Multiple devices connected to your computer Use the following command to specify the target device. Replace <Device Serial Number> with your device's serial number and <component-id> with your app's component ID.

Copied to clipboard.

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

Last updated: Jan 05, 2026

Run Your App on Vega Virtual Device or Fire TV Stick

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

Configure the keyboard language settings

Keyboard shortcuts

Set up Fast Refresh

Troubleshoot

Run your app on Fire TV Stick

Prerequisites

Step 1: Set up and register your Fire TV Stick

Step 2: Register Fire TV Stick for Developer Mode

Step 3: Configure Developer Mode

Step 4: Load your app on a Fire TV Stick

Step 5: Run your app on Fire TV Stick

Related topics