OpenSquilla — Token-Efficient AI Agent

Same budget, more capability, better results.
A microkernel AI agent for your CLI, Web UI, and chat channels.

English · 中文 · 日本語 · Français · Deutsch · Español

---

News

• 📢 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.0 Preview 4 is the current preview release.

For task-oriented product documentation, start with the
[OpenSquilla Product Guide](README.product.md) or the
[documentation index](docs/README.md).

---

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).

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.0 Preview 4 desktop use, prefer the packaged desktop installers from
the GitHub Release: OpenSquilla-0.5.0-rc4-mac-arm64.dmg on macOS and
OpenSquilla-0.5.0-rc4-win-x64.exe on Windows.

| Path | Audience | When to use |
| --- | --- | --- |
| [Desktop installers](#desktop-installers) (recommended desktop) | macOS and Windows users | Packaged desktop app |
| [Quick terminal install](#quick-terminal-install) (recommended) | End users on any OS | Release wheel from a terminal |
| [Install from source](#install-from-source) | Users tracking main | Run from a checkout, not edit it |
| [Develop from source](#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 |
| 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](#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 ·
uv.

Desktop installers

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

• macOS Apple Silicon:
• Windows x64:

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

• macOS Apple Silicon:
• Windows x64:

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](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](#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](#install-from-source).

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

Linux / macOS:

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

Windows PowerShell:

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.

sh
uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.5.0rc4/opensquilla-0.5.0rc4-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](#troubleshooting) if
the router runtime reports a native-library load error.

3. Configure and run.

sh
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.0rc4/opensquilla-0.5.0rc4-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](#develop-from-source) instead if you intend to
modify the code.

1. Clone with LFS assets

sh
   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

sh
   bash scripts/install_source.sh

Windows PowerShell

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,
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](#troubleshooting) for details.

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:

- matrix — Matrix channel (pulls in matrix-nio)
- matrix-e2e — Matrix channel with end-to-end encryption (requires
libolm)
- document-extras — PDF generation via WeasyPrint

sh
   OPENSQUILLA_INSTALL_EXTRAS=matrix bash scripts/install_source.sh        # macOS / Linux

powershell
   powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1 -Extras matrix   # Windows

4. Configure and run — see [Configuration](#configuration).

Install from source — terminal prerequisites and installer options

Install prerequisites (Git, Git LFS, uv) from a terminal

Windows PowerShell:

powershell
winget install --id Git.Git -e
winget install --id GitHub.GitLFS -e
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
git lfs install

macOS (Homebrew):

sh
brew install git git-lfs uv
git lfs install

Debian / Ubuntu:

sh
sudo apt update && sudo apt install -y git git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

On Fedora use sudo dnf install -y git git-lfs; on Arch use
sudo pacman -S --needed git git-lfs; then install uv with the
curl command above. PATH changes from these installers apply to new
terminal sessions.

Installer environment variables and PATH checks

sh
OPENSQUILLA_INSTALL_PROFILE=core   bash scripts/install_source.sh   # minimal runtime, no SquillaRouter
OPENSQUILLA_INSTALL_DRY_RUN=1      bash scripts/install_source.sh   # print the plan only

Verify which opensquilla your shell runs with command -v
opensquilla (macOS/Linux) or where.exe opensquilla (Windows). If it
is not on PATH, run uv tool update-shell. After reinstalling from a
local checkout, restart the gateway so it loads the updated package.

Develop from source

Use this path when you are working on OpenSquilla's source code:
making changes, running tests, or debugging behavior against this
checkout. It is not the normal install path. Unlike
[Install from source](#install-from-source), this path requires uv:
uv sync creates a repository-local .venv, and uv run executes
commands against the files in this checkout.

sh
uv sync --extra recommended --extra dev
uv run opensquilla --help

The recommended extra includes SquillaRouter for development too;
the dev extra installs the test, lint, and typecheck tools. Install
additional extras into the same environment you run:

sh
uv sync --extra recommended --extra dev --extra matrix
uv run opensquilla channels status matrix --json

In this mode, prefix every opensquilla command in
[Configuration](#configuration) with uv run. Do not debug a
development checkout through a user-local opensquilla command — that
command runs in a different Python environment.

Uninstall

Remove OpenSquilla with opensquilla uninstall. It keeps your data by default
and removes only the program:

sh
opensquilla uninstall --dry-run   # preview what would be removed and kept
opensquilla uninstall             # remove the program, keep your data

To delete data too, opt in explicitly:

sh
opensquilla uninstall --purge-state    # sessions, logs, cache, scheduler, memory
opensquilla uninstall --purge-config   # config.toml and secrets (.env)
opensquilla uninstall --purge-all      # everything (asks you to type a confirmation)

The running gateway is drained and stopped first, deletion stays inside the
OpenSquilla home, and Docker/desktop installs get guided removal steps instead.
Desktop or OS app removal remains platform-specific; the CLI guidance does not
remove a desktop app bundle. See [docs/cli.md](docs/cli.md#uninstall) for the
full reference.

---

Installation Privacy

OpenSquilla uses anonymous installation telemetry to estimate install counts,
version adoption, and runtime compatibility. Data is sent on first gateway
startup and once per OpenSquilla version. OpenSquilla may also make passive
update checks, including automatic desktop update checks at startup and, while
the app remains open, at most once per day. Uploads use a short timeout and
never block startup.

See [PRIVACY.md](PRIVACY.md) for the full privacy policy covering local data,
provider requests, network observability, logs, release downloads, and deletion.

What is sent:

• schema version
• locally generated stable install_id digest
• OpenSquilla version
• event type (install or version_seen)
• install method (pip, source, docker, desktop, or unknown)
• operating system, OS version, CPU architecture, and Python major/minor

version

• first-seen and sent timestamps
• CI/test-environment marker (ci_environment)

The install_id is a local one-way SHA-256 digest derived from usable MAC addresses, then local IP addresses when no MAC is available, with a random persisted fallback. Raw MAC/IP values are not uploaded.

What is not sent: usernames, hostnames, paths, API keys, provider config,
chat/session/memory/agent content, file names, or file contents. Source IP may
be visible to HTTP servers at the transport layer, but is not part of the
payload.

To disable non-user-initiated network observability before startup:

sh
OPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true

or set:

toml
[privacy]
disable_network_observability = true

That unified switch covers automatic install telemetry, passive update checks,
and automat

…

Collapse