![Invariant LLM Connect](Invariant_LLM_Connect_Branding_v1/web/invariant-llm-connect-repository-banner.png)

# Invariant LLM Connect

**Invariant LLM Connect** is a dedicated lightweight browser for web-based LLM platforms.

It exists to run existing LLM web interfaces with substantially less unnecessary system overhead than a conventional general-purpose browser. It is intended to live beside the user's normal browser, not replace it.

> Give the resources to the model, not the browser.

## What It Does

Invariant LLM Connect loads configured LLM-platform URLs such as local, LAN, VPN, or remote web interfaces. The hosted platform remains responsible for chat, model controls, files, agents, RAG, tools, authentication, and other application behavior.

Connect provides the narrow browser environment needed to run those interfaces:

- user-defined LLM platform endpoints
- optional known-platform presets
- multiple tabs
- multiple windows
- controlled authentication flows where required
- controlled external previews with system-browser handoff for updates, authentication, downloads, and pop-ups
- manual tab suspension and future optional automatic suspension
- modern web security required by LLM applications

## What It Is Not

Invariant LLM Connect is not a general-purpose web browser, LLM frontend, inference server, model manager, agent framework, RAG system, AI assistant, search engine, Open WebUI-specific client, Chromium wrapper, or Electron application.

There is no normal address bar and no unrestricted browsing model. The `+` control opens configured LLM platforms, not arbitrary blank browser tabs.

## Engine Direction

Gecko is the required engine. Chromium, WebView2, CEF, and Electron are not product runtime options.

The final application should not merely be stock Firefox with changed preferences. Unneeded inherited browser functionality should be removed where practical while preserving critical security systems.

## Project Documents

- [PRODUCT-FOUNDATION.md](PRODUCT-FOUNDATION.md) defines the product boundary and philosophy.
- [ARCHITECTURE.md](ARCHITECTURE.md) records engineering constraints and implementation direction.
- [COMPATIBILITY.md](COMPATIBILITY.md) tracks tested platforms, engine versions, known limitations, and regressions.
- [CHANGELOG.md](CHANGELOG.md) records the complete development and release history.

These documents define the current product scope, architecture, compatibility expectations, and release history.

## Repository Layout

```text
assets/                 Branding asset staging and required asset manifest
config/                 Public-safe example configuration and schema
docs/                   Development plans and evaluation docs
packaging/linux/        Linux desktop-entry and packaging identity notes
packaging/windows/      Windows metadata and icon-package notes
src/Invariant.LlmConnect/Windows MVP spike
```

Example configuration uses non-sensitive local, LAN, and documentation-safe endpoints so public examples remain portable and safe to share.

## Current Build Status

The active Windows runtime is a full Firefox-source Gecko build with Invariant application identity. Artifact mode remains available for faster frontend iteration. Windows is the first build target; Linux follows from the same Gecko product source.

The former Windows WebView2 shell under `src/` is retired because WebView2 is Chromium-based. It must not be used for product, hardware, memory, CPU, or LLM testing. Root build, run, and publish commands are gated to Gecko only. See [docs/GECKO-MIGRATION.md](docs/GECKO-MIGRATION.md).

Implemented in the current Gecko development build:

- built-in Open WebUI preset at `http://localhost:8080`
- `+ Platform` picker with Open WebUI as a choice
- persistent custom platform name/URL entries
- multiple tabs
- back, forward, and reload controls
- marked external-preview tabs with a configurable system-browser or ask-every-time preference
- Invariant branding in the browser chrome
- automated live-process verification for Gecko and against Chromium-family modules
- full native launcher metadata and a unique Invariant application ID
- per-user Windows EXE installer with uninstall registration and shortcuts
- in-place installer updates that preserve the Gecko user profile
- Connect-owned signed update architecture with no resident updater process
- stable-channel settings UI, staged Windows updates, and active-session warning
- independently signed declarative platform-compatibility data

Not yet implemented:

- manual tab suspension/resume
- automatic suspension
- platform management/edit/delete UI
- controlled external authentication flow
- benchmark collection
- production update endpoint, offline production signing key, and Authenticode certificate

## Build And Run

From this directory, after the Gecko bootstrap and Invariant source overlay are complete:

```powershell
.\build-windows.ps1
```

Run:

```powershell
.\run.ps1
```

For normal Windows double-click testing, use:

```text
run.cmd
```

Verify the live engine:

```powershell
.\test-windows.ps1
```

Build the Windows installer:

```powershell
.\publish-windows.ps1
```

The output is `dist\windows-installer\Invariant-LLM-Connect-Setup.exe`. After
installing it, verify the installed runtime with:

```powershell
.\test-windows.ps1 -Installed
```

Both test modes fail unless `xul.dll` is loaded or if WebView2, Edge, Chromium,
Chrome ELF, or CEF modules are present.

Run the offline updater and manifest security tests with `npm test`. Update
architecture, signing, mock-server, and release details are in
[docs/UPDATES.md](docs/UPDATES.md).