> ## Documentation Index
> Fetch the complete documentation index at: https://vvennela-ftl-18-95.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Detailed installation and configuration for FTL

## System requirements

> [card] Python
>
> **Python 3.11 or higher** is required. Check your version:
>
> ```bash theme={null}
> python --version
> ```

> [card] Docker
>
> **Docker Desktop** (macOS/Windows) or **Docker Engine** (Linux) must be installed and running.
>
> Verify:
>
> ```bash theme={null}
> docker info
> ```

> [card] rsync (Linux only)
>
> On Linux, rsync is used for snapshots:
>
> ```bash theme={null}
> apt install rsync  # Ubuntu/Debian
> yum install rsync  # RHEL/CentOS
> ```

> [card] API keys
>
> At minimum, you need an **Anthropic API key** from [console.anthropic.com](https://console.anthropic.com).
>
> Additional keys depend on your agent choice.

## Installation methods

> [tab] From GitHub (recommended)
>
> Clone the repository and install in editable mode:
>
> ```bash theme={null}
> git clone https://github.com/vvennela/ftl
> cd ftl
> pip install -e .
> ```
>
> > [!NOTE]
> >
> > Editable mode (`-e`) allows you to pull updates with `git pull` without reinstalling.

> [tab] With optional extras
>
> FTL supports optional features via pip extras:
>
> ```bash AWS integration theme={null}
> pip install -e ".[aws]"
> ```
>
> ```bash Credential proxy theme={null}
> pip install -e ".[proxy]"
> ```
>
> ```bash Langfuse tracing theme={null}
> pip install -e ".[tracing]"
> ```
>
> ```bash All extras theme={null}
> pip install -e ".[aws,proxy,tracing]"
> ```
>
> See [Optional features](#optional-features) for details on each extra.

> [tab] Virtual environment
>
> Best practice for Python projects:
>
> ```bash theme={null}
> python -m venv venv
> source venv/bin/activate  # Windows: venv\Scripts\activate
>
> git clone https://github.com/vvennela/ftl
> cd ftl
> pip install -e .
> ```
>
> > [!TIP]
> >
> > 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:

```bash theme={null}
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]:
```

> [tab] 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

> [tab] 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

> [tab] 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

> [tab] 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
>
> > [!WARNING]
> >
> > After your first `ftl code` run, authenticate Kiro:
> >
> > ```bash theme={null}
> > 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]:
```

> [tab] 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

> [tab] AWS Bedrock
>
> Uses `bedrock/us.anthropic.claude-sonnet-4-6` via AWS.
>
> * **Requires:** AWS credentials configured
> * **Best for:** AWS-centric setups with Bedrock access

> [tab] 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

> [!NOTE]
>
> Any [LiteLLM-supported model](https://docs.litellm.ai/docs/providers) works. Edit `.ftlconfig` to use custom models:
>
> ```json theme={null}
> {
>   "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`:

```bash OpenAI theme={null}
ftl auth OPENAI_API_KEY sk-proj-...
```

```bash AWS credentials theme={null}
ftl auth AWS_ACCESS_KEY_ID AKIA...
ftl auth AWS_SECRET_ACCESS_KEY ...
ftl auth AWS_DEFAULT_REGION us-east-1
```

```bash Other services theme={null}
ftl auth STRIPE_SECRET_KEY sk_live_...
ftl auth SENDGRID_API_KEY SG...
```

All credentials are stored in `~/.ftl/credentials` and available to FTL (not directly to the agent — see [Shadow credentials](https://vvennela-ftl-18-95.mintlify.site/concepts/shadow-credentials.md)).

## Docker image verification

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

```bash theme={null}
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
```

> [accordion] 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:**
>
> ```bash theme={null}
> cd ftl  # Your cloned repository
> docker build -t ftl-sandbox .
> ```

## Optional features

### AWS integration

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

```bash theme={null}
pip install -e ".[aws]"
```

After installation, configure AWS resources:

```bash theme={null}
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](https://vvennela-ftl-18-95.mintlify.site/guides/aws-setup.md) for details.

### Credential-swap proxy

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

```bash theme={null}
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

```python Agent code (uses shadow value) theme={null}
import stripe
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")  # ftl_shadow_stripe_secret_key_7f8a2b3c
stripe.Customer.create(email="test@example.com")
```

```http Outbound request (proxy intercepts) theme={null}
POST https://api.stripe.com/v1/customers
Authorization: Bearer ftl_shadow_stripe_secret_key_7f8a2b3c
```

```http Rewritten by proxy theme={null}
POST https://api.stripe.com/v1/customers
Authorization: Bearer sk_live_abc123
```

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

### Langfuse tracing

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

```bash theme={null}
pip install -e ".[tracing]"
```

Configure credentials:

```bash theme={null}
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:

```bash theme={null}
cd your-project
ftl init
```

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

```json .ftlconfig theme={null}
{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001"
}
```

Edit `.ftlconfig` to override settings per-project. See [Configuration reference](https://vvennela-ftl-18-95.mintlify.site/configuration/ftlconfig.md) for all available fields.

## Verify installation

**1. Check FTL version**

```bash theme={null}
ftl --version
```

**2. Verify Docker access**

```bash theme={null}
docker ps
```

**3. Check global config**

```bash theme={null}
cat ~/.ftl/config.json
```

Should show:

```json theme={null}
{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001"
}
```

**4. Run a test task**

```bash theme={null}
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:

```bash theme={null}
cd ftl  # Your cloned repository
git pull
```

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

> [!TIP]
>
> To update the Docker image:
>
> ```bash theme={null}
> docker pull vvenne/ftl:latest
> docker tag vvenne/ftl:latest ftl-sandbox
> ```

## Troubleshooting

> [accordion] pip install fails with Python version error
>
> FTL requires Python 3.11 or higher. Check your version:
>
> ```bash theme={null}
> python --version
> ```
>
> If you have multiple Python versions installed, use:
>
> ```bash theme={null}
> python3.11 -m venv venv
> source venv/bin/activate
> pip install -e .
> ```

> [accordion] Docker build fails on M1/M2 Mac
>
> Apple Silicon Macs may need platform specification:
>
> ```bash theme={null}
> docker build --platform linux/amd64 -t ftl-sandbox .
> ```
>
> Or use Rosetta 2 mode in Docker Desktop settings.

> [accordion] ftl command not found after install
>
> Ensure the pip install directory is in your PATH:
>
> ```bash theme={null}
> echo $PATH
> which ftl
> ```
>
> If missing, add to `~/.bashrc` or `~/.zshrc`:
>
> ```bash theme={null}
> export PATH="$HOME/.local/bin:$PATH"
> ```

> [accordion] rsync not found (Linux)
>
> Install rsync for your distribution:
>
> ```bash theme={null}
> # Ubuntu/Debian
> sudo apt update && sudo apt install rsync
>
> # RHEL/CentOS
> sudo yum install rsync
>
> # Arch
> sudo pacman -S rsync
> ```

> [accordion] Proxy install fails (cryptography build error)
>
> The `cryptography` package requires system dependencies:
>
> ```bash theme={null}
> # 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

> [card] [Run your first task](https://vvennela-ftl-18-95.mintlify.site/quickstart.md)
>
> Follow the 5-minute quickstart guide

> [card] [CLI reference](https://vvennela-ftl-18-95.mintlify.site/cli/setup.md)
>
> Complete command-line documentation

> [card] [Configuration](https://vvennela-ftl-18-95.mintlify.site/configuration/ftlconfig.md)
>
> All `.ftlconfig` fields and options

> [card] [AWS setup](https://vvennela-ftl-18-95.mintlify.site/guides/aws-setup.md)
>
> Configure production AWS integration


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.