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

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

> [!NOTE]
>
> **Prerequisites:** Python 3.11+, Docker Desktop (or Docker Engine on Linux), and an Anthropic API key from [console.anthropic.com](https://console.anthropic.com)
>
> On Linux, also install rsync: `apt install rsync`

### Step 1: Install FTL

```bash Install from GitHub theme={null}
git clone https://github.com/vvennela/ftl
cd ftl
pip install -e .
```

```bash Verify installation theme={null}
ftl --version
```

> [!TIP]
>
> Use a virtual environment to avoid conflicts:
>
> ```bash theme={null}
> 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:

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

> [!WARNING]
>
> **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`:

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

This creates `.ftlconfig` with values from your global setup:

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

> [!TIP]
>
> Edit `.ftlconfig` to override settings per-project. See [Configuration reference](https://vvennela-ftl-18-95.mintlify.site/configuration/ftlconfig.md) for all available fields.

### Step 4: Run your first task

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

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

> [accordion] 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`.

> [accordion] Shadow credentials
>
> If you have a `.env` file in your project root:
>
> ```bash .env theme={null}
> STRIPE_SECRET_KEY=sk_live_abc123
> OPENAI_API_KEY=sk-proj-xyz789
> ```
>
> FTL generates shadow values and injects them into the sandbox:
>
> ```bash Sandbox environment theme={null}
> 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.

> [accordion] 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.

> [accordion] 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

> [card] [Interactive shell](https://vvennela-ftl-18-95.mintlify.site/guides/interactive-shell.md)
>
> Use `ftl` (no arguments) for follow-up instructions without cold boots

> [card] [Adding credentials](https://vvennela-ftl-18-95.mintlify.site/cli/auth.md)
>
> Learn about `ftl auth` for saving additional API keys

> [card] [AWS setup](https://vvennela-ftl-18-95.mintlify.site/guides/aws-setup.md)
>
> Configure S3 snapshots, CloudWatch tracing, and Bedrock Guardrails

> [card] [Configuration reference](https://vvennela-ftl-18-95.mintlify.site/configuration/ftlconfig.md)
>
> All available `.ftlconfig` fields and their defaults

## Troubleshooting

> [accordion] Docker not found or not running
>
> ```bash theme={null}
> [red]Docker not found. Install Docker Desktop and try again.[/red]
> ```
>
> **Solution:** Install Docker Desktop from [docs.docker.com/get-docker](https://docs.docker.com/get-docker/) and ensure it's running.

> [accordion] No .ftlconfig found
>
> ```bash theme={null}
> [red]No .ftlconfig found. Run 'ftl init' first.[/red]
> ```
>
> **Solution:** Navigate to your project directory and run `ftl init`.

> [accordion] ANTHROPIC\_API\_KEY is not set
>
> ```bash theme={null}
> [bold red]ANTHROPIC_API_KEY is not set.[/bold red]
>   Run: ftl auth ANTHROPIC_API_KEY <your-key>
> ```
>
> **Solution:** Save your API key:
>
> ```bash theme={null}
> ftl auth ANTHROPIC_API_KEY sk-ant-...
> ```

> [accordion] 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.

> [!NOTE]
>
> **Need more help?** Join our [GitHub Discussions](https://github.com/vvennela/ftl/discussions) or file an issue.


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