Installation

Detailed installation and configuration for FTL

System requirements

Python

Python 3.11 or higher is required. Check your version:

python --version

Docker

Docker Desktop (macOS/Windows) or Docker Engine (Linux) must be installed and running.

Verify:

docker info

rsync (Linux only)

On Linux, rsync is used for snapshots:

apt install rsync  # Ubuntu/Debian
yum install rsync  # RHEL/CentOS

API keys

At minimum, you need an Anthropic API key from console.anthropic.com.

Additional keys depend on your agent choice.

Installation methods

From GitHub (recommended)

Clone the repository and install in editable mode:

git clone https://github.com/vvennela/ftl
cd ftl
pip install -e .

Editable mode (-e) allows you to pull updates with git pull without reinstalling.

With optional extras

FTL supports optional features via pip extras:

AWS integration

pip install -e ".[aws]"

See Optional features for details on each extra.

Virtual environment

Best practice for Python projects:

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

git clone https://github.com/vvennela/ftl
cd ftl
pip install -e .

Activate the virtual environment in every new shell session before using ftl commands.

One-time setup

After installation, run the setup wizard to configure your agent, tester model, and credentials:

ftl setup

Agent selection

The wizard prompts you to choose an AI coding agent:

Which agent do you want to use?
  1. Claude Code  (Anthropic, recommended)
  2. Codex        (OpenAI)
  3. Aider        (open-source)
  4. Kiro         (AWS)
  Choice [1]:

Claude Code

Recommended. Uses Anthropic’s Claude models with a Code-optimized interface.

• Requires: ANTHROPIC_API_KEY
• Docker image: vvenne/ftl:latest
• Best for: Most users — high-quality code generation with streaming output

Codex

OpenAI’s Codex model (now deprecated by OpenAI but still supported in FTL).

• Requires: OPENAI_API_KEY
• Docker image: vvenne/ftl:codex
• Best for: Legacy projects or OpenAI preference

Aider

Open-source coding agent with support for multiple LLM providers.

• Requires: OPENAI_API_KEY or ANTHROPIC_API_KEY
• Docker image: vvenne/ftl:aider
• Best for: Model flexibility and community-driven development

Kiro

AWS-native coding agent (requires AWS SSO browser login).

• Requires: AWS credentials + browser login after first run
• Docker image: vvenne/ftl:kiro
• Best for: AWS-centric workflows

After your first ftl code run, authenticate Kiro:

docker exec -it $(docker ps -qf ancestor=vvenne/ftl:kiro) kiro-cli login

Credentials persist in the container until it is removed.

Your choice is saved to ~/.ftl/config.json and used as the default for all new projects.

Tester model selection

FTL generates adversarial tests in parallel while the agent codes. Choose your test generation model:

Which model for test generation?
  1. Anthropic API — claude-haiku  (uses ANTHROPIC_API_KEY)
  2. AWS Bedrock   — claude-sonnet (uses AWS credentials)
  3. Skip test generation
  Choice [1]:

Anthropic API (default)

Uses claude-haiku-4-5-20251001 via Anthropic’s API.

• Requires: ANTHROPIC_API_KEY
• Latency: ~1-3 seconds per test generation
• Cost: Lowest-cost Anthropic model

AWS Bedrock

Uses bedrock/us.anthropic.claude-sonnet-4-6 via AWS.

• Requires: AWS credentials configured
• Best for: AWS-centric setups with Bedrock access

Skip test generation

Disables parallel test generation.

• Best for: Quick iterations or budget-conscious development
• Tests can be re-run manually later with ftl interactive mode

Any LiteLLM-supported model works. Edit .ftlconfig to use custom models:

{
  "tester": "openai/gpt-4o-mini",
  "tester": "bedrock/us.anthropic.claude-sonnet-4-6",
  "tester": "claude-haiku-4-5-20251001"
}

API key configuration

The wizard prompts for your Anthropic API key if not already set:

Anthropic API key
  Get one at https://console.anthropic.com
  ANTHROPIC_API_KEY: sk-ant-...

Your key is saved to ~/.ftl/credentials (file mode 600) and loaded automatically on every FTL invocation.

Adding more credentials

For agents requiring additional keys, use ftl auth:

OpenAI

ftl auth OPENAI_API_KEY sk-proj-...

All credentials are stored in ~/.ftl/credentials and available to FTL (not directly to the agent — see Shadow credentials).

Docker image verification

After ftl setup, verify the image was pulled or built:

docker images | grep ftl

You should see:

ftl-sandbox              latest    abc123def456   2 days ago   1.2GB
vvenne/ftl               latest    abc123def456   2 days ago   1.2GB

If image pull fails

FTL automatically falls back to building the image locally from your cloned Dockerfile.

Requirements for local build:

1. You must have cloned the full FTL repository (not just pip installed)
2. Docker BuildKit must be available

To manually rebuild:

cd ftl  # Your cloned repository
docker build -t ftl-sandbox .

Optional features

AWS integration

Enables S3 snapshots, CloudWatch tracing, Secrets Manager, and Bedrock Guardrails:

pip install -e ".[aws]"

After installation, configure AWS resources:

cd your-project
ftl init
ftl config --aws

This provisions:

• S3 bucket ftl-<account>-<region>
• CloudWatch log group /ftl/<project-name>
• Bedrock Guardrail ftl-<project-name>
• Optional Secrets Manager prefix

See AWS setup guide for details.

Credential-swap proxy

Enables live API calls with real credentials while the agent only sees shadow values:

pip install -e ".[proxy]"

How it works:

1. FTL starts an HTTP/HTTPS intercepting proxy on the host
2. Container routes all outbound traffic through the proxy
3. Proxy replaces shadow values with real credentials before upstream requests
4. HTTPS traffic handled via MITM with ephemeral CA

Agent code (uses shadow value)

import stripe
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")  # ftl_shadow_stripe_secret_key_7f8a2b3c
stripe.Customer.create(email="[e-mail]")

The agent never learns your real key, but API calls succeed.

Langfuse tracing

Enables LLM observability for all tester and diff-review LLM calls:

pip install -e ".[tracing]"

Configure credentials:

ftl auth LANGFUSE_PUBLIC_KEY pk-lf-...
ftl auth LANGFUSE_SECRET_KEY sk-lf-...
ftl auth LANGFUSE_HOST https://cloud.langfuse.com  # Optional

Every litellm.completion() call is traced automatically via LiteLLM’s Langfuse integration.

Project initialization

After one-time machine setup, initialize FTL in each project:

cd your-project
ftl init

This creates .ftlconfig with defaults from ~/.ftl/config.json:

.ftlconfig

{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001"
}

Edit .ftlconfig to override settings per-project. See Configuration reference for all available fields.

Verify installation

1. Check FTL version

   ftl --version
   
2. Verify Docker access

   docker ps
   
3. Check global config

   cat ~/.ftl/config.json
   

   Should show:

   {
     "agent": "claude-code",
     "tester": "claude-haiku-4-5-20251001"
   }
   
4. Run a test task

   cd /tmp
   mkdir ftl-test && cd ftl-test
   ftl init
   echo 'print("hello")' > test.py
   ftl code 'add a docstring to test.py'
   

If the test task completes and shows you a diff, your installation is working correctly.

Upgrading FTL

If you installed with pip install -e ., pull the latest code:

cd ftl  # Your cloned repository
git pull

No reinstallation needed — editable mode automatically uses the updated code.

To update the Docker image:

docker pull vvenne/ftl:latest
docker tag vvenne/ftl:latest ftl-sandbox

Troubleshooting

pip install fails with Python version error

FTL requires Python 3.11 or higher. Check your version:

python --version

If you have multiple Python versions installed, use:

python3.11 -m venv venv
source venv/bin/activate
pip install -e .

Docker build fails on M1/M2 Mac

Apple Silicon Macs may need platform specification:

docker build --platform linux/amd64 -t ftl-sandbox .

Or use Rosetta 2 mode in Docker Desktop settings.

ftl command not found after install

Ensure the pip install directory is in your PATH:

echo $PATH
which ftl

If missing, add to ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

rsync not found (Linux)

Install rsync for your distribution:

# Ubuntu/Debian
sudo apt update && sudo apt install rsync

# RHEL/CentOS
sudo yum install rsync

# Arch
sudo pacman -S rsync

Proxy install fails (cryptography build error)

The cryptography package requires system dependencies:

# Ubuntu/Debian
sudo apt install build-essential libssl-dev libffi-dev python3-dev

# macOS
brew install openssl
export LDFLAGS="-L$(brew --prefix openssl)/lib"
export CPPFLAGS="-I$(brew --prefix openssl)/include"

pip install -e ".[proxy]"

Next steps

Run your first task

Follow the 5-minute quickstart guide

CLI reference

Complete command-line documentation

Configuration

All .ftlconfig fields and options

AWS setup

Configure production AWS integration