Firn is a high-performance, multi-tenant vector and full-text search engine backed by object storage (AWS S3, MinIO, Cloudflare R2, Tigris, DigitalOcean Spaces). It is designed as a credible open-source alternative to turbopuffer, proving that a professional-grade tiered storage architecture (RAM → NVMe → S3) is achievable entirely from open-source components. See Storage backends for the full compatibility matrix.

The cost efficiency of S3 with the speed of local RAM. A multi-tenant vector and full-text search engine backed by S3. Built with LanceDB and Foyer for microsecond-scale search latency on top of object storage.

On real-world cloud infrastructure (AWS S3), a raw linear scan of 100,000 vectors can take 25 seconds per query. By pairing LanceDB with a tiered foyer (RAM + NVMe) cache, Firn collapses that bottleneck:

• Cold Query (S3 Linear Scan): ~25.1s
• Cold Query (ANN Indexed): ~979ms (25x faster)
• Warm Query (Internal Engine): ~72µs (350,000x faster)
• End-to-End HTTP (Warm): < 5ms (including network RTT and JSON overhead)

Every cache hit results in zero S3 requests, directly reducing your cloud bill while providing "instant" search response times.

Cold query, warm query, full-text search, and cache proof, all in 60 seconds. This demo runs against local MinIO; on real AWS S3 the cold query takes 25 seconds instead of 109ms, making the cache speedup even more dramatic.

Firn is built on a "Tiered Storage" philosophy:

1. L1: RAM Cache (via foyer): Sub-microsecond access for the most frequent queries.
2. L2: NVMe Cache (via foyer): Fast, durable cache for high-volume search results.
3. L3: Object Storage (via LanceDB + S3/MinIO): The "Source of Truth" where every namespace is isolated under its own S3 prefix.

• axum: High-performance async REST API.
• LanceDB: Vector and BM25 search engine that runs natively on object storage.
• foyer: Advanced hybrid cache (RAM + NVMe) with LFU/LRU eviction.
• Prometheus: Full operational visibility into cache hits, misses, and S3 request savings.

Firn's correctness depends on S3's If-None-Match: * precondition behaving as a strictly linearisable compare-and-swap across concurrent writers. LanceDB's commit protocol uses it to serialise manifest updates, so a backend that ignores or incorrectly handles this header will silently lose writes. Every provider below has been tested with the same two checks: a sequential conditional-PUT pre-flight, and an 8-writer x 100-row concurrent stress (the passing backends additionally survive 100 consecutive runs). The test harness is in crates/firnflow-core/tests/.

The two dedicated tests live at crates/firnflow-core/tests/s3_conditional_writes.rs and crates/firnflow-core/tests/lance_concurrent_writes.rs. Both are #[ignore]'d and require credentials to run. If you want to evaluate a backend not in the table, copy a block from either file and point it at your own bucket.

• Multi-tenant by Design: Each namespace maps to an isolated S3 prefix (s3://bucket/namespace/) with near-zero idle cost.
• Instant Invalidation: A "Generation Counter" strategy ensures that after a write, all stale search results for that namespace are invalidated in $O(1)$ time.
• CAS Consistency: Verified concurrency safety using S3's If-None-Match: * to prevent data loss when multiple writers fight for the same bucket.
• Zero-Copy Ready: Optimized serialization via bincode (with architectural triggers to move to rkyv if needed).
• Operational Excellence: Native Prometheus metrics tracking cache hit rates and S3 request count (the primary signal for cost savings).

Everything you need (MinIO storage + Firn API) is orchestrated via Docker Compose:

git clone https://github.com/gordonmurray/firnflow
cd firnflow
docker compose up --build

The API is live at http://localhost:3000. Save a vector to the demo namespace:

curl -X POST http://localhost:3000/ns/demo/upsert \
     -H 'Content-Type: application/json' \
     -d '{
       "rows": [
         {"id": 1, "vector": [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]}
       ]
     }'

Query the same namespace for the nearest neighbor:

curl -X POST http://localhost:3000/ns/demo/query \
     -H 'Content-Type: application/json' \
     -d '{"vector": [1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0], "k": 1}'

See how much S3 traffic you've avoided:

curl http://localhost:3000/metrics | grep s3_requests

Firn ships with optional bearer-token authentication on the REST API. Both keys are opt-in:

Header format on every protected request: Authorization: Bearer <token>.

If FIRNFLOW_ADMIN_API_KEY is unset, the read/write key authorises admin routes too (single-key fallback). Set both keys to a different value to lock destructive operations behind a separate credential. If neither key is set the API stays open and logs a single startup WARN — this preserves the default-open posture of the local-dev compose stack.

export FIRNFLOW_API_KEY=$(openssl rand -hex 32)
curl -X POST http://localhost:3000/ns/demo/upsert \
     -H "Authorization: Bearer $FIRNFLOW_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"rows": [...]}'

This is service-level authentication. Any holder of FIRNFLOW_API_KEY can read or write any namespace; any holder of FIRNFLOW_ADMIN_API_KEY can additionally delete or rebuild indexes on any namespace. If you need per-tenant namespace isolation, place Firn behind an authenticating gateway that enforces tenant-to-namespace authorisation. See docs/configuration.html for the rate-limiting knobs (FIRNFLOW_RATE_LIMIT_RPS, FIRNFLOW_RATE_LIMIT_BURST, FIRNFLOW_PREAUTH_IP_LIMIT_RPS) and the FIRNFLOW_TRUST_PROXY_HEADERS switch for deployments behind a load balancer.

Auth column: open = no header required; read/write = FIRNFLOW_API_KEY (or FIRNFLOW_ADMIN_API_KEY); admin = FIRNFLOW_ADMIN_API_KEY if configured, otherwise FIRNFLOW_API_KEY via the single-key fallback. /metrics is metrics when FIRNFLOW_METRICS_TOKEN is set, otherwise open.

Firn uses a containerized toolchain. No local Rust installation is required.

# Run the full test suite (requires MinIO)
./scripts/cargo test --workspace -- --ignored

# Run the cold-vs-warm latency benchmark
./scripts/cargo run --release -p firnflow-bench

Benchmark results are committed at bench/results/cold_vs_warm.md.