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: "nmake build"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        },
        {
            script: "make build"
            runtimes: [{name: "container", image: "golang:1.26"}]
            platforms: [{name: "linux"}]
        },
        {
            script: "make build"
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
        },
    ]
}]

Runtime Comparison

Aspect	Native	Virtual	Container
Speed	Fastest	Fast	Slower (overhead)
Isolation	None	None (not a sandbox)	Full
Portability	Platform-dependent	High	Highest
Shell features	Full host shell	POSIX subset	Full (in container)
Dependencies	Host shell	None	Docker/Podman
Best for	Simple scripts	Cross-platform	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 Runtime

The virtual runtime is always available because it's embedded in the Invowk binary.

Container Runtime

Container Provisioning Details

When the container runtime is selected, Invowk creates an ephemeral image layer:

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 commands	virtual	Works everywhere
CI/CD pipelines	container	Reproducible
Commands needing specific tools	container	Isolated dependencies
Interactive TUI	native or virtual	Better terminal support

Related Diagrams

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