Getting Started
QualiLens runs entirely on your computer. Download the release, confirm the prerequisites below, and launch.
Mac (Apple silicon) and Linux
QualiLens is developed and tested on macOS, and it runs natively on Macs with Apple silicon (M1 or later) and on Linux with no extra setup, because the launcher is a shell script (run.sh). Intel Macs are not supported, because a library the app needs for encryption and for checking update signatures is no longer published for them. Start with Step 1 below.
Running Windows? See Setting up WSL below.
Setting up WSL on Windows
QualiLens needs a Unix shell. On Windows, WSL (Windows Subsystem for Linux) provides one inside a lightweight Linux environment that runs alongside Windows. If WSL is already installed on your machine, skip to Step 1.
Open PowerShell as Administrator
Right-click the Start button and choose Terminal (Admin) or Windows PowerShell (Admin).
Install WSL
wsl --installThis installs WSL 2 with Ubuntu. Restart your computer when prompted.
Create your Linux user
After restarting, Ubuntu opens automatically and asks for a username and password. These are local to the Linux environment — choose whatever you like.
WSL is ready. Continue with Step 1 below — the remaining steps apply to all platforms. For troubleshooting or alternative distributions, see Microsoft's Install WSL documentation.
Check the requirements
QualiLens builds its own Python environment on first launch. The following must already be present.
| Requirement | Why | Check | Install |
|---|---|---|---|
| Python 3.11+ | Runs the backend and analysis pipelines | python3 --version | brew install python@3.12 or python.org |
| Node 18+ & npm (clone only) | Builds the interface once, on first launch. Not needed if you downloaded the release ZIP | node -v | nodejs.org |
| ffmpeg (optional) | Extracts audio from video; splits large recordings | ffmpeg -version | brew install ffmpeg |
You can skip ffmpeg if you only upload documents and audio files under about 24 MB. You will need it for video or large audio files.
WSL users: If Python is missing, open your Ubuntu terminal and run:
sudo apt update && sudo apt install python3 python3-pip python3-venv -yIf your distribution ships an older version, add the deadsnakes PPA: sudo add-apt-repository ppa:deadsnakes/ppa and install python3.12.
Download QualiLens
Download the latest release, unzip it, and place the folder wherever you like. The release includes the pre-built interface — you need only Python, no Node or npm.
Download QualiLens.zipDevelopers who want to modify the code can clone the repository instead — this path requires Node 18+ to build the interface on first launch.
git clone https://github.com/iconerr/qualilens.gitCloud sync warning. If the folder sits inside a Dropbox, iCloud, or OneDrive directory, do not run QualiLens on two computers against the same synced database simultaneously. Let the sync finish completely before opening the app on a second machine.
Launch QualiLens
Open a terminal in the QualiLens folder and run the launcher.
./run.shThe first run creates a Python environment, installs dependencies, and builds the interface — expect a minute or two. Every launch after the first is much faster. Once the server is up, it prints the address and opens QualiLens in your browser, signed in.
QualiLens running at http://127.0.0.1:8765 (Ctrl-C to stop)
The launch page that signs a browser in is /var/folders/…/qualilens.Ab12Cd/open.htmlThe launcher signs in the browser it opens. To use QualiLens in another browser, open the launch page the terminal names. The address on its own shows how to open QualiLens instead of your projects, so another account on the same computer cannot reach your data through it.
Stop the app with Ctrl-C in the terminal. Closing the browser tab does not stop it — runs continue in the background.
WSL users: Your Windows drives are mounted under /mnt/. Open the Ubuntu terminal and navigate to the QualiLens folder:
cd /mnt/c/Users/YourName/Downloads/QualiLensReplace YourName with your Windows username. You can find it by running cmd.exe /c "echo %USERNAME%" inside WSL.
Add an API key
Open Settings from the top bar. Each provider gets its own card with Save, Test, and Remove controls. Paste your key, press Save, then Test to confirm it works.
You need a key from at least one of the four providers: Anthropic, OpenAI, Google, or Mistral. If you plan to upload audio or video, you also need an OpenAI key — transcription runs through OpenAI's Whisper service regardless of which provider performs the analysis.
Where keys are stored. Keys live in the local SQLite database, encrypted. The secret that unlocks them is a small file outside the data folder (~/Library/Application Support/QualiLens/secret.key on macOS, ~/.config/qualilens/secret.key on Linux and WSL), readable by your account only, so a synced or copied database carries no usable key. Someone using your own account on your own computer can still read both files: use Remove before handing the computer to someone, and prefer a key scoped to this work, with its own spending limit.
Run your first analysis
Click New analysis. The wizard covers method selection, configuration, model choice, data upload, and cost estimation.
Start with a single short document — a typical first run costs a few cents and exposes all checkpoints before you commit a full corpus.
Accepted file types
Audio and video require an OpenAI key for transcription. Video also requires ffmpeg.
Updating QualiLens
Open Settings and find the Application card. Check for updates queries GitHub for the latest release (one request; nothing of yours is transmitted). When a newer release exists, Download and install applies it through a validated updater that replaces only application files — projects, keys, and uploads are structurally excluded.
After the update the app stops itself. Start it again with ./run.sh.