OpenSquilla — Token-Efficient AI Agent

<p align="center"> <img src="assets/opensquilla-long-logo.png" alt="OpenSquilla logo" width="500"> </p> <p align="center"> <b>Same budget, more capability, better results.</b><br> A microkernel AI agent for your CLI, Web UI, and chat channels. </p> <p align="center"> <a href="https://github.com/opensquilla/opensquilla/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/opensquilla/opensquilla/ci.yml?style=for-the-badge" alt="CI"></a> <a href="https://opensquilla.ai/"><img src="https://img.shields.io/badge/website-opensquilla.ai-blue?style=for-the-badge" alt="Website"></a> <a href="https://github.com/opensquilla/opensquilla/releases"><img src="https://img.shields.io/github/v/release/opensquilla/opensquilla?include_prereleases&style=for-the-badge" alt="GitHub release"></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue?style=for-the-badge" alt="Python 3.12+"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=for-the-badge" alt="Apache 2.0 License"></a> </p> <p align="center"> <b>English</b> · <a href="README.zh-Hans.md">中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.fr.md">Français</a> · <a href="README.de.md">Deutsch</a> · <a href="README.es.md">Español</a> </p>

---

News

• 📢 2026-08-22 — The English version of our technical report is now on aiXiv: aixiv.260822.000001, and the Chinese version is on ChinaXiv: 202608.00176. See Citation for how to cite OpenSquilla.

• 📢 2026-08-21 — PDF versions of our technical report are now available in this repo: English · 中文.

• 📢 2026-07-14 — Our technical report Agentic Routing: The Harness-Native Data Flywheel is now on arXiv. It shows how the harness-native router turns everyday agent traffic into a self-improving data flywheel, and how multi-model ensemble routing surpasses Fable 5.

---

Overview

OpenSquilla is a token-efficient, microkernel AI agent. A local model router sends each turn to the cheapest model that can handle it, while persistent memory, a layered sandbox, built-in web search, and on-device embeddings round out a single shared turn loop.

Every entry point — Web UI, CLI, and chat channels — runs through that same loop, so tool dispatch, retries, and decision logging behave identically everywhere. A pluggable provider layer speaks to TokenRhythm, OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini, Qwen/DashScope, and 20+ other LLM providers with no change to your code or config schema.

OpenSquilla 0.5.4 is the current stable release.

For task-oriented product documentation, start with the OpenSquilla Product Guide or the documentation index.

---

Installation

OpenSquilla runs on Windows, macOS, and Linux. Pick the path that matches your use case.

Desktop installers and Quick terminal install give you a prebuilt release — no Git required. The other two — Install from source and Develop from source — build from a Git checkout (git clone + Git LFS), including the Vue control console. Release wheels and Desktop installers already contain that console, so their users do not need Node.js or npm.

Release install commands use published GitHub release assets. Python wheel installs use versioned wheel filenames because installers validate the version embedded in the wheel filename.

For 0.5.4 desktop use, prefer the packaged desktop installers from the GitHub Release: OpenSquilla-0.5.4-mac-arm64.dmg on macOS and OpenSquilla-0.5.4-win-x64.exe on Windows.

| Path | Audience | When to use | | --- | --- | --- | | Desktop installers (recommended desktop) | macOS and Windows users | Packaged desktop app | | Quick terminal install (recommended) | End users on any OS | Release wheel from a terminal | | Install from source | Users tracking main | Run from a checkout, not edit it | | Develop from source | Contributors | Edit, test, or debug the source |

Prerequisites

| Requirement | Quick terminal install | Install from source | Develop from source | | --- | :---: | :---: | :---: | | Python 3.12+ | via uv | via uv or system | via uv | | Git + Git LFS | — | required | required | | Node.js 22.12+ + npm | — | required to build the Web UI | required for Web UI and wheels | | uv | installed if missing | recommended | required |

The default recommended profile installs SquillaRouter — OpenSquilla's on-device model router — and its model assets; OPENSQUILLA_INSTALL_PROFILE=core omits those dependencies. The separate --router disabled onboarding flag keeps the dependencies installed but turns the router off at runtime.

On Windows, SquillaRouter's bundled ONNX runtime also needs the Visual C++ runtime. The from-source PowerShell installer installs it automatically via winget; the Quick terminal install (uv tool install) path does not — if startup logs a DLL load failed error, install it manually (see Troubleshooting). OpenSquilla keeps running with direct single-model routing until it is installed.

On macOS terminal installs, SquillaRouter's LightGBM runtime may also need the system OpenMP library. The desktop app bundles the runtime it needs, but Quick terminal install does not install Homebrew/system libraries. If startup logs Library not loaded: @rpath/libomp.dylib, run brew install libomp, then restart the gateway. OpenSquilla keeps running with direct single-model routing until it is installed.

Install links: Git · Git LFS · Node.js · uv.

Desktop installers

The 0.5.4 desktop installers package the Vue control console and gateway runtime in an Electron shell.

• macOS Apple Silicon: https://github.com/opensquilla/opensquilla/releases/download/v0.5.4/OpenSquilla-0.5.4-mac-arm64.dmg
• Windows x64: https://github.com/opensquilla/opensquilla/releases/download/v0.5.4/OpenSquilla-0.5.4-win-x64.exe

For faster Mainland China downloads, use the OSS direct-download aliases:

• macOS Apple Silicon: https://opensquilla-releases.oss-cn-beijing.aliyuncs.com/releases/latest/OpenSquilla-mac-arm64.dmg
• Windows x64: https://opensquilla-releases.oss-cn-beijing.aliyuncs.com/releases/latest/OpenSquilla-win-x64.exe

These fixed links advance only after a newer eligible release passes mirror verification. Use the versioned GitHub Release links above when you need a specific release.

Quit any running OpenSquilla desktop app before upgrading. On macOS, drag the app from the DMG into Applications for installation or updates, eject the DMG, then open the Applications copy. The existing Desktop profile in the platform application-data directory is reused. A terminal installation's ~/.opensquilla is a separate profile; transfer it explicitly from Settings only if needed.

When upgrading the Windows Desktop from RC3 to RC4 or later, run the new installer directly over the existing installation. Do not uninstall RC3 first: its uninstaller may remove Desktop user data. Back up %APPDATA%\OpenSquilla before upgrading. RC4 and later installers preserve profile data during a normal uninstall.

Code signing policy: docs/code-signing-policy.md.

[!NOTE] Windows builds are currently unsigned. If SmartScreen appears, choose More info → Run anyway. If Smart App Control or enterprise policy blocks the unsigned app, use Quick terminal install instead.

Quick terminal install

The recommended path on Windows, macOS, and Linux. uv installs OpenSquilla into its own isolated environment and manages its own Python — no system Python required. This path installs published releases only; for main, development branches, or local checkouts use Install from source.

1. Install uv — skip if uv --version already works.

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh
. "$HOME/.local/bin/env"

Windows PowerShell:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path

2. Install OpenSquilla — the same command on every platform.

uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-py3-none-any.whl"

This installs the OpenSquilla wheel from the release URL, then lets uv download the dependencies declared by the selected extras. The default recommended extra includes SquillaRouter runtime dependencies such as ONNX Runtime, LightGBM, NumPy, and tokenizers, so a first install needs network access unless those wheels are already cached. uv does not install system native runtimes such as macOS libomp or the Windows Visual C++ Redistributable; see Troubleshooting if the router runtime reports a native-library load error.

3. Configure and run.

opensquilla onboard
opensquilla gateway run

[!NOTE] If opensquilla is not found right after a fresh uv install, open a new terminal, or re-run the PATH line from step 1.

For a fully pinned install, use the versioned wheel URL: https://github.com/opensquilla/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-py3-none-any.whl.

Install from source

Use this path to run OpenSquilla from a checkout without editing it. The clone is only the package source for the installer; after install, use the opensquilla command — do not run uv run. Choose Develop from source instead if you intend to modify the code.

1. Clone with LFS assets

   git lfs install
   git clone https://github.com/opensquilla/opensquilla.git
   cd opensquilla
   git lfs pull --include="src/opensquilla/squilla_router/models/**"
   

2. Run the installer

   macOS / Linux

   bash scripts/install_source.sh
   

   Windows PowerShell

   powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1
   

   The script installs .[recommended] (SquillaRouter + memory + local models) into a dedicated user environment via uv tool install. Before the Python install, it runs npm ci and npm run build in opensquilla-webui. Every source reinstall recreates the locked node_modules tree and rebuilds the console; the first run normally has the largest dependency download, while a warm npm cache reduces later network use but not all build time or disk writes. It then installs the built console with the Python package, falling back to python -m pip install --user when uv is unavailable. If opensquilla is not on PATH after install (common on a fresh host where ~/.local/bin is not yet on PATH), run uv tool update-shell and open a new terminal; see Troubleshooting for details.

   Direct pip install ., uv tool install ., and VCS URL installs are low-level source-build paths, not substitutes for this installer. A local checkout works only after its Web UI has been built; a VCS URL checkout has no generated artifact and is intentionally rejected. Use this source installer or an official release wheel instead.

3. (optional) Install advanced extras. Most channels — Feishu, Telegram, DingTalk, QQ, WeCom, Slack, and Discord — work from the base install. The opt-in extras are