航班价格追踪器

Requirements

• Node.js >= 22 (for local development; not needed for the Docker install path)
• Docker Desktop
• One of:
• Claude Code (free with Claude Pro/Max)
• Codex (free with ChatGPT Pro)
• An API key from Anthropic, OpenAI, or Google
• Ollama, llama.cpp, or vLLM

<details> <summary>LLM Providers</summary>

Flight Finder needs an LLM for two things: parsing natural language queries and extracting price data from Google Flights pages.

Three ways to use Flight Finder:

• Subscription users (Claude Pro/Max, ChatGPT Pro) -- auto-detected, auth tokens mounted read-only.
• API key users -- paste a key, passed via env var, never written to disk.
• Local model users -- select Ollama/llama.cpp/vLLM in the admin UI, type your model ID.

Picking a local model (Ollama, llama.cpp, vLLM):

The parse step needs a model that follows strict JSON instructions. Tiny models tend to ramble or refuse. Stick with current generation families that have reliable structured output. Qwen3 / Qwen3.5 currently have the most stable tool calling and JSON behaviour in the small model class; Gemma 3n / Gemma 4 are strong alternatives with native function calling on the laptop tier.

• CPU only, tight RAM: qwen3:0.6b (523MB) or qwen3.5:0.8b (1.0GB). JSON mode is forced server side, so even these can produce parseable output.
• CPU only, typical desktop: qwen3:1.7b (1.4GB) or qwen3:4b (2.5GB, sweet spot if you have the RAM).
• CPU or GPU edge (5 to 8GB): gemma3n:e2b (5.6GB, 32K context) or gemma4:e2b (7.2GB, 128K context, newer).
• GPU (8GB+ VRAM): qwen3.5:9b (6.6GB, best JSON quality and speed balance), qwen3:8b (5.2GB), or gemma4:e4b (9.6GB, native function calling).

Avoid models under 1B (TinyLlama, etc.) and older generations (Llama 3.x, Qwen 2.5). They tend to ramble even with JSON mode forcing valid syntax, because the field values still need to be semantically correct. For slow CPUs, bump EXTRACT_TIMEOUT_MS in .env if larger models keep timing out (default 90000). </details>

Setup

1. During install, say yes to "Set up ExpressVPN?" and paste your activation code -- or paste it later in Settings 2. The VPN sidecar starts automatically with Flight Finder (no extra commands needed) 3. When creating a new tracker, toggle "Compare prices from different countries" and pick which countries to compare 4. Each scrape run: local baseline first, then each VPN country sequentially 5. On the chart page, use the view filter to switch between: - All countries (full detail) - Country comparison (cheapest price per country over time) - Local only / individual country isolation

<details> <summary>docker-compose.vpn.yml details</summary>

The VPN sidecar uses misioslav/expressvpn and exposes: - SOCKS5 proxy on port 1080 (internal, used by Playwright) - REST API on port 8000 (internal, used by Flight Finder to switch countries)

Requirements: - EXPRESSVPN_CODE in ~/.flight-finder/.env - Docker host must have /dev/net/tun (kernel TUN module) - The sidecar needs NET_ADMIN capability

Only Playwright traffic goes through the VPN. Database, Redis, and web UI traffic stay on normal Docker networking. </details>

<details> <summary>Supported countries</summary>

US, GB, DE, FR, ES, IT, NL, IE, JP, KR, IN, AU, CA, MX, BR, AR, CO, TH, SG, HK

Each country profile aligns: locale, timezone, Accept-Language header, and geolocation to match the VPN exit point. Currency stays user-controlled (independent from VPN country). </details>

Quick Start

curl -fsSL https://flight-finder.org/install.sh | bash

If you have Claude Code or Codex installed, the setup script detects it automatically. Otherwise, it asks you to paste an API key.

Once it finishes:

1. Open localhost:3003
2. Or run flight-finder search "NYC to Tokyo in July under $800"
3. Flight Finder starts tracking prices immediately

Scraping Constraints

Flight Finder walks an ordered chain of price sources per query. The chain is admin allowlisted and per user orderable. Each source has different reliability:

Skyscanner and Kayak are off by default. Admin enables them in /admin/config; users then order them in /account/settings. When a source returns no flights the next source in the chain runs; an all_filtered_out result (real flights existed but query filters excluded them) short circuits the chain because changing sources cannot help.

For Skyscanner and Kayak to be production grade you would need residential proxies or paid CAPTCHA solving, neither of which Flight Finder ships. If those sources fail consistently for your route, leave them off.

VPN Price Comparison

Test the myth that VPN location affects flight prices. Flight Finder can scrape the same query from multiple countries and show the results side by side.