Quickstart Guide

Deploy a complete local instance of Flit with Docker Compose in under five minutes. This guide walks you through configuration, database migrations, administrator bootstrapping, and making your first routed API call.

Step 1: Clone Repository

Clone the Flit repository including its pinned submodules:

Terminal

git clone --recurse-submodules https://github.com/RytQlk/flit.git
cd flit

Step 2: Initialize Runtime Secrets & Environment

From the repository root, copy the base environment file and run the automated runtime secret provisioning script:

Terminal

cp src/deployment/docker/.env.example src/deployment/docker/.env
python3 scripts/setup_runtime_secrets.py

The interactive setup generates individual, file-based secrets under src/deployment/docker/secrets/:

litellm_master_key: Private upstream gateway management key (kept private behind Nginx).
litellm_salt_key: Cryptographic salt for virtual key hashing and token storage.
postgres_password: PostgreSQL cluster password.
redis_password: In-memory store authentication password.
aquila_cookie_encryption_key: 32-byte Fernet key for encrypting browser session cookies.
aquila_bootstrap_admin_password: Initial password for the local admin user.

💡

Validate Secrets: You can non-destructively inspect and validate your secrets configuration at any time by running:
python3 scripts/setup_runtime_secrets.py --validate-only

Step 3: Run Database Migrations

Execute upstream LiteLLM schema migrations followed by Flit's core migrations:

Terminal

cd src/deployment/docker
docker compose --profile migration run --rm litellm-migrate
docker compose --profile migration run --rm aquila-migrate

Step 4: Launch the Flit Stack

Start all runtime services (Nginx reverse proxy, LiteLLM gateway, Flit web application, PostgreSQL, and Redis):

Terminal

docker compose up -d --wait --wait-timeout 300

Verify that all containers are healthy:

Terminal

docker compose ps

🔑

Accessing the Admin Workspace: Open http://localhost:4000/admin in your browser. Log in with username admin and the password stored in secrets/aquila_bootstrap_admin_password. You will be prompted to change your password immediately upon first login.

Step 5: Send Your First Inference Request

Once you have configured a provider deployment and issued a virtual key in the admin console, dispatch requests through Nginx at http://localhost:4000/v1/chat/completions. Use the virtual model selector aquila to let Flit automatically route to the optimal tier:

cURL

curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-virtual-key" \
  -d '{
    "model": "aquila",
    "messages": [
      {"role": "user", "content": "Explain the difference between TCP and UDP in two sentences."}
    ]
  }'

🎉

Congratulations! Your request was received by Nginx on port 4000, classified in-memory by Flit's worker engine with zero hot-path database I/O, and forwarded to an active provider deployment in the appropriate tier (aquila-fast, aquila-smart, or aquila-power).