Setting Runtime Modules in Your App Manifest

A runtime module is a critical component in your app's architecture that defines the execution environment for your app's components. It determines how your code is interpreted and executed, affecting performance, memory usage, and functionality.

Runtime modules are essential because they:

• Ensure compatibility between your app's components and the underlying system.
• Optimize resource usage based on the component type (interactive, task, or service).
• Enable proper process management and component isolation.

Guidelines for defining runtime modules

When defining runtime modules in your app manifest, follow these guidelines.

Interactive components

For interactive components, use one of the following runtime modules:

• /com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0
• /com.amazon.kepler.runtime.keplerscript_2@IKeplerScript (new convention, may cause validator warnings)

Example manifest entry

[components]
[[components.interactive]]
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"

Task or service components

For task or service components, you can use the same runtime modules as interactive components if the task or service shares the same process with the interactive component.

Example manifest entry

[[components.interactive]]
id = "<your-app-package-name>.main"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0" 
launch-type = "singleton"

[[components.service]]
id = "<your-app-package-name>.service"
runtime-module = "/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"

If your task or service components don't share the same process with an interactive component, use one of the headless runtimes. These have a smaller memory footprint.

/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0

Example manifest entry

[[components.service]]
id = "<your-app-package-name>.service"
runtime-module = "/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0"
launch-type = "singleton"

Process group consistency

Components in the same process group must use the same runtime-module.

Version consistency

Always use the same KeplerScript version (indicated by the number after the @ symbol) for all runtime modules in your manifest. For example, you can't mix version 2 and version 1 runtime modules in the same manifest.

Validation warnings and errors

If you don't follow the guidelines listed above, you will receive warning or error messages when you validate your app manifest with VPT.

The messages below show examples of warnings and errors you may receive from VPT.

Example 1: Inconsistent runtime modules in process group

Copy code Copied to clipboard.

manifest.toml:32:5 error: [processes.group] Inconsistent runtime modules in process group. Found multiple runtime modules: '/com.amazon.kepler.keplerscript.runtime.loader_2@IKeplerScript_2_0' (com.amazon.samplepkg.component.a), '/com.amazon.kepler.headless.runtime.loader_2@IKeplerScript_2_0' (com.amazon.samplepkg.component.b, com.amazon.samplepkg.component.c)
  help: All components in a process group must have the same runtime module if declared

Example 2: Inconsistent runtime module versions

Copy code Copied to clipboard.

manifest.toml:10:6 error: [components.runtime-module] Inconsistent runtime module versions found: 'IKeplerScript_1_0' (com.amazon.samplepkg.component.main), 'IKeplerScript_2_0' (com.amazon.samplepkg.component.main2, com.amazon.samplepkg.component.main3)
  help: All runtime modules declared must use the same version

Last updated: Sep 30, 2025