OpenSquilla: a token-efficient microkernel AI agent with an on-device model router

What OpenSquilla actually solves, and for whom

Most agent frameworks spend the same amount of model budget on a trivial lookup as on a multi-step refactor. OpenSquilla's pitch is narrower than "another agent runtime": a local model router decides, per turn, which model is the cheapest one that can still handle the request. The README frames this as "same budget, more capability, better results" and describes SquillaRouter as an on-device router shipped with the default install profile. The audience is therefore people who already pay per token and notice it: developers running an agent from a terminal, and teams that want the same behaviour in a Web UI or a chat channel without maintaining three code paths. The repository describes a microkernel design, so the agent core stays small and capabilities arrive as pluggable pieces. That is a deliberate constraint, not a feature list. It means the interesting decisions live in the router and the provider layer, and the rest of the system is plumbing around one shared turn loop.

One turn loop behind CLI, Web UI and chat channels

The architecture claim in the README is that every entry point runs through the same turn loop, so tool dispatch, retries and decision logging behave identically everywhere. That is the part worth checking when you evaluate it, because it is the difference between three products and one product with three front doors. A pluggable provider layer sits underneath: the README lists TokenRhythm, OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini and Qwen/DashScope among 20+ providers, and states that switching between them needs no change to your code or the config schema. Around the loop sit persistent memory, a layered sandbox, built-in web search and on-device embeddings. The dependencies in pyproject.toml back this up in concrete terms: sqlite-vec for vector storage, aiosqlite and SQLAlchemy for persistence, yoyo-migrations for schema changes, starlette and uvicorn for the HTTP surface, and python-telegram-bot, lark-oapi, dingtalk-stream and qq-botpy for the chat channels. Web search defaults to DuckDuckGo through duckduckgo-search, with Brave selected automatically when a key is present, per .env.example. That is a coherent stack rather than a wrapper around one vendor SDK, and it is the strongest argument for the microkernel framing.

Installing OpenSquilla and a first real run

The README splits installation into four paths and is explicit about which ones need a toolchain. Desktop installers and the Quick terminal install give you a prebuilt release and need no Git. Install from source and Develop from source build from a Git checkout with Git LFS, and building the Web UI from source needs Node.js 22.12+. Release wheels and desktop installers already contain the Vue control console, so their users do not need Node.js or npm at all.

For terminal use, the documented command installs the release wheel as a uv tool. The README notes that `uv` is installed if missing on this path.

uv tool install opensquilla

On Windows and macOS this path does not install the native runtime SquillaRouter needs. The README says the from-source PowerShell installer handles the Visual C++ runtime via `winget`, but the `uv tool install` path does not. On macOS, if startup logs `Library not loaded: @rpath/libomp.dylib`, the documented fix is Homebrew:

brew install libomp

After restarting the gateway, SquillaRouter should come up. If it does not, OpenSquilla keeps running with direct single-model routing, which is the fallback rather than an error.

Configuration starts from the example environment file. Copy it and fill in the provider key; OpenRouter is marked required, and Brave is optional but auto-selected over DuckDuckGo once set.

cp .env.example .env

# Required — LLM provider (OpenRouter)
OPENROUTER_API_KEY=
# Optional — Brave Search API
BRAVE_SEARCH_API_KEY=

Docker is the other supported route. The compose file publishes the gateway on host loopback only by default, and the comment there is worth reading before you change it: reaching the Web UI from another device requires publishing on all interfaces and enabling token auth first. The Dockerfile states that the in-container bind is `0.0.0.0` by design and that the `gateway.bind.public` warning fires on every container start as an intended signal, not a misconfiguration.

Where OpenSquilla gets in your way

The install story has a real seam. On Windows and macOS, the recommended terminal path can leave SquillaRouter without its native runtime, and the project's response is to keep running with direct single-model routing. That is a graceful degradation, but it is also silent: the token savings that motivated the install are gone, and nothing in the README suggests a prominent warning beyond the specific log lines it names. If your reason for choosing OpenSquilla is cost, verify the router is actually active rather than assuming it.

The second constraint is maturity. pyproject.toml carries the classifier "Development Status :: 3 - Alpha" at version 0.5.4, while the README calls 0.5.4 the current stable release. Those two statements are not contradictory, but they set expectations differently, and anyone building on internal APIs should read the classifier first.

The third is the desktop profile split. The README says a terminal installation's `~/.opensquilla` is a separate profile from the Desktop one, and transferring it is a manual step from Settings. Windows upgrades from RC3 to RC4 or later have a sharper edge: the README instructs running the new installer over the existing installation and explicitly warns not to uninstall RC3 first, because its uninstaller may remove Desktop user data. Backing up `%APPDATA%\OpenSquilla` is the documented precaution. That is a genuine operational hazard, not a footnote.

How OpenSquilla differs from a general agent framework

LangChain and its graph-oriented successor are the obvious comparison, and the difference is where each puts intelligence. A general framework gives you abstractions for chains, tools and memory, then leaves model selection to you: you pick a model per chain, or you write your own routing logic. OpenSquilla inverts that. Routing is the built-in component, and the README points to a technical report titled "Agentic Routing: The Harness-Native Data Flywheel" describing a harness-native router that turns everyday agent traffic into a self-improving data flywheel, plus a claim that multi-model ensemble routing surpasses Fable 5. Whether that claim holds for your workload is something the report argues and you would have to test; the README does not provide numbers you can transfer to your own traffic. The practical difference is that OpenSquilla expects to own the turn loop and the routing decision, while a framework like LangChain expects you to compose those yourself. If you already have routing logic you trust, OpenSquilla's main value proposition is the part you would be replacing.

Licence, maintenance and the upgrade bill

OpenSquilla is Apache-2.0, declared both in pyproject.toml and in the repository's LICENSE file, with a THIRD_PARTY_NOTICES.md alongside it. Apache-2.0 is permissive and includes a patent grant, which matters for a project that bundles native runtime components such as ONNX and LightGBM. The repository also carries a PRIVACY.md and a code signing policy under docs, which is more than many projects at this stage provide. This is not legal advice; if you redistribute the desktop installers or the container image, read THIRD_PARTY_NOTICES.md yourself.

On maintenance, the last push was on 2026-08-25, the same day v0.5.4 was released, and the repository is not archived. Releases have been roughly two weeks apart through the 0.5.x line: v0.5.2 on 2026-07-29, v0.5.3 on 2026-08-13, v0.5.4 on 2026-08-25. Upgrade cost is where the project asks something of you. Desktop users on macOS reinstall by dragging the app from the DMG into Applications and ejecting it; the existing Desktop profile is reused. Windows users upgrading from RC3 must run the new installer over the old one and back up `%APPDATA%\OpenSquilla` first. Terminal users on a separate profile do not get the Desktop profile automatically. The project ships a MIGRATION.md and a migrations/ directory, which suggests schema changes are handled deliberately, but the README does not document rollback for a failed upgrade.

Editorial conclusion

Adopt OpenSquilla if you want one agent loop behind a CLI, a Web UI and chat channels, and you are willing to run the recommended install profile so SquillaRouter is present. Skip it if you need a stable API surface: pyproject.toml still classifies the project as Alpha. Before committing, run the Quick terminal install on your target OS and confirm the gateway starts with the router active, because the Windows and macOS missing-runtime cases degrade to single-model routing instead of failing loudly.

Frequently asked questions

Official sources

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