Enable Developer Mode - Amazon Vega Docs

Developer Mode (also called “dev mode”) enables you to sideload apps, debug components, and access your Fire TV device through the developer shell and VDA (Vega Device Adapter) over the network or USB interface. You can test apps, access secure shells, manage packages, and access the file system. Activating Developer Mode requires authentication with your Amazon Developer Account and reboots your device. All Vega Fire TV devices use the same Developer Mode enablement process. Estimated time to complete: 5–10 minutes

Prerequisites

Before you begin, make sure you have:

Amazon Developer Account (required for authentication) — Sign up if you don’t have one
Vega CLI installed on your development machine — verify with vega --version. See Install the Vega SDK if not installed
Latest SDK Manager — run vega update to get the latest version. See Vega SDK Manager
Fire TV device running Vega OS, connected to the same network as your computer. For a full list of supported devices, see Fire TV device specifications.

Authenticate Developer Mode on Fire TV

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

Developer Mode states

Developer Mode operates in enable, authenticating, and disable states. Enable state The enable state activates full developer features including vsh shell access, package management through vpm, and component debugging capabilities. Authenticating state The authenticating state indicates the system is validating developer mode access during enablement. Disable state The disable state restricts access to standard user features.

Development tools

Developer Mode provides access to essential tools for package deployment, component management, and file operations. Use them in the correct context with proper permissions.

Vega CLI

Use the Vega command line interface (CLI) commands to install, uninstall, and manage packages on your device. The following package operations are available:

# Installation (takes the package file path)
vega device install-app --packagePath my-package.vpkg

# List packages
vega device installed-packages

# Package info
vega device run-cmd --command 'vpm info <package-id>'

# Uninstall (takes the component ID, not the package file)
vega device uninstall-app --appName <component-id>

You can only sideload non-Amazon packages (packages without the com.amazon prefix).

Component management

Use the component management commands through the vega device to launch, list, and terminate your app components. The key commands are:

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

# List components
vega device running-apps

# Terminate
vega device terminate-app --appName <component-id>

File operations

Use file operations to transfer files between your development machine and device. The default shell only allows access to the /tmp directory, while component shells can access their specific directories. Always verify your file permissions after transfer, and remove temporary files when they’re no longer needed to maintain device storage. Remember that file paths are case-sensitive. When deleting files, remember to:

Only delete files that were pushed to /tmp from the default development shell.

Delete the files in within the specific component shell by:

Entering the component shell using: vega exec vda shell -t component-id com.myorg.myapp.main
Navigating to the /scratch directory, which is a bind mount of inside the component shell:

sh(com.myorg.myapp.main):/$ cd scratch
sh(com.myorg.myapp.main):/scratch$ rm -rf <filename>

Default shell push

# Push to default shell
vega device copy-to --source <src> --destination /tmp/

# To view the file
vega device shell
sh(com.amazon.dev.shell):/$ ls -al /tmp

Component shell push

vega device copy-to --source <src> --destination /tmp/scratch/<package-id>/

Example:
(hostmachine)% vega device copy-to --source myfile_cloud.sh --destination /tmp/scratch/com.myorg.myapp

# Find the list of components
vega device installed-apps

Example output:
com.myorg.myapp.main
com.myorg.otad.main
com.myorg.dev.shell.service

# Find the list of packages installed on device
vega device installed-packages

Example output:
com.myorg.myapp
com.myorg.test.lifecycleobserver
com.myorg.TESSERACT.TEST
com.myorg.sm-sample.client
com.myorg.samplepkg
com.myorg.security.manager.unprivileged-test
com.myorg.nmunprivileged.task
com.myorg.messaging.mr33.okidl.ac

# Launch Component shell
(hostmachine)% vega exec vda shell -t component-id com.myorg.myapp.main

# View the pushed file
sh(com.myorg.myapp):/$ ls -al scratch/

Example output:
total 4
drwxr-xr-x  2 app_user app_user  60 2024-07-16 03:03 .
drwxr-xr-x 19 app_user app_user 400 2024-07-16 03:03 ..
-rwxrwxrwx  1 app_user 30086    650 2024-07-16 03:03 myfile_cloud.sh

Pull from device

# Pull from device
vega device copy-from --source <device-path> --destination <local-path>

Best practices

When using Developer Mode, make the following practices part of your regular development workflow to prevent unintended system modification:

Sideload only apps with non-Amazon package IDs (verify your package ID doesn’t begin with com.amazon).
Use the minimum access level needed for your task.
Follow the principle of least privilege.
Be mindful that your actions can affect device stability and security.

Troubleshooting and support

When issues arise during development, start by identifying which area is affected (authentication, shell access, package management, component launch, or file operations). Causes of common issues include incorrect permissions or device state restrictions. If the solutions described in the following sections don’t resolve your issue, collect relevant logs using loggingctl log before seeking support.

Authentication issues

Issue	Resolution
Authentication fails	Verify your device and computer are on the same network. Confirm you have a valid Amazon Developer Account. Check that you entered the authentication code exactly as displayed.
Code expires	If the 5-minute timeout expires, select Request a New Code on the same screen, or return to Developer Options and restart the process.
CLI not responding	Make sure you have the latest version of the CLI. Verify Vega CLI is properly installed: `vega --version`. Check your device IP address is correct. Ensure no firewall is blocking the connection.
Validation timeout	If you see “Validation check timed out” messages, the system automatically retries. Wait for the retry attempts to complete. If repeated failures occur, restart from Developer Options.
Device doesn’t reboot	If you selected Cancel on the confirmation dialog, the process was aborted. Restart from Developer Options to try again.
Browser doesn’t open automatically	Manually navigate to the URL shown in your terminal. Copy and paste the URL into your browser and enter the authentication code when prompted.

Common development issues

Issue	Possible causes	Resolution	Prevention
Package installation fails	Wrong directory or format issues.	Check `/tmp` location or verify package format.	Follow package guidelines.
Component launch issues	Missing manifest entry.	Verify manifest configuration or check component ID.	Include proper manifest entries.

Debugging tools

Use loggingctl log to collect system logs and monitor component status. Each debugging tool has specific access levels based on your device state.

Tool	Purpose	Required access level	Common use cases
`loggingctl`	System and component logs	Varies by shell type	Debug crashes or verify behavior.
`vlcm list`	Component monitoring	Default shell	Track running components or verify states.
`ps -efZ`	Process and security context	Component shell	Verify permissions or check process state.

​Prerequisites

​Authenticate Developer Mode on Fire TV

​Developer Mode states

​Development tools

​Vega CLI

​Component management

​File operations

​Best practices

​Troubleshooting and support

​Authentication issues

​Common development issues

​Debugging tools

​Related topics