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:

~/.ftl/config.json

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

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:

.ftlconfig

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

Configuration Precedence

Settings are merged in this order:

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

Full Configuration Schema

.ftlconfig

{
  "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 · default: "claude-code" · required

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

tester · string · default: "claude-haiku-4-5-20251001" · required

LiteLLM model string for adversarial test generation

Environment Variables

shadow_env · array · default: "[]"

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

{
  "shadow_env": ["DATABASE_URL", "STRIPE_SECRET_KEY"]
}

agent_env · array · default: "[]"

Environment variables from your host to forward into the sandbox

{
  "agent_env": ["NODE_ENV", "DEBUG"]
}

Setup Hook

setup · string

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

{
  "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"

{
  "snapshot_backend": "s3",
  "s3_bucket": "ftl-123456789012-us-east-1"
}

AWS Integration

cloudwatch_log_group · string

CloudWatch log group for session traces

{
  "cloudwatch_log_group": "/ftl/myproject"
}

secrets_manager_prefix · string

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

{
  "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

{
  "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:

Anthropic Direct

Default option using Anthropic API:

.ftlconfig

{
  "tester": "claude-haiku-4-5-20251001"
}

Requires ANTHROPIC_API_KEY.

AWS Bedrock

Use Claude via AWS Bedrock:

.ftlconfig

{
  "tester": "bedrock/us.anthropic.claude-sonnet-4-6"
}

Requires AWS credentials.

OpenAI

Use OpenAI models:

.ftlconfig

{
  "tester": "openai/gpt-4o-mini"
}

Requires OPENAI_API_KEY.

Disable Testing

Skip test generation:

.ftlconfig

{
  "tester": ""
}

The tester runs in parallel with the agent, so model latency doesn’t add to wall-clock time.

Setup Examples

Basic Python Project

.ftlconfig

{
  "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

.ftlconfig

{
  "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

.ftlconfig

{
  "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:

   cd your-project
   ftl init
   

   This creates .ftlconfig with values from your global config.

2. Edit .ftlconfig

   Customize settings for your project:

   .ftlconfig

   {
     "agent": "claude-code",
     "tester": "claude-haiku-4-5-20251001",
     "setup": "pip install -r requirements.txt"
   }
   
3. Commit to Git

   Add .ftlconfig to version control:

   git add .ftlconfig
   git commit -m "Add FTL configuration"
   

AWS Quick Setup

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

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

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:

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:

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.