Runtime Selection Flowchart

This diagram documents the decision tree for selecting which runtime executes a command. Understanding this helps users choose the right runtime for their use case.

Decision Flowchart

Platform Selection Details

Platform Values

Platform Value	Matches On
"linux"	Linux systems
"macos"	macOS systems
"windows"	Windows systems

note

At least one platform must be specified per implementation. There is no "all platforms" shorthand — list each target platform explicitly.

Example Command Definition

cmds: [{
    name: "build"
    implementations: [
        {
            script: {content: "nmake build"}
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        },
        {
            script: {content: "make build"}
            runtimes: [{name: "container", image: "debian:stable-slim"}]
            platforms: [{name: "linux"}]
        },
        {
            script: {content: "make build"}
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
        },
    ]
}]

Runtime Comparison

Aspect	Native	Virtual-Sh	Virtual-Lua	Container
Speed	Fastest	Fast	Fast	Slower (overhead)
Isolation	None	None (not a sandbox)	None (not a sandbox)	Full
Portability	Platform-dependent	High	High	Highest
Language	Host shell	POSIX subset	Lua	Full (in container)
Dependencies	Host shell	Built-ins or allowed binaries	Lua stdlib or allowed helpers	Docker/Podman
Best for	Simple scripts	Cross-platform shell	Cross-platform Lua	Complex environments

Runtime Resolution Precedence

Runtime mode is resolved in this order:

1. --ivk-runtime CLI override — hard fail if incompatible with the selected implementation
2. default_runtime from config — used only when compatible with the implementation
3. Command default runtime — the runtime specified in the selected platform implementation

warning

There is no implicit native → virtual fallback when native is unavailable. If the native runtime is requested but cannot run (e.g., no shell found), the command fails rather than silently switching to virtual.

Runtime Availability Checks

Native Runtime

Virtual-Sh And Virtual-Lua Runtimes

The virtual-sh and virtual-lua runtimes are always available because they are embedded in the Invowk binary.

Container Runtime

Container Provisioning Details

For ephemeral container execution, Invowk prepares an image and creates an ephemeral image layer. Existing persistent container targets can skip image preparation and use Exec directly. Missing persistent targets fail before image preparation unless create_if_missing is enabled, in which case Invowk prepares the image, creates/starts the persistent container, then uses Exec:

Why Ephemeral Layers?

1. No image pollution: Base images stay clean
2. Fast iteration: No full rebuild needed
3. Portable: Commands work with any compatible base image
4. Secure: Invowk binary is injected, not installed in image

SSH Server for Callbacks

When enable_host_ssh: true is set, Invowk starts a temporary SSH server:

Use cases:

• Accessing host secrets
• Running host-only commands
• File synchronization

Decision Guidelines

Use Case	Recommended Runtime	Why
Quick scripts	native	Fastest, no overhead
Cross-platform shell commands	virtual-sh	Works everywhere
Cross-platform Lua commands	virtual-lua	Works everywhere
CI/CD pipelines	container	Reproducible
Commands needing specific tools	container	Isolated dependencies
Interactive TUI	native, virtual-sh, or virtual-lua	PTY-backed interactive support

Related Diagrams

• Command Execution Sequence - Full execution flow
• C4 Container Diagram - Runtime component relationships
• Discovery Precedence Flowchart - How commands are found