Overview

Date: 2026-05-11

Time: 15:22

Overview

FTL2 is an AI-first Python automation framework that runs Ansible modules directly from Python code without YAML, Jinja2, or the ansible-playbook runtime. It achieves 3-21x speedups over Ansible through native in-process module execution, asyncio-based concurrency, and a gate protocol that pre-builds modules for remote execution. FTL2 is designed for both one-off automation scripts and as infrastructure for full applications, with AI agents as the primary intended user.

Key Concepts

• Native Python API — automation is written in Python (async/await), not YAML playbooks. No Jinja2 templating.
• Ansible module compatibility — uses the same module names and parameters as Ansible. Builtins (file, copy, shell, command, service, dnf) have native in-process implementations; collection modules fall back to subprocess execution.
• Short names vs FQCN — builtin modules use short names (file, copy, shell); collection modules use fully qualified names (community.general.linode_v4, ansible.posix.firewalld).
• Host targeting — ftl.groupname targets remote host groups; ftl.local targets localhost (used for API/cloud modules); ftl["hostname"] targets a specific host.
• asyncio concurrency — replaces Ansible's fork-based parallelism. All operations are async/await.
• Gate modules — pre-build a gate package with all needed modules once, then send only JSON parameters over SSH per task. Eliminates per-task module upload overhead.
• fail_fast — stops execution on first failure when set to True.
• State tracking — .ftl2-state.json enables idempotent provisioning with crash recovery. Check with ftl.state.has("name").
• Policy equivalence — shell, command, and raw modules are treated as equivalent by the policy engine. Denying one blocks all three, including FQCN variants.
• AI-first design — structured errors (JSON, tracebacks), secret bindings prevent credential leakage, policy engines restrict AI actions, check mode for dry-runs.

Commands and Syntax

Installation:

pip install ftl2          # standard install
pip install ftl2[vault]   # with Vault support
uvx ftl2 --help           # run directly without install

Core automation pattern:

async with automation(
    inventory="inventory.yml",
    fail_fast=True,
) as ftl:
    await ftl.groupname.module(param=value)

Full configuration options for automation():

| Parameter | Purpose |

|-----------|---------|

| inventory | Path to YAML inventory file |

| fail_fast | Stop on first failure |

| secret_bindings | Dict mapping module globs to env var credentials |

| state_file | Path to state JSON for idempotency/crash recovery |

| vault_secrets | Dict mapping names to Vault KV v2 paths ("app#key" format) |

| policy | Path to policy YAML file |

| environment | Environment name (used by policy rules) |

| gate_modules | Set to "auto" for automatic gate building |

| record | Path to audit JSON file |

Policy YAML syntax:

rules:
  - decision: deny
    match:
      module: "shell"
      environment: "prod"
    reason: "Use proper modules in production"
  - decision: deny
    match:
      module: "*"
      param.state: "absent"
      host: "prod-*"
    reason: "No destructive actions on production hosts"

Dynamic provisioning pattern:

ftl.add_host("hostname", ansible_host="1.2.3.4", ansible_user="root")
await ftl.local.wait_for(host="1.2.3.4", port=22, timeout=300)
await ftl["hostname"].dnf(name="nginx", state="present")

Vault secrets access:

pw = ftl.secrets["DB_PASSWORD"]  # access pulled Vault secret

Requires VAULTADDR and VAULTTOKEN environment variables.

Relationships

• Ansible ecosystem — FTL2 reuses the entire Ansible module ecosystem (same names, same parameters) but replaces the runtime, YAML DSL, and Jinja2 templating.
• HashiCorp Vault — integrates via vault_secrets parameter for KV v2 secret retrieval; optional install with ftl2[vault].
• asyncio — all operations are async; scripts use asyncio.run() as the entry point.
• uv — used for auto-installing missing Python dependencies at runtime and for uvx direct execution.
• Secret bindings — connect to policy engine (restricting AI actions) and audit recording (credentials never appear in logs).
• State file — connects to dynamic provisioning (tracking what's been created) and crash recovery (replaying from failure point).
• AI reconciliation loop — observe-decide-act-verify pattern where AI replaces hardcoded controller logic; deterministic rules written as recurring problems get solved.

Exam-Relevant Points

• FTL2 achieves 3-21x speedup over Ansible; API workloads show the largest gains (up to ~21x at 25 hosts).
• Builtin modules run in-process (native implementations); collection modules run via subprocess.
• shell, command, and raw are policy-equivalent — denying one denies all three.
• Secret bindings ensure credentials are never visible in code or logs — critical for AI agent safety.
• Gate modules are pre-built once and only JSON parameters are sent per task over SSH.
• ftl.local is used for API/cloud modules (connection: local equivalent).
• Vault integration requires pip install ftl2[vault] and VAULTADDR/VAULTTOKEN env vars.
• State file format is .ftl2-state.json; check existence with ftl.state.has("name").
• Policy rules match on: module, environment, host, and param.* fields.
• PolicyDeniedError is raised when a policy rule blocks an action.
• Ansible drops hosts as "unreachable" at 25+ hosts; FTL2's persistent gate connections handle them without issues.
• AI reconciliation loop: observe → decide → act → verify; cost converges toward zero as deterministic rules replace AI reasoning.