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

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

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

```json theme={null}
{
  "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:**

```json theme={null}
{ "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](https://docs.litellm.ai/docs/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.

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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`.

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

> [!NOTE]
>
> 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`)

```json theme={null}
{
  "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`.

```json theme={null}
{
  "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.

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

> [!TIP]
>
> 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).

```json theme={null}
{
  "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.

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

> [!WARNING]
>
> 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.

```json theme={null}
{
  "guardrail_version": "1"
}
```

## Complete Example

```json .ftlconfig theme={null}
{
  "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`:

```json .ftlconfig theme={null}
{
  "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.

```json ~/.ftl/config.json theme={null}
{
  "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`


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