# Understanding the Preflight Protocol in OpenMontage: Capability Verification Explained

> Discover OpenMontage's Preflight Protocol: a crucial validation phase before tool execution that verifies runtime capabilities, providers, and credentials for seamless operation.

- Repository: [Calesthio/OpenMontage](https://github.com/calesthio/OpenMontage)
- Tags: deep-dive
- Published: 2026-08-30

---

**The Preflight Protocol in OpenMontage is a mandatory, side-effect-free validation phase that executes before any tool or workflow to discover and verify runtime capabilities, required providers, and available credentials.**

OpenMontage uses this protocol to prevent costly execution failures by validating the entire execution environment upfront. Before any video processing begins, the system performs a comprehensive audit of what resources are actually available versus what the workflow requires. Understanding how the Preflight Protocol verifies capabilities allows developers to build more resilient tools and autonomous agents that fail fast with clear diagnostics.

## What Is the Preflight Protocol in OpenMontage?

The Preflight Protocol serves as a mandatory gate that every tool must pass through before entering the execution phase. According to the source code in [`tools/base_tool.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/base_tool.py), this protocol is explicitly designed as a "Preflight check without side effects" that returns a description of what the tool would accomplish without performing any real work.

This validation system addresses three critical questions before resource-intensive media generation starts:

- **Which runtimes are available?** (HyperFrames, Remotion, FFmpeg)
- **Which external providers are accessible?** (ElevenLabs, HeyGen, local voice generators)
- **Are the necessary credentials present?** (API keys, authentication tokens)

By answering these questions upfront, the **Preflight Protocol in OpenMontage** ensures that missing capabilities surface as user-friendly warnings rather than runtime exceptions during video rendering.

## How the Preflight Protocol Verifies Capabilities

The verification process follows a strict five-stage pipeline implemented across the core tooling infrastructure.

### Tool-Level Preflight Checks

Every tool in the system inherits from `BaseTool`, which defines the abstract `preflight()` method at line 400 of [`tools/base_tool.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/base_tool.py). Concrete tool implementations override this method to declare their specific requirements and expected outputs. When invoked, `preflight()` returns a dictionary describing the intended action—for example, `{'action': 'stitch', 'clips': 5, 'output': 'stitched.mp4'}`—without modifying any state or consuming API quotas.

### Runtime Availability Discovery

The `ToolRegistry` queries the environment to report which media processing engines are actually installed and functional. As documented in [`skills/core/hyperframes.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/core/hyperframes.md) at line 193, the protocol specifically checks for runtimes like HyperFrames, Remotion, and FFmpeg. This step prevents scenarios where a tool attempts to invoke `ffmpeg` commands that would fail due to missing binaries.

### Provider Menu Validation

The system constructs a mandatory **Provider Menu** that catalogs all external services required for the workflow. According to the comment at line 321 of [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py), this menu is "Mandatory at Preflight" and cross-referenced against the requirements defined in [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) (line 263). If a workflow requires ElevenLabs for voice generation but the provider is not configured, the preflight flags this dependency gap immediately.

### Credential Discovery and Authentication

The protocol executes authentication status commands—typically `npx hyperframes auth status`—to verify which API keys are present in the environment. The `website-to-video` skill documentation at line 39 demonstrates this pattern, showing how the system checks sign-in status before proceeding. If credentials are missing, the preflight aborts and prompts the user to authenticate or switch to offline engines.

### Generating the Capability Summary

After completing all checks, the system invokes `registry.provider_menu_summary()` to produce a human-readable report. The animation pipeline's proposal director, documented at line 135 of [`skills/pipelines/animation/proposal-director.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/pipelines/animation/proposal-director.md), demonstrates this final step. This summary displays exactly what will happen and what is missing, allowing users to make informed decisions before committing compute resources.

## Implementing Preflight Checks in Python

Developers can programmatically invoke the **Preflight Protocol in OpenMontage** to validate capabilities before executing custom workflows. The following example demonstrates how to inherit from `BaseTool` and leverage the `ToolRegistry` for comprehensive capability verification:

```python
from tools.base_tool import BaseTool
from tools.tool_registry import ToolRegistry

# Example: a custom video-stitch tool that inherits the base preflight behavior

class VideoStitchTool(BaseTool):
    def run(self, clips):
        # Real implementation goes here …

        pass

# Instantiate the registry (holds information about runtimes & providers)

registry = ToolRegistry()

# 1️⃣ Run the tool’s preflight check

tool = VideoStitchTool()
preflight_report = tool.preflight()          # → dict describing what would happen

# 2️⃣ Ask the registry which runtimes are actually available

runtime_status = registry.runtime_status()   # e.g. {'hyperframes': True, 'ffmpeg': True}

# 3️⃣ Get a provider-menu summary (mandatory at preflight)

provider_summary = registry.provider_menu_summary()  # Human-readable list

print("Preflight report:", preflight_report)
print("Runtimes:", runtime_status)
print("Available providers:", provider_summary)

```

Executing this script produces side-effect-free output similar to:

```

Preflight report: {'action': 'stitch', 'clips': 5, 'output': 'stitched.mp4'}
Runtimes: {'hyperframes': True, 'remotion': False, 'ffmpeg': True}
Available providers: ElevenLabs ✓, image_selector ✓, video_selector ✗ (no API keys)

```

This output confirms exactly which operations can proceed and which dependencies require resolution before the actual video processing begins.

## Summary

- The **Preflight Protocol in OpenMontage** is mandatory and executes before any tool runs to verify capabilities without side effects.
- All tools inherit the `preflight()` method from `BaseTool` at line 400 of [`tools/base_tool.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/base_tool.py) to declare their requirements.
- The `ToolRegistry` validates runtime availability (HyperFrames, FFmpeg) and enforces the mandatory Provider Menu check at line 321 of [`tools/tool_registry.py`](https://github.com/calesthio/OpenMontage/blob/main/tools/tool_registry.py).
- Credential discovery uses authentication status commands to verify API keys before costly remote API calls occur.
- The protocol generates a human-readable summary via `provider_menu_summary()` so users can see exactly what is available and what is missing before execution.

## Frequently Asked Questions

### What happens if the Preflight Protocol detects missing credentials?

If the protocol discovers missing API keys or expired authentication tokens—typically via commands like `npx hyperframes auth status`—it aborts the preflight step and surfaces a clear error message. As shown in the `website-to-video` skill documentation, the system prompts the user to sign in or explicitly continue with offline-only engines that do not require remote credentials.

### Is the Preflight Protocol optional for custom tools?

No, the Preflight Protocol is mandatory for all tools in the OpenMontage ecosystem. The [`AGENT_GUIDE.md`](https://github.com/calesthio/OpenMontage/blob/main/AGENT_GUIDE.md) at line 263 explicitly requires the Provider Menu validation at preflight time, and the `ToolRegistry` enforces these checks regardless of whether the tool uses local or remote resources. Custom tools must inherit from `BaseTool` and implement the `preflight()` method to participate in this validation.

### How does preflight verification differ from actual tool execution?

The `preflight()` method is strictly side-effect-free—it describes what *would* happen without performing any real work, consuming API quotas, or writing files. The actual `run()` method performs the resource-intensive operations. This separation allows developers to validate entire workflow chains cheaply before committing to expensive video rendering or external API calls.

### Which specific runtimes does the preflight check verify?

According to [`skills/core/hyperframes.md`](https://github.com/calesthio/OpenMontage/blob/main/skills/core/hyperframes.md) at line 193, the protocol specifically reports on the availability of HyperFrames, Remotion, and FFmpeg runtimes. The `ToolRegistry` checks for installed binaries and executable paths, ensuring that tools do not attempt to invoke commands that would fail due to missing system dependencies.