OpenSquilla: one turn loop, one router, four install paths

One turn loop behind the Web UI, CLI, and chat channels

The Web UI, the CLI, and the chat channels do not run separate agents. All three enter the same turn loop, so tool dispatch, retry behavior, and decision logging stay identical no matter where a request came from. That shared loop is what makes persistent memory, a layered sandbox, built-in web search, and on-device embeddings parts of one runtime instead of four add-ons you wire up separately. The provider layer is pluggable in the same spirit: it speaks to TokenRhythm, OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini, and Qwen/DashScope, plus 20+ other providers, with no change to your code or config schema. The practical payoff is that a turn which misbehaves leaves the same trail whichever surface sent it. Nothing here is a second implementation you have to keep in sync.

SquillaRouter and the two native libraries that gate it

The default recommended profile installs SquillaRouter, the on-device model router, together with its model assets. That router is the piece that sends each turn to the cheapest model able to handle it. Two switches change that picture. Setting OPENSQUILLA_INSTALL_PROFILE=core leaves those dependencies out entirely, and the `--router disabled` onboarding flag installs them but keeps the router off at runtime. Then there are the native runtimes. On Windows, the bundled ONNX runtime needs the Visual C++ runtime; the from-source PowerShell installer adds it through winget, but the quick terminal install does not. On macOS terminal installs the LightGBM runtime may also need the system OpenMP library; the desktop app bundles the runtime it needs:

brew install libomp

If startup logs `Library not loaded: @rpath/libomp.dylib`, run that command and restart the gateway. A `DLL load failed` line on Windows is the same class of problem. In both cases OpenSquilla does not stop, and that is the trap: it keeps running with direct single-model routing, so your install succeeds and the startup log line is the only sign that the cheapest-model path is out of play.

Two profile directories and the Windows uninstall trap

Desktop and terminal installs keep their state in different places. The desktop app stores its profile in the platform application-data directory and reuses it across upgrades. A terminal installation writes to `~/.opensquilla`, which is a separate profile, so moving between the two means transferring it explicitly from Settings. On macOS the upgrade is mechanical: quit the running app, drag it from the DMG into Applications, eject the DMG, then open the Applications copy. Windows has a real hazard. Moving from RC3 to RC4 or later means running the new installer directly over the existing installation, because the RC3 uninstaller may remove Desktop user data if you uninstall first. Back up `%APPDATA%\OpenSquilla` before that upgrade. RC4 and later installers preserve profile data during a normal uninstall. Wheel installs use versioned filenames because the installers validate the version embedded in the wheel.

Proxy flags that keep outbound traffic off your shell environment

The example environment file turns proxy inheritance off on purpose and gives you four switches to change that. OPENSQUILLA_GATEWAY_SEARCH_PROXY exists for web_search when the Brave or DuckDuckGo endpoints are not reachable directly, and OPENSQUILLA_GATEWAY_SEARCH_USE_ENV_PROXY defaults to false rather than reading HTTP_PROXY and HTTPS_PROXY. OPENSQUILLA_TRUST_ENV covers outbound clients for channels, providers, web_fetch, and http_request, with a comment warning that a stray proxy in a parent shell must not silently reroute agent traffic; it wants to be set to 1 on WSL2, corporate, or censored networks. The fourth, OPENSQUILLA_WEB_FETCH_TRUST_PROXY_DNS, requires TRUST_ENV and stays off because turning it on delegates final destination access control to the proxy and gives up the DNS pinning web_fetch keeps by default. Read the consequence carefully: on a network where those search endpoints are blocked, web search fails until you configure one of these yourself.

The container binds 0.0.0.0 and warns you on every start

The image is built in two stages: a Node 22.12.0 bookworm slim builder that produces the Web UI bundle, and a python:3.13-slim-bookworm runtime that copies only the staged artifact, never Node.js or node_modules. Inside the container the gateway binds to 0.0.0.0 because Docker port publishing needs a wildcard bind, so the defense is placed on the host side instead:

docker run -p 127.0.0.1:18791:18791

Because the in-container bind is wildcard by design, a `gateway.bind.public` warning fires on every container start. That is the intended signal, not a malfunction. compose.yaml publishes on host loopback only and keeps config, state, logs, and workspace in a named volume mounted at `/var/lib/opensquilla`. If you want the Web UI on a NAS or a home server, publishing on all interfaces requires token auth first, with OPENSQUILLA_AUTH_MODE set to token and an OPENSQUILLA_AUTH_TOKEN generated by `openssl rand -hex 32`. Skip the local build by pointing compose at the published image:

OPENSQUILLA_GATEWAY_IMAGE=ghcr.io/tokenrhythm/opensquilla:latest docker compose up -d

Pinned ranges that stall a dependency upgrade

pyproject.toml requires Python 3.12 or newer and pins several dependencies for reasons written into its own comments. Typer is held at `>=0.27.2,<0.28` because the compact help renderer adapts Typer's private Rich panel hook, and the file asks you to review that contract before moving to another Typer minor series. The chat side carries a second bound worth reading: `websockets>=16.0,<18`, because Lark 1.5 handshake errors are adapted per client and exercised against websockets 16 and 17, and newer Lark SDKs require websockets below 16. The websockets and Lark SDK bounds have to be reviewed together, which means a Typer or Lark bump can block the whole upgrade until somebody reviews the adapter. The HTTP and parsing floors are labeled as security floors: aiohttp `>=3.14.4`, multidict `>=6.9.1`, idna `>=3.19`, urllib3 `>=2.7.0` and brotli `>=1.2.1`, with certifi set to `>=2026.10.19`. Meanwhile the classifier still reads Development Status :: 3 - Alpha.

The efficiency numbers sit in papers, not in a harness

The token-efficiency claim is documented in technical reports. A technical report titled Agentic Routing: The Harness-Native Data Flywheel went up on arXiv as 2607.11399 on 2026-07-14, describing how the harness-native router turns everyday agent traffic into a self-improving data flywheel and how multi-model ensemble routing surpasses Fable 5. The English version landed on aiXiv as aixiv.260822.000001 on 2026-08-22, with the Chinese version on ChinaXiv as 202608.00176. The provider layer is the counterweight: twenty-plus providers behind one schema means you can hold a model fixed and change only the router, or hold the router fixed and change the model. That is a sound way to run your own comparison.

Desktop installers, wheel names, and one shared release

Release install commands pull published GitHub release assets, while wheel installs carry a versioned filename because the installers validate the version embedded in the wheel name. From source and develop from source both need a Git checkout with Git LFS, plus Node.js 22.12+ and npm, and they build the Vue control console themselves; release wheels and desktop installers already carry that console, so their users never need Node at all. For 0.5.7 the packaged assets are `OpenSquilla-0.5.7-mac-arm64.dmg` and `OpenSquilla-0.5.7-win-x64.exe`. Separate OSS direct-download aliases point at Mac and Windows builds for faster Mainland China transfers, and those fixed links advance only after a newer eligible release passes mirror verification, so a specific release needs the versioned GitHub links instead. The cadence behind these is quick: v0.5.5 shipped on 2026-09-23, v0.5.6 on 2026-09-30, and v0.5.7 on 2026-10-23, with the last push landing on 2026-11-02.

Editorial conclusion

OpenSquilla suits a team that wants one agent loop shared by a terminal, a browser, and chat channels, and that reads the platform notes before the first run. It does not suit a team that needs a non-alpha release, a dependency set it can widen freely, or a router runtime someone else installs. Verify two things before trusting either claim: which profile directory your install actually writes to, and whether SquillaRouter loaded or the gateway fell back to direct single-model routing.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes