Enable Developer Mode

Developer Mode enables app development capabilities on devices. You can test apps, access secure shells, manage packages, debug components, and access the file system. You can use it for app development, package deployment, performance monitoring, app debugging, and component management.

For instructions on how to configure developer mode on Fire TV Stick, see Configure Developer Mode.

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. These tools are critical for the development workflow and must be used in the correct context with proper permissions. Understanding these tools and their appropriate usage helps ensure efficient development and prevent common issues. Some tools might have different capabilities depending on your shell type and device configuration.

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
kepler device install-app --packagePath my-package.vpkg

# List packages
kepler device installed-packages

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

# Uninstall
kepler 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 kepler device to launch, list, and terminate your app components. The key commands are:

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

# List components
kepler device running-apps

# Terminate
kepler 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 /tmp/scratch/<package-id> 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:

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

2. Delete the files in /tmp/scratch/<package-id> within the specific component shell by:

   • Entering the component shell using: kepler exec vda shell -t component-id com.myorg.myapp.main
   • Navigating to the /scratch directory, which is a bind mount of /tmp/scratch/<package-id> 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
    kepler device copy-to --source <src> --destination /tmp/
   
    # To view the file
    kepler device shell
    sh(com.amazon.dev.shell):/$ ls -al /tmp
   

   Component shell push

   
    kepler device copy-to --source <src> --destination /tmp/scratch/<package-id>/
   
    Example:
    (hostmachine)% kepler device copy-to --source myfile_cloud.sh --destination /tmp/scratch/com.myorg.myapp   
   
    # Find the list of components
    kepler 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
    kepler 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)% kepler 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
    kepler device copy-from -o <device-path> -s <local-path>
   

Best practices

When using Developer Mode, make the following practices part 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 (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 table don’t resolve your issue, collect relevant logs using loggingctl log before seeking support.

Common issues

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.

Related topics

• Use Loggingctl to Manage System Logs
• Configure Developer Mode on Fire TV Stick

Last updated: Sep 30, 2025