> ## 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.

# Configuration

> Configure FTL projects with .ftlconfig and global defaults

FTL uses a layered configuration system: global defaults in `~/.ftl/config.json` set during `ftl setup`, overridden by per-project `.ftlconfig` files.

## Configuration Files

### Global Configuration

`~/.ftl/config.json` stores machine-wide defaults set by `ftl setup`:

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

> [!NOTE]
>
> Global config is used as the template when you run `ftl init` in a new project.

### Project Configuration

`.ftlconfig` in your project root defines per-project settings:

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

## Configuration Precedence

Settings are merged in this order:

```mermaid theme={null}
graph LR
  A[Default Config] --> B[Global Config]
  B --> C[Project .ftlconfig]
  C --> D[Final Config]
```

1. **Default values** - Built-in FTL defaults
2. **Global config** - `~/.ftl/config.json`
3. **Project config** - `.ftlconfig` in project root

## Full Configuration Schema

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

  "shadow_env": ["MY_EXTRA_SECRET"],
  "agent_env": ["SOME_VAR_TO_FORWARD"],

  "setup": "pip install -r requirements.txt 2>/dev/null; npm install --silent 2>/dev/null; true",

  "snapshot_backend": "local",
  "s3_bucket": "my-ftl-snapshots",
  "cloudwatch_log_group": "/ftl/myproject",
  "secrets_manager_prefix": "/myproject/prod/",
  "guardrail_id": "abc123def456",
  "guardrail_version": "1"
}
```

## Configuration Fields

### Core Settings

**agent** `string` *required* (default: claude-code)

Agent to run. Options: `"claude-code"`, `"codex"`, `"aider"`, `"kiro"`

**tester** `string` *required* (default: claude-haiku-4-5-20251001)

LiteLLM model string for adversarial test generation

### Environment Variables

**shadow\_env** `array` (default: \[])

Extra environment variable names to shadow beyond what's in `.env`

```json theme={null}
{
  "shadow_env": ["DATABASE_URL", "STRIPE_SECRET_KEY"]
}
```

**agent\_env** `array` (default: \[])

Environment variables from your host to forward into the sandbox

```json theme={null}
{
  "agent_env": ["NODE_ENV", "DEBUG"]
}
```

### Setup Hook

**setup** `string`

Shell command run once on a **fresh container only**, before the agent starts

```json theme={null}
{
  "setup": "pip install -r requirements.txt 2>/dev/null; npm install --silent 2>/dev/null; true"
}
```

The `true` at the end prevents missing files from failing the boot. On warm container reuse, this command is skipped.

### Snapshot Storage

**snapshot\_backend** `string` (default: local)

Snapshot storage backend: `"local"` or `"s3"`

**s3\_bucket** `string`

S3 bucket name. Required when `snapshot_backend` is `"s3"`

```json theme={null}
{
  "snapshot_backend": "s3",
  "s3_bucket": "ftl-123456789012-us-east-1"
}
```

### AWS Integration

**cloudwatch\_log\_group** `string`

CloudWatch log group for session traces

```json theme={null}
{
  "cloudwatch_log_group": "/ftl/myproject"
}
```

**secrets\_manager\_prefix** `string`

AWS Secrets Manager prefix. When set, replaces `.env` as the secrets source

```json theme={null}
{
  "secrets_manager_prefix": "/myproject/prod/"
}
```

Secrets with JSON object values are expanded into individual keys. Plain-string secrets use the last path segment as the key name, uppercased.

**guardrail\_id** `string`

Bedrock Guardrail ID. When set, replaces the local lint scan with a Bedrock Guardrail that hard-blocks merge if it intervenes

```json theme={null}
{
  "guardrail_id": "abc123def456",
  "guardrail_version": "1"
}
```

**guardrail\_version** `string` (default: DRAFT)

Guardrail version to apply

## Tester Model Configuration

The `tester` field accepts any [LiteLLM-supported model](https://docs.litellm.ai/docs/providers):

> [tab] Anthropic Direct
>
> Default option using Anthropic API:
>
> ```json .ftlconfig theme={null}
> {
>   "tester": "claude-haiku-4-5-20251001"
> }
> ```
>
> Requires `ANTHROPIC_API_KEY`.

> [tab] AWS Bedrock
>
> Use Claude via AWS Bedrock:
>
> ```json .ftlconfig theme={null}
> {
>   "tester": "bedrock/us.anthropic.claude-sonnet-4-6"
> }
> ```
>
> Requires AWS credentials.

> [tab] OpenAI
>
> Use OpenAI models:
>
> ```json .ftlconfig theme={null}
> {
>   "tester": "openai/gpt-4o-mini"
> }
> ```
>
> Requires `OPENAI_API_KEY`.

> [tab] Disable Testing
>
> Skip test generation:
>
> ```json .ftlconfig theme={null}
> {
>   "tester": ""
> }
> ```

> [!NOTE]
>
> The tester runs in parallel with the agent, so model latency doesn't add to wall-clock time.

## Setup Examples

### Basic Python Project

```json .ftlconfig theme={null}
{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001",
  "setup": "pip install -r requirements.txt 2>/dev/null; true",
  "shadow_env": ["DATABASE_URL", "STRIPE_SECRET_KEY"]
}
```

### Node.js Project

```json .ftlconfig theme={null}
{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001",
  "setup": "npm install --silent 2>/dev/null; true",
  "shadow_env": ["SUPABASE_URL", "SUPABASE_ANON_KEY"]
}
```

### Full-Stack with AWS

```json .ftlconfig theme={null}
{
  "agent": "claude-code",
  "tester": "bedrock/us.anthropic.claude-sonnet-4-6",
  "setup": "pip install -r requirements.txt 2>/dev/null; npm install --silent 2>/dev/null; true",
  
  "snapshot_backend": "s3",
  "s3_bucket": "ftl-123456789012-us-east-1",
  "cloudwatch_log_group": "/ftl/myproject",
  "secrets_manager_prefix": "/myproject/prod/",
  "guardrail_id": "gr1a2b3c4d5e",
  "guardrail_version": "1",
  
  "shadow_env": ["DATABASE_URL", "STRIPE_SECRET_KEY", "OPENAI_API_KEY"]
}
```

## Initializing Configuration

**1. Run ftl init**

Create `.ftlconfig` in your project root:

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

This creates `.ftlconfig` with values from your global config.

**2. Edit .ftlconfig**

Customize settings for your project:

```json .ftlconfig theme={null}
{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001",
  "setup": "pip install -r requirements.txt"
}
```

**3. Commit to Git**

Add `.ftlconfig` to version control:

```bash theme={null}
git add .ftlconfig
git commit -m "Add FTL configuration"
```

## AWS Quick Setup

Provision all AWS resources and update `.ftlconfig` in one command:

```bash theme={null}
ftl config --aws
```

This wizard:

**1. Reads AWS Identity**

Uses STS to get your account ID and region

**2. Creates S3 Bucket**

Creates `ftl-<account>-<region>` (idempotent)

**3. Creates CloudWatch Log Group**

Creates `/ftl/<project-name>` (idempotent)

**4. Creates Bedrock Guardrail**

Creates `ftl-<project-name>` with PII and credential blocking

**5. Prompts for Secrets Manager**

Optional Secrets Manager prefix for secret storage

**6. Updates .ftlconfig**

Merges all resource IDs into your project config

> [!WARNING]
>
> Running `ftl config --aws` requires:
>
> * `pip install -e ".[aws]"` for boto3
> * AWS credentials configured (via `aws configure` or `ftl auth`)

## Finding Configuration

FTL walks up from the current directory to find `.ftlconfig`, similar to how Git finds `.git`:

```python theme={null}
from pathlib import Path

def find_config():
    current = Path.cwd()
    for parent in [current, *current.parents]:
        config_path = parent / ".ftlconfig"
        if config_path.exists():
            return config_path
    return None
```

This allows you to run `ftl` commands from any subdirectory in your project.

## Configuration Validation

FTL validates that required keys are present:

```python theme={null}
REQUIRED_KEYS = {"agent", "tester"}

missing = REQUIRED_KEYS - set(config.keys())
if missing:
    raise ValueError(f"Missing required keys in .ftlconfig: {missing}")
```

If validation fails, FTL exits with a clear error message.


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