FTL2

AI-first Python automation using the Ansible module ecosystem. 3-21x faster than ansible-playbook.

Install

pip install ftl2

Or run directly with uvx:

uvx ftl2 --help

Quick Start

import asyncio
from ftl2 import automation

async def main():
    async with automation(
        inventory="inventory.yml",
        fail_fast=True,
    ) as ftl:
        await ftl.webservers.dnf(name="nginx", state="present")
        await ftl.webservers.service(name="nginx", state="started")
        await ftl.webservers.ansible.posix.firewalld(
            port="80/tcp", state="enabled", permanent=True, immediate=True,
        )

asyncio.run(main())

What It Does

FTL2 runs Ansible modules directly from Python without YAML, Jinja2, or the ansible-playbook runtime. Common modules (file, copy, shell, command, etc.) have native implementations that execute in-process. Ansible collection modules fall back to subprocess execution. For remote hosts, modules are pre-built into a gate package once, then only JSON parameters are sent over SSH on each call — no re-uploading module code per task. Concurrency uses asyncio instead of Ansible's fork-based parallelism.

# Any Ansible module works — same names, same parameters
await ftl.local.community.general.linode_v4(label="web01", type="g6-standard-1", ...)
await ftl.webservers.copy(src="app.conf", dest="/etc/nginx/conf.d/app.conf")
await ftl.db.community.postgresql.postgresql_db(name="myapp", state="present")

Features

• Vault secrets — pull secrets from HashiCorp Vault KV v2 with vault_secrets={"DB_PW": "myapp#db_password"}
• Secret bindings — inject API tokens into modules automatically, never visible in code or logs
• State tracking — .ftl2-state.json for idempotent provisioning with crash recovery
• Policy engine — YAML-based rules to restrict what actions can be taken per module, host, or environment
• Audit recording — JSON trail of every action with timestamps, durations, params
• Audit replay — resume from failure by replaying successful actions from a previous run
• Gate modules — pre-build remote execution gates with all modules baked in
• Event streaming — real-time events from remote hosts (file changes, system metrics)
• Dynamic hosts — add_host() for provisioning workflows where you create and configure in one script
• Check mode — dry-run without executing
• Auto-install deps — missing Python packages installed with uv at runtime

async with automation(
    inventory="inventory.yml",
    secret_bindings={
        "community.general.linode_v4": {"access_token": "LINODE_TOKEN"},
        "uri": {"bearer_token": "API_TOKEN"},
    },
    state_file=".ftl2-state.json",
    vault_secrets={
        "DB_PASSWORD": "myapp#db_password",
    },
    policy="policy.yml",
    environment="prod",
    gate_modules="auto",
    record="audit.json",
    fail_fast=True,
) as ftl:
    ...

Policy Engine

Restrict what actions are permitted based on module, host, environment, and parameters:

# policy.yml
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"

Note: The shell, command, and raw modules are treated as equivalent by the policy engine. A rule denying shell automatically blocks command and raw too, including FQCN variants like ansible.builtin.raw.

async with automation(policy="policy.yml", environment="prod") as ftl:
    await ftl.file(path="/tmp/test", state="absent")
    # Raises PolicyDeniedError: No destructive actions on production hosts

Vault Secrets

Pull secrets from HashiCorp Vault instead of environment variables:

async with automation(
    vault_secrets={
        "DB_PASSWORD": "myapp#db_password",
        "API_KEY": "myapp#api_key",
    },
    secret_bindings={
        "community.general.slack": {"token": "SLACK_TOKEN"},
    },
) as ftl:
    pw = ftl.secrets["DB_PASSWORD"]  # from Vault

Uses standard VAULT_ADDR and VAULT_TOKEN env vars. Install with pip install ftl2[vault].

Dynamic Provisioning

Create cloud servers and configure them in a single script:

async with automation(
    state_file=".ftl2-state.json",
    secret_bindings={
        "community.general.linode_v4": {"access_token": "LINODE_TOKEN", "root_pass": "ROOT_PASS"},
    },
    fail_fast=True,
) as ftl:
    # Provision
    if not ftl.state.has("web01"):
        server = await ftl.local.community.general.linode_v4(
            label="web01", type="g6-standard-1", region="us-east", image="linode/fedora43",
        )
        ftl.add_host("web01", ansible_host=server["instance"]["ipv4"][0], ansible_user="root")
        await ftl.local.wait_for(host=server["instance"]["ipv4"][0], port=22, timeout=300)

    # Configure immediately
    await ftl["web01"].dnf(name="nginx", state="present")
    await ftl["web01"].service(name="nginx", state="started", enabled=True)

AI-First Automation

FTL2 is designed for AI agents as the primary user. Traditional automation tools force AI to generate YAML with fragile indentation, parse unstructured error output, and work around DSL limitations. FTL2 eliminates all of that — AI agents write native Python, get structured errors, and leverage the Ansible module ecosystem they already know from training data.

Why Python over YAML for AI:

Safe AI autonomy: Secret bindings inject credentials at runtime — AI-generated code never sees actual values, preventing accidental leakage into logs or context windows. Policy engines restrict what modules AI can call. Check mode lets AI dry-run before committing.

# AI agent generates this — secrets stay in the tool layer
async with automation(
    secret_bindings={
        "amazon.aws.*": {"aws_access_key_id": "AWS_KEY"},
        "community.general.slack": {"token": "SLACK_TOKEN"},
    },
    policy="policy.yml",
) as ftl:
    await ftl.webservers.dnf(name="nginx", state="present")
    # Credentials injected automatically, never visible in generated code

AI reconciliation loop: FTL2 supports observe-decide-act-verify loops where AI replaces hardcoded controller logic. The AI observes current state through modules, reasons about the gap to desired state, emits FTL2 calls to close the gap, then verifies convergence. As recurring problems get solved, AI writes deterministic rules — cost converges toward zero over time.

Zero onboarding: AI already knows Ansible module names and parameters from training data. No need for thousands of tool definitions or MCP servers. A minimal CLAUDE.md is enough for an AI agent to start provisioning infrastructure:

# CLAUDE.md — Automation

Use ftl2 for all infrastructure automation. Write Python scripts, not YAML.

## Pattern
\```python
from ftl2 import automation
async with automation(
    secret_bindings={"community.general.linode_v4": {"access_token": "LINODE_TOKEN"}},
    state_file=".ftl2-state.json",
    fail_fast=True,
) as ftl:
    await ftl.webservers.dnf(name="nginx", state="present")
\```

## Rules
- Use short names for builtins: `file`, `copy`, `shell`, `service`, `dnf`, `user`
- Use FQCN for collections: `community.general.linode_v4`, `ansible.posix.firewalld`
- Secrets go in `secret_bindings`, never in code
- Use `ftl.local` for API/cloud modules, `ftl.groupname` for remote hosts
- `pip install ftl2` to install

Performance

Local benchmarks

Benchmarked with ftl2-performance (single host, localhost):

Scale tests

Benchmarked with ftl2-scale-tests against real Linode VMs (Fedora 42, us-east). FTL2 uses gate protocol multiplexing and native modules; Ansible uses --forks N.

SSH workloads (file operations, package install, service setup across remote hosts):

API workloads (20 HTTP requests per host, connection: local):

API calls show the architecture difference most clearly. FTL2 fires all requests concurrently with async httpx. Ansible forks a subprocess per uri task, serializing within each host. At 25 hosts (500 total requests), FTL2 finishes in 0.7s vs Ansible's 14.7s.

Ansible also drops hosts as "unreachable" at 25+ hosts even after preflight verification. FTL2's persistent gate connections handle the same hosts without issues.

Development

git clone git@github.com:benthomasson/ftl2.git
cd ftl2
uv pip install -e ".[dev]"
pytest

License

Apache-2.0