.ftlconfig Reference

Complete reference for the .ftlconfig project configuration file

Overview

The .ftlconfig file is a JSON configuration file placed in your project root that controls FTL’s behavior for that specific project. It is created by ftl init and can be edited manually to customize settings.

File Location

FTL searches for .ftlconfig by walking up from the current working directory to parent directories, similar to how Git finds .git. This means you can run FTL commands from subdirectories of your project.

ftl init  # Creates .ftlconfig in current directory

Configuration Hierarchy

Configuration values are merged in the following order (later values override earlier ones):

1. Built-in defaults - Hard-coded fallback values
2. Global config (~/.ftl/config.json) - Set during ftl setup
3. Project config (.ftlconfig) - Project-specific overrides

Required Fields

agent · string · required

The coding agent to use inside the sandbox.

Valid values:

• "claude-code" - Claude Code (requires ANTHROPIC_API_KEY)
• "codex" - Codex (requires OPENAI_API_KEY)
• "aider" - Aider (requires OPENAI_API_KEY or ANTHROPIC_API_KEY)
• "kiro" - Kiro (requires AWS credentials + browser login)

Default: "claude-code"

{
  "agent": "claude-code"
}

tester · string · required

LiteLLM model string for adversarial test generation. The tester runs in parallel with the agent.

Default: "claude-haiku-4-5-20251001"

Examples:

{ "tester": "claude-haiku-4-5-20251001" }               // Anthropic direct
{ "tester": "bedrock/us.anthropic.claude-sonnet-4-6" }   // AWS Bedrock
{ "tester": "openai/gpt-4o-mini" }                       // OpenAI

See LiteLLM providers for all supported models.

Optional Fields

Credential Management

shadow_env · array · default: "[]"

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

These variables are loaded from your host os.environ, replaced with shadow values in the sandbox, and tracked for credential swapping.

{
  "shadow_env": ["MY_EXTRA_SECRET", "API_TOKEN"]
}

agent_env · array · default: "[]"

Environment variables from your host to forward into the sandbox without shadowing.

Use this for non-sensitive configuration like NODE_ENV or LOG_LEVEL.

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

Container Setup

setup · string

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

Use this for installing project dependencies. The command runs inside the sandbox at /workspace.

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

The true at the end prevents failure if files are missing. The setup command is skipped on warm container reuse — packages persist in /home/ftl/.local/ across tasks.

Snapshot Backend

snapshot_backend · string · default: "local"

Where to store project snapshots.

Valid values:

• "local" - rsync to ~/.ftl/snapshots/
• "s3" - Upload to S3 (requires s3_bucket)

{
  "snapshot_backend": "s3"
}

s3_bucket · string

S3 bucket name for snapshots. Required when snapshot_backend is "s3".

Snapshots are stored as gzipped tarballs at s3://<bucket>/snapshots/<project-hash>/<id>.tar.gz.

{
  "snapshot_backend": "s3",
  "s3_bucket": "my-ftl-snapshots"
}

AWS Integrations

cloudwatch_log_group · string

CloudWatch log group for session traces. When set, FTL emits structured JSON events for each session stage.

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

Use ftl config --aws to provision this automatically.

secrets_manager_prefix · string

AWS Secrets Manager path prefix. When set, FTL fetches secrets from Secrets Manager instead of reading .env.

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

{
  "secrets_manager_prefix": "/myproject/prod/"
}

guardrail_id · string

Bedrock Guardrail ID for diff safety checking. When set, FTL applies the guardrail to the full diff text before human review, replacing the local lint scan.

If the guardrail intervenes (detects credentials, PII, etc.), the merge is hard-blocked and changes are discarded.

{
  "guardrail_id": "abc123def456",
  "guardrail_version": "1"
}

Guardrail intervention results in automatic rejection — no manual review.

guardrail_version · string · default: "DRAFT"

Bedrock Guardrail version to apply. Used only when guardrail_id is set.

{
  "guardrail_version": "1"
}

Complete Example

.ftlconfig

{
  "agent": "claude-code",
  "tester": "claude-haiku-4-5-20251001",
  
  "shadow_env": ["MY_EXTRA_SECRET"],
  "agent_env": ["NODE_ENV", "LOG_LEVEL"],
  
  "setup": "pip install -r requirements.txt 2>/dev/null; npm install --silent 2>/dev/null; true",
  
  "snapshot_backend": "s3",
  "s3_bucket": "my-ftl-snapshots",
  "cloudwatch_log_group": "/ftl/myproject",
  "secrets_manager_prefix": "/myproject/prod/",
  "guardrail_id": "abc123def456",
  "guardrail_version": "1"
}

Minimal Example

The smallest valid .ftlconfig created by ftl init:

.ftlconfig

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

Global Config

The file ~/.ftl/config.json stores machine-wide defaults set during ftl setup. Project .ftlconfig files override these values.

~/.ftl/config.json

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

Source Reference

Configuration loading: ftl/config.py:45-61

Default values: ftl/config.py:9-14