Quickstart

Get FTL running in under 5 minutes

Get started in four steps

This guide will take you from zero to running your first AI coding task in an isolated sandbox.

Prerequisites: Python 3.11+, Docker Desktop (or Docker Engine on Linux), and an Anthropic API key from console.anthropic.com

On Linux, also install rsync: apt install rsync

Step 1: Install FTL

Install from GitHub

git clone https://github.com/vvennela/ftl
cd ftl
pip install -e .

Use a virtual environment to avoid conflicts:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Step 2: Run setup wizard

The one-time setup wizard configures your agent, tester model, and API credentials:

ftl setup

You’ll be prompted to:

1. Choose your agent

   Select which AI coding agent to use:

   Which agent do you want to use?
     1. Claude Code  (Anthropic, recommended)
     2. Codex        (OpenAI)
     3. Aider        (open-source)
     4. Kiro         (AWS)
     Choice [1]:
   

   The wizard pulls the appropriate Docker image from vvenne/ftl:<tag>

2. Choose test generation model

   Select the LLM model for adversarial test generation:

   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]:
   

   Tests generate in parallel while the agent codes, so there’s no added latency

3. Save your API key

   If you haven’t set ANTHROPIC_API_KEY yet:

   Anthropic API key
     Get one at https://console.anthropic.com
     ANTHROPIC_API_KEY: sk-ant-...
   

   Your key is saved to ~/.ftl/credentials (mode 600) and loaded automatically on every invocation

Your choices are saved globally to ~/.ftl/config.json and used as defaults for every new project.

Docker Hub images are pulled automatically:

• vvenne/ftl:latest — Claude Code
• vvenne/ftl:codex — Codex
• vvenne/ftl:aider — Aider
• vvenne/ftl:kiro — Kiro
• vvenne/ftl:full — All agents

If the pull fails, FTL builds the image locally from your cloned Dockerfile.

Step 3: Initialize your project

Navigate to your project directory and create a .ftlconfig:

cd your-project
ftl init

This creates .ftlconfig with values from your global setup:

.ftlconfig

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

Edit .ftlconfig to override settings per-project. See Configuration reference for all available fields.

Step 4: Run your first task

ftl code 'create a Stripe payment module'

1. Snapshot

   FTL snapshots your project to ~/.ftl/snapshots/<id> using rsync

2. Boot sandbox

   Docker container starts (or reuses existing) with shadow credentials injected

3. Agent + tests run in parallel

   Claude Code writes code while adversarial tests generate simultaneously

   Running agent  (generating tests in parallel via claude-haiku-4-5-20251001)
   
4. Review and approve

   FTL shows you a diff of all changes. You can:

   • Type a — approve and merge changes to your project
   • Type r — reject and discard all changes
   • Type any question — ask the model about the diff (e.g. “does this handle null inputs?”)

   Review diff and approve or reject changes:
     a — approve and merge
     r — reject and discard
     or ask a question about the changes
   
   Your choice >
   

Changes only touch your project after you type a and confirm. The agent never has direct write access to your filesystem.

What just happened?

Let’s break down the FTL workflow:

Snapshot creation

FTL uses rsync to copy your project state to ~/.ftl/snapshots/<id>. Files matching .ftlignore patterns are excluded (similar to .gitignore).

The snapshot is mounted read-only into the Docker container at /workspace.

Shadow credentials

If you have a .env file in your project root:

.env

STRIPE_SECRET_KEY=sk_live_abc123
OPENAI_API_KEY=sk-proj-xyz789

FTL generates shadow values and injects them into the sandbox:

Sandbox environment

STRIPE_SECRET_KEY=ftl_shadow_stripe_secret_key_7f8a2b3c
OPENAI_API_KEY=ftl_shadow_openai_api_key_4d9e2a1f

Your real keys never enter the container. The agent writes code using shadow values.

Parallel test generation

While the agent codes, FTL sends your task description to the tester model with a prompt like:

Generate adversarial tests for this task:
"create a Stripe payment module"

Write pytest test cases that verify:
- Correct implementation
- Error handling
- Edge cases

Tests run immediately when the agent finishes, catching issues before you review.

Credential linting

Before showing the diff, FTL scans for:

• Hardcoded shadow values (ftl_shadow_* pattern)
• Known credential patterns (Stripe keys, AWS keys, GitHub tokens, etc.)
• Dangerous SQL operations (DROP TABLE, TRUNCATE without WHERE)
• Dangerous shell commands (rm -rf, chmod -R 777)

Findings are displayed as warnings but never block review (unless you configure Bedrock Guardrails).

Next steps

Interactive shell

Use ftl (no arguments) for follow-up instructions without cold boots

Adding credentials

Learn about ftl auth for saving additional API keys

AWS setup

Configure S3 snapshots, CloudWatch tracing, and Bedrock Guardrails

Configuration reference

All available .ftlconfig fields and their defaults

Troubleshooting

Docker not found or not running

[red]Docker not found. Install Docker Desktop and try again.[/red]

Solution: Install Docker Desktop from docs.docker.com/get-docker and ensure it’s running.

No .ftlconfig found

[red]No .ftlconfig found. Run 'ftl init' first.[/red]

Solution: Navigate to your project directory and run ftl init.

ANTHROPIC_API_KEY is not set

[bold red]ANTHROPIC_API_KEY is not set.[/bold red]
  Run: ftl auth ANTHROPIC_API_KEY <your-key>

Solution: Save your API key:

ftl auth ANTHROPIC_API_KEY sk-ant-...

Image pull fails

If ftl setup can’t pull from Docker Hub, it falls back to building locally. This requires the Dockerfile in your cloned ftl repository.

If the build fails, check that you cloned the full repository and didn’t just install via pip.

Need more help? Join our GitHub Discussions or file an issue.