# 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-08-22** — The English version of our technical report is now on aiXiv: [aixiv.260822.000001](https://aixiv.science/abs/aixiv.260822.000001), and the Chinese version is on ChinaXiv: [202608.00176](https://chinaxiv.org/abs/202608.00176). See [Citation](#citation) for how to cite OpenSquilla.
- 📢 **2026-07-14** — Our technical report **[Agentic Routing: The Harness-Native Data Flywheel](https://arxiv.org/abs/2607.11399)** 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.7 is the current stable release.
Downloads: [OpenSquilla 0.5.7](https://github.com/TokenRhythm/opensquilla/releases/tag/v0.5.7).
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),
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.7 desktop use, prefer the packaged desktop installers from
the GitHub Release: `OpenSquilla-0.5.7-mac-arm64.dmg` on macOS and
`OpenSquilla-0.5.7-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 |
| 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](#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](https://git-scm.com/downloads) ·
[Git LFS](https://git-lfs.com/) ·
[Node.js](https://nodejs.org/en/download) ·
[uv](https://docs.astral.sh/uv/getting-started/installation/).
### Desktop installers
The 0.5.7 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]
> The 0.5.7 Windows installer is Authenticode signed as Beijing TokenRhythm
> Technologies Co., Ltd. The published v0.5.4 Windows installer remains unsigned.
> SmartScreen reputation can still take time
> to build for a new publisher or application. If enterprise policy blocks the
> Desktop 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/TokenRhythm/opensquilla/releases/download/v0.5.7/opensquilla-0.5.7-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/TokenRhythm/opensquilla/releases/download/v0.5.7/opensquilla-0.5.7-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/TokenRhythm/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`. 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](#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:
- `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, Node.js 22.12+ with npm, uv) from a terminal**
Windows PowerShell:
```powershell
winget install --id Git.Git -e
winget install --id GitHub.GitLFS -e
winget install --id OpenJS.NodeJS.LTS -e
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
git lfs install
```
macOS (Homebrew):
```sh
brew install git git-lfs node uv
git lfs install
```
Debian / Ubuntu:
```sh
sudo apt update && sudo apt install -y git git-lfs curl
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
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`; install Node.js 22.12+ and npm from
your distribution or nodejs.org, 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
cd opensquilla-webui
npm ci
npm run build
cd ..
uv sync --extra recommended --extra dev
uv run opensquilla --help
```
Run `npm run build` again after changing Web UI sources. Standard wheel builds
fail closed when the generated console is missing or stale; editable `uv sync`
installs remain available for backend-only work.
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.
---
## Usage Statistics and Privacy
OpenSquilla uses the existing **Network reporting** switch for V1 statistics and
both V2 statistics streams. Reporting is enabled by default and can be turned off
in Privacy settings, without separate onboarding choices or consent popups:
- **Reliability diagnostics** records bounded operation results for app and
Gateway startup, crashes, turns, tools, file parsing, updates, and session
performance.
- **Product and growth analytics** records client launches, product activity,
and one-time acquisition, onboarding,
app-readiness, registration, and first-successful-turn milestones. Existing
installations do not become new-user cohorts just by enabling reporting.
The streams retain separate session/journey identifiers, durable queues,
upload endpoints, and retention policies. Reliability events
go to `/v1/reliability/events`; growth events go to `/v1/growth/events`.
Retries reuse `event_id` for server-side deduplication, and growth events are
not sampled.
Application events also carry a one-way, application-specific `device_id`
derived locally from the OS machine identifier when available. Daily/monthly
activity and feature device counts deduplicate this token across profiles and
client surfaces. Legacy events without it are excluded from device counts;
operation totals and success rates still count actual operations.
V2 statistics never include prompts, responses, file names, file paths, file
contents, tool arguments, task parameters, provider configuration, raw account
IDs, order data, MAC addresses, IP addresses, or raw OS machine identifiers. Complete
crash stacks stay local unless the user explicitly prepares and shares a
support bundle.
V1 installation/version reporting at `/v1/install` and daily conversation/token
totals at `/v1/usage` run alongside V2 after Gateway readiness. Only completed
UTC days are uploaded; pending days retry hourly. Existing installation state
is retained. Daily event IDs use a persistent random identity per aggregate
database to separate profiles while keeping retries stable. V1 retains its pseudonymous installation
ID derived locally from MAC/IP data, with a persisted random fallback; raw MAC/IP
values are not uploaded. The `X-OpenSquilla-Install-Id` provider header remains
retired, and V2 keeps its independent identities.
To force all non-user-initiated network observability off before startup:
```sh
OPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true
```
or set:
```toml
[privacy]
disable_network_observability = true
```
This is a hard veto over V1 and both V2 statistics streams, passive update checks, and
automatic desktop update checks. Disabling Network reporting pauses pending uploads and
stops collection without deleting local statistics state. Previously saved
per-scope declines are migrated to the unified switch being off; users can
then change that one setting. CI, test, and `DO_NOT_TRACK` environments
also fail closed for statistics uploads. Other user-initiated actions may still contact
configured providers, search services, channels, or release hosts.
Explicit update-availability checks remain disabled while the unified or
legacy update opt-out controls are active.
Legacy opt-out environment variables remain honored:
```sh
OPENSQUILLA_TELEMETRY_DISABLED=true
OPENSQUILLA_UPDATE_CHECK_DISABLED=true
```
The legacy statistics variable disables V1 and V2 reporting. The legacy update
variable also suppresses V1 uploads for compatibility, but does not disable V2.
See [`PRIVACY.md`](PRIVACY.md) for the complete data, reporting, deletion, update,
and external-producer rules.
---
## Configuration
### First-run setup
`opensquilla onboard` is the interactive first-run wizard. It writes
the active config file and keeps provider secrets in environment
variables when you pass `--api-key-env`. The router defaults to
`recommended` (SquillaRouter on supported providers); pass
`--router disabled` for direct single-model routing.
```sh
opensquilla onboard # full interactive wizard
opensquilla onboard --if-needed # idempotent: safe for scripts and re-installs
opensquilla onboard --minimal # provider only; skip channels and search
opensquilla onboard status # inspect every setup section without writing
```
In SSH, CI, or any environment without a TTY, use the non-interactive
form — keep the secret in the environment and pass its **name**, not
its value:
**Linux / macOS**
```sh
export OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
```
**Windows PowerShell**
```powershell
$env:OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
```
OpenRouter is only an example — substitute any supported provider and
its API-key variable.
Re-configure one section later without redoing the whole wizard (these
examples assume the relevant API key is already in the environment):
```sh
opensquilla configure provider --provider openai --model gpt-4o --api-key-env OPENAI_API_KEY
opensquilla configure router --router recommended
opensquilla configure search --search-provider duckduckgo
opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY
opensquilla configure channels
```
Sections: `provider`, `router`, `channels`, `search`,
`image-generation`, `memory-embedding`. The Web UI exposes the same
catalog and status model at `/control/setup`: Provider and Router are
the fast path, while Channels, Search, Image generation, and Memory
embedding sit in the Capability Center and can be configured later.
Empty channels are treated as an opt-out, not a failed setup.
**Config load order:** `OPENSQUILLA_GATEWAY_CONFIG_PATH` →
`./opensquilla.toml` → `~/.opensquilla/config.toml` → built-in
defaults. Environment values for individual secrets always win over
file values.
### Migrate from OpenClaw or Hermes Agent
If you already have state under `~/.openclaw` or `~/.hermes`, run a
dry run first to inspect the migration report, then apply it explicitly:
```sh
opensquilla migrate openclaw --json
opensquilla migrate openclaw --apply
opensquilla migrate hermes --json
opensquilla migrate hermes --apply
```
Use `opensquilla migrate --source openclaw,hermes --apply` to import
both default homes. Add `--migrate-secrets` only after reviewing the dry-run
report. See [`MIGRATION.md`](MIGRATION.md) for custom paths and conflict
handling.
### Run
```sh
opensquilla gateway run # foreground, 127.0.0.1:18791
opensquilla gateway start --json # background + health wait
opensquilla chat # interactive REPL
opensquilla agent -m "your prompt" # one-shot, automation-friendly
```
For subprocess progress, add `--event-stream-stderr`. The final result keeps
its existing stdout format, while stderr receives incrementally flushed,
privacy-bounded v1 JSONL events. Consumers must drain stderr continuously and
only treat objects with `"_event": true` as events because ordinary diagnostics
can share the stream. See [docs/cli.md](docs/cli.md#agent-progress-event-stream)
for the versioned schema and compatibility contract.
Parallel agent subprocesses must use separate profile homes and persistent
state roots. Set both variables for every child:
```sh
OPENSQUILLA_STATE_DIR=/tmp/agent-a \
OPENSQUILLA_GATEWAY_STATE_DIR=/tmp/agent-a/state \
opensquilla agent -m "task A" --json --event-stream-stderr &
OPENSQUILLA_STATE_DIR=/tmp/agent-b \
OPENSQUILLA_GATEWAY_STATE_DIR=/tmp/agent-b/state \
opensquilla agent -m "task B" --json --event-stream-stderr &
wait
```
On Windows, set both values in each child process environment. If an
orchestrator copies `config.toml` or `.env`, remove or rewrite every `state_dir`
or `OPENSQUILLA_GATEWAY_STATE_DIR` value as well. Explicitly shared session DB,
workspace, scratch, transcript, and usage paths remain shared by design.
> **Development-only OpenTUI terminal UI.** Release installs continue to use
> the Python-native chat. The richer full-screen frontend currently runs only
> from a [Develop from source](#develop-from-source) checkout; no companion host
> is published in release assets or installed by the release installer. From
> the checkout, install the pinned Bun dependencies once, then launch against
> that same source tree:
>
> ```sh
> bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package
> OPENSQUILLA_TUI_DEV_SOURCE_HOST=1 uv run opensquilla chat --ui tui
> ```
>
> Use `opensquilla chat --ui plain` to require the stable renderer. See
> [docs/tui.md](docs/tui.md) for terminal chat usage and
> [docs/features/tui-frontend.md](docs/features/tui-frontend.md) for backend
> details.
Open the Web UI at . The **Health**
view shows whether OpenSquilla is ready, what is not ready, and the
next recovery steps. From the CLI, run:
```sh
opensquilla doctor
opensquilla doctor --json
opensquilla doctor --config ./opensquilla.toml --json
```
`/health` and `/healthz` are lightweight liveness endpoints for process
checks. `opensquilla doctor` and the Web UI Health view are the readiness
surfaces for provider config, memory, logs, search, channels, sandbox
posture, router, image generation, and recovery guidance. Press
`Ctrl+C` to stop a foreground gateway.
Other command groups include `sessions`, `skills`, `memory`, `migrate`,
`cron`, `channels`, `providers`, `models`, and `cost`. Run
`opensquilla --help` or `opensquilla --help` for details.
Advanced configuration — verify a channel, public network binding, Docker
**Connect and verify a messaging channel**
Channel saves are config changes, not runtime-connectivity proof.
Restart the gateway after channel edits, then verify the live channel:
```sh
opensquilla gateway restart
opensquilla channels status --json
```
Treat a channel as connected only when the status payload reports
`enabled=true`, `configured=true`, and `connected=true`. Feishu
defaults to websocket mode, Telegram to polling, and Slack can use
Socket Mode — none of those modes needs a public URL. Feishu webhook
mode, Telegram webhook mode, Slack webhook mode, and WeCom require a
public, provider-reachable URL.
**Public network binding**
To reach the Web UI from another machine, bind the gateway to all
interfaces and use the host's public IP:
```sh
opensquilla gateway run --listen 0.0.0.0 --port 18791
```
Public access also requires the host firewall or cloud security group
to allow inbound TCP on that port. Do not expose the gateway with
`[auth] mode = "none"` — configure token auth before binding to
`0.0.0.0`.
**Docker**
Prebuilt multi-arch images (`amd64`/`arm64`) are published to
`ghcr.io/tokenrhythm/opensquilla` on release tags. The 0.5.7 workflow publishes
`v0.5.7` and advances `latest` after image verification —
[`docs/docker.md`](docs/docker.md) is the full container guide
(home servers and NAS, LAN exposure with token auth, upgrades):
```sh
OPENSQUILLA_GATEWAY_IMAGE=ghcr.io/tokenrhythm/opensquilla:latest docker compose up -d
```
Without `OPENSQUILLA_GATEWAY_IMAGE`, the compose path runs an
`opensquilla:local` image you build yourself. Build it from a source
checkout with the Git LFS router assets pulled
(see [Install from source](#install-from-source) for the clone and
`git lfs pull`):
```sh
docker build -t opensquilla:local .
```
`./start.sh` (or `start.ps1` on Windows) then runs `docker compose
up -d` and tails the gateway logs. Docker avoids a host Python
toolchain — not the local image build.
Provider tiers, sandbox tuning, image generation, and concurrency
settings live in `opensquilla.toml.example`.
---
## Release Notes
Per-version highlights live in [`CHANGELOG.md`](CHANGELOG.md) and
[`docs/releases/`](docs/releases/).
---
## Key Features
| Capability | What it does |
| --- | --- |
| **Token-efficient routing** | `SquillaRouter` — a local LightGBM + ONNX classifier in the `recommended` extra — scores each turn on length, language, code, keywords, and semantic embeddings, then routes it across four canonical tiers (C0–C3) to the cheapest capable model. Classification runs on-device; your prompt never leaves the machine to make that decision. |
| **Adaptive reasoning and prompts** | OpenSquilla requests extended reasoning only for turns the router scores as complex, and the system prompt scales with task complexity — lightweight for trivial turns, full instructions for complex ones. |
| **20+ LLM providers** | The provider registry targets 20+ LLM backends — TokenRhythm, OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini, DashScope/Qwen, Moonshot, Mistral, Groq, Zhipu, SiliconFlow, vLLM, LM Studio, and more, with primary-plus-fallback selection; first-run onboarding exposes the verified subset. |
| **On-demand skills and MCP** | 15 bundled skills (coding, GitHub, cron, pptx/docx/xlsx/pdf, summarization, tmux, weather, and more) load only when the task needs them. The current source includes MCP client and server support; see [MCP setup](docs/mcp-server.md#requirements) for SDK 2.x installation, then run `opensquilla mcp-server run` to expose session workflows to another MCP client. Skills can be authored, installed, and published from the CLI. |
| **Persistent local memory** | A curated `MEMORY.md` plus dated Markdown notes, searched with SQLite full-text keyword search and `sqlite-vec` semantic recall. Embeddings run on-device via bundled ONNX, or swap to OpenAI/Ollama. Optional exponential decay and opt-in "dream" consolidation are available. |
| **Layered security sandbox** | Three policy tiers (Standard / Strict / Locked) on a permission matrix. Bubblewrap isolates code execution on Linux; macOS runs commands through Seatbelt (`sandbox-exec`) with generated SBPL profiles; Windows uses the native `windows_default` backend after setup readiness checks. A denial ledger auto-pauses autonomous runs after repeated denials, rejected outputs are purged, and skill metadata and tool results are XML-escaped against prompt injection. |
| **Built-in tools** | File read/write/edit, shell and background processes, git, web search (DuckDuckGo, Bocha, Brave, IQS, Tavily, or Exa) and fetch behind an SSRF guard, spreadsheet/PPTX/PDF authoring, image generation, and text-to-speech. |
| **Unified gateway** | A Starlette ASGI server on `127.0.0.1:18791` with WebSocket RPC and an embedded control console (`/control/`). Web UI, CLI, and channels for Terminal, WebSocket, Slack, Telegram, Discord, Feishu, DingTalk, WeCom, Matrix, and QQ all share one `TurnRunner`. |
| **Durable sessions, subagents, and scheduling** | SQLite-backed session, transcript, and replay storage with per-agent workspaces. Agents spawn depth-bounded subagents, and a `SchedulerEngine` with an in-tree cron parser runs recurring jobs via `opensquilla cron`. |
| **Operator controls** | Human-in-the-loop approvals can pause sensitive tool calls for a decision; per-turn and per-session token and cost rollups (`opensquilla cost`) and diagnostics are available from the CLI and Web UI. |
---
## Benchmark Results
Results from our [technical report](https://aixiv.science/abs/aixiv.260822.000001). Scores come
from each benchmark's own grader, and costs use one provider price list across all frameworks.
An OpenSquilla row is either a forced single-model run — the full harness with routing disabled,
which isolates the harness contribution — or a multi-tier routing pool.
### PinchBench
25 tasks covering file operations, data processing, web retrieval, creative output, tool use,
and memory recall. Score is the cross-task mean; cost is the total for the run.
| Framework | Model (pool) | Score | Cost |
| --- | --- | ---: | ---: |
| OpenClaw | Opus-4.7 | 92.55 | $6.23 |
| OpenClaw | GLM-5.1 | 88.33 | $1.60 |
| OpenClaw | OpenRouter Auto | 88.10 | $3.01 |
| Hermes Agent | Opus-4.7 | 92.65 | $6.66 |
| OpenSquilla | Opus-4.7 | 93.85 | $4.84 |
| OpenSquilla | {DeepSeek-V4 Flash, DeepSeek-V4 Flash, GLM-5.1, Opus-4.7} | 92.51 | $0.69 |
| OpenSquilla | {MiniMax M2.5 (free), DeepSeek-V4 Flash, DeepSeek-V4 Flash, GLM-5.1} | 90.48 | $0.13 |
Forced single-model OpenSquilla takes the top score, +1.3 over OpenClaw's Opus-4.7 run at 22%
lower cost. The Opus-4.7-backstopped routing pool holds 99.96% of the 92.55 baseline score at
$0.69. The OpenRouter Auto row is a query-level routing baseline measured under a separate
protocol and is not directly comparable to the other rows.
### ClawMark
100 domain-specific business tasks across 13 domains, from clinical assistance and content
operations to legal, HR, insurance, and real estate. Cost is average billed cost per task.
| Framework | Model (pool) | Score | Cost per task |
| --- | --- | ---: | ---: |
| OpenClaw | GLM-5.1 | 71.2 | $0.62 |
| OpenSquilla | GLM-5.1 | 77.0 | $0.87 |
| OpenSquilla | {MiniMax M2.5 (free), DeepSeek-V4 Pro, GLM-5.1, GLM-5.1} | 70.6 | $0.39 |
The harness alone adds 5.8 points to the same model, at higher cost — this is the one benchmark
where the quality point sits above the baseline on price. The routing pool trades the gain back
for a 37% cheaper task, landing near the GLM-5.1 direct run.
### ClawSWEBench
350 multilingual SWE-bench-style repair tasks from 8 languages and 43 repositories, with the
task set, containers, prompts, turn limits, and timeouts all fixed. Cost is average billed cost
per task.
| Framework | Model (pool) | Resolve rate | Cost per task |
| --- | --- | ---: | ---: |
| OpenClaw | Opus-4.7 | 77.1% | $3.09 |
| OpenClaw | GLM-5.2 | 74.3% | $0.87 |
| OpenClaw | GLM-5.1 | 73.4% | $0.79 |
| OpenClaw | Qwen3.7-Max | 73.1% | $1.25 |
| OpenSquilla | GLM-5.2 | 79.4% | $0.95 |
| OpenSquilla | GLM-5.1 | 74.9% | $0.87 |
| OpenSquilla | {DeepSeek-V4 Flash, GLM-5.1, GLM-5.2} | 74.0% | $0.44 |
Forced single-model GLM-5.2 resolves the most tasks: +5.1 points over OpenClaw's direct GLM-5.2
run, and ahead of OpenClaw's strongest single model at about 31% of its cost. The routing pool
matches OpenClaw's GLM-5.2 run at half the cost, delegating 207 of the 350 tasks (59%) to the
inexpensive DeepSeek-V4 Flash tier and escalating 139 to the top tier.
### DRACO
100 cross-domain deep-research tasks, graded on factual accuracy, completeness, objectivity,
presentation quality, and citation quality. Cost is average billed cost per task; tokens are
input plus output, in thousands.
| Framework | Model (pool) | Score | Cost per task | Tokens (K) |
| --- | --- | ---: | ---: | ---: |
| OpenClaw | Opus-4.8 | 52.13 | $1.1420 | 54.2 |
| OpenSquilla | Opus-4.8 | 52.36 | $0.6559 | 103.5 |
| OpenSquilla | {DeepSeek-V4 Pro, GLM-5.2, Opus-4.8} | 52.33 | $0.3729 | 108.6 |
The harness alone edges past OpenClaw's direct run while nearly halving cost; turning routing on
keeps 99.94% of that score at 67% below the OpenClaw run. The routed run spends more tokens than
the fixed one, so the saving comes from the price mix of the calls rather than from shorter
prompts.
### Multi-model ensemble routing
The high-accuracy mode drafts with several proposer models and fuses the drafts with an
aggregator. Every row runs in the same OpenSquilla harness over DRACO, so the execution
substrate is fixed and only the model allocation changes.
| Search | Method | Score | Cost per task | Tokens (K) |
| --- | --- | ---: | ---: | ---: |
| DuckDuckGo | Fable 5 | 59.80 | $1.2122 | 93.7 |
| DuckDuckGo | Opus-4.8 | 52.36 | $0.6559 | 103.5 |
| DuckDuckGo | DeepSeek-V4 Pro | 50.32 | $0.1320 | 83.4 |
| DuckDuckGo | GPT-5.5 | 50.22 | $0.4505 | 81.9 |
| DuckDuckGo | Qwen3.7-Max | 49.34 | $0.0432 | 99.5 |
| DuckDuckGo | GLM-5.2 | 48.28 | $0.1214 | 116.8 |
| DuckDuckGo | Kimi K2.7 Code | 45.48 | $0.0676 | 86.3 |
| DuckDuckGo | Gemini-3 Flash | 40.79 | $0.0117 | 9.5 |
| DuckDuckGo | Multi-model ensemble routing (ours) | 60.82 | $0.3766 | 579.7 |
| Brave | Fable 5 | 62.06 | $1.3241 | 106.7 |
| Brave | Opus-4.8 | 59.11 | $1.6177 | 257.7 |
| Brave | GPT-5.5 | 53.28 | $0.8407 | 189.4 |
| Brave | Multi-model ensemble routing (ours) | 64.09 | $0.1218 | 500.1 |
The ensemble outscores the strongest single model on both search providers: +1.02 points at 31%
of its cost under DuckDuckGo, and +2.03 points at 90.8% lower cost under Brave. Fable 5
completed 94 of the 100 tasks under DuckDuckGo and 93 under Brave, and is scored on the tasks it
completed; every other row completed all 100. Letting the router assemble the proposer set at
run time, with only the aggregator fixed, comes within 0.51 points of the hand-picked
configuration at 15.8% lower cost.
The quality is paid for in tokens and wall-clock time, which parallel proposer execution, early
stopping, and per-proposer budgets control.
---
## Troubleshooting
macOS desktop app keeps bouncing or reports AppTranslocation
If macOS starts OpenSquilla from a temporary AppTranslocation path, quit
OpenSquilla, drag the app into Applications if you are installing it, eject the
DMG, then open OpenSquilla again. If an old OpenSquilla icon is still bouncing,
force quit the old process first and reopen OpenSquilla.
macOS: Library not loaded: @rpath/libomp.dylib
If startup logs `Library not loaded: @rpath/libomp.dylib` from
`lightgbm/lib/lib_lightgbm.dylib`, OpenSquilla keeps running with
direct single-model routing, but the bundled `SquillaRouter` runtime
stays inactive until the macOS OpenMP runtime is installed.
The desktop app bundles the native runtime it needs. If you used
Quick terminal install or source install from a shell, install `libomp`
with Homebrew and restart the gateway:
```sh
brew install libomp
opensquilla gateway restart
```
Windows: DLL load failed / Visual C++ runtime
If startup logs `DLL load failed while importing
onnxruntime_pybind11_state`, OpenSquilla keeps running with direct
single-model routing, but the bundled `SquillaRouter` runtime stays
inactive until the Visual C++ Redistributable for Visual Studio
2015–2022 (x64) is installed.
The from-source PowerShell installer attempts to install the redistributable via
`winget`. If you used Quick terminal install, or `winget` is unavailable,
install it manually and restart PowerShell:
. Then restore the recommended
router:
```powershell
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router recommended
opensquilla gateway restart
```
---
## Credits
OpenSquilla is inspired by
[OpenClaw](https://github.com/openclaw/openclaw). Bundled third-party
content is attributed in
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
Community contributors are acknowledged in
[`CONTRIBUTORS.md`](CONTRIBUTORS.md), including release-specific attribution
notes for squash-merged or replayed work.
---
## Contributors
Thanks to all the people who contribute to OpenSquilla.
---
## Contributing
Contributions of every kind are welcome — bug reports, feature ideas,
documentation, new provider or channel adapters, skills, and core
runtime work. See [`CONTRIBUTING.md`](CONTRIBUTING.md), then open an
issue or pull request on
[GitHub](https://github.com/TokenRhythm/opensquilla).
[Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) ·
[Privacy](PRIVACY.md) · [Code signing policy](docs/code-signing-policy.md) ·
[Third-party notices](THIRD_PARTY_NOTICES.md) · [Support](SUPPORT.md) ·
[License](LICENSE) (Apache-2.0)
---
## Citation
If you use OpenSquilla in your research, please cite our technical report:
```bibtex
@misc{opensquilla2026,
title = {OpenSquilla: Token-Efficient Agent = Models + Routing Harness},
author = {{TokenRhythm Technologies}},
year = {2026},
month = aug,
eprint = {aixiv.260822.000001},
archivePrefix = {aiXiv},
howpublished = {aiXiv preprint},
url = {https://aixiv.science/abs/aixiv.260822.000001},
note = {Version 1.0, under review}
}
```