Overview

Date: 2026-05-11

Time: 15:20

Overview

This page documents how to build applications on top of FTL2's gate event protocol, using the ftl2-htop monitoring TUI as a reference implementation. It covers the full lifecycle: initializing the gate subsystem over SSH, sending commands, registering event handlers, and running concurrent application logic alongside FTL2's event dispatch loop. The key insight is that FTL2 can be used as a library for building real-time distributed applications, not just as a configuration management tool.

Key Concepts

• Gate event protocol — a bidirectional JSON message protocol over SSH channels, supporting both request/response commands and unsolicited events
• Gate subsystem — persistent processes on remote hosts started via gate_subsystem=True, lasting for the lifetime of the async with automation() block
• HostScopedProxy — object returned by getattr(ftl, group) that targets all hosts in a group; also works for individual hosts (e.g., ftl.webserver)
• Event handlers — registered via proxy.on(event_type, handler), can be sync or async, multiple handlers per event type allowed
• PEP 723 inline script metadata — FTL2 apps can be single-file scripts with inline dependency declarations, runnable via uv run with no virtualenv setup
• Pure-Python vs compiled dependency rule — pure-Python deps go in the gate .pyz bundle; compiled deps (like psutil with C extensions) must be installed on the host via dnf/apt
• Message format — JSON tuples over length-prefixed messages: ["CommandName", {params}]

Commands and Syntax

Gate subsystem initialization:

async with automation(inventory=args.inventory, gate_subsystem=True) as ftl:

Host group iteration:

groups = list(ftl.hosts.groups)
proxy = getattr(ftl, group)  # HostScopedProxy for all hosts in group

Sending a gate command (request/response):

await proxy.monitor(interval=2.0, include_processes=True)

Registering an event handler:

proxy.on("SystemMetrics", lambda m: metrics_store.update({m.get("hostname"): m}))

Blocking event dispatch:

await ftl.listen()

Concurrent listen + app logic:

await asyncio.gather(ftl.listen(), update_display())

Installing compiled host dependencies before gate use:

await ftl.webservers.dnf(name="python3-psutil", state="present")

Running the app:

uvx --from "git+https://github.com/benthomasson/ftl2-htop" ftl2-htop -i inventory.yml
uv run ftl2_htop.py -i inventory.yml
ftl2-htop -i inventory.yml --debug   # raw events, no TUI

Relationships

• Inventory — gate apps consume the same YAML inventory as standard FTL2 automation; host groups drive proxy targeting
• Module system — standard FTL2 modules (dnf, apt) are used to prepare hosts before gate features are invoked
• automation() context manager — the same entry point used for scripting; gate_subsystem=True extends it for persistent bidirectional communication
• SSH subsystem — gate processes run over SSH, inheriting FTL2's connection and privilege escalation model
• asyncio — the entire gate protocol is async-native; ftl.listen() and application coroutines run via asyncio.gather

Exam-Relevant Points

• gatesubsystem=True is the flag that enables persistent gate processes (not gate=True or enablegate)
• ftl.listen() blocks and dispatches events — it must run concurrently with application logic via asyncio.gather
• proxy.on() registers handlers; handlers receive the event data as a dict; both sync and async handlers are supported
• The gate message format is JSON tuples (e.g., ["StartMonitor", {interval: 2}]), not dicts or protobuf
• Compiled dependencies (C extensions) cannot be bundled in the gate .pyz — they must be pre-installed on the host
• getattr(ftl, group_name) returns a HostScopedProxy, not a list of hosts
• Single-file FTL2 apps use PEP 723 inline metadata and run with uv run — no virtualenv required
• Events can arrive interleaved with command responses; the protocol handles demultiplexing transparently