{ "markdown": "# OpenSquilla — Token-Efficient AI Agent\n\n

\n \"OpenSquilla\n

\n\n

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

\n\n

\n \"CI\"\n \"Website\"\n \"GitHub\n \"Python\n \"Apache\n

\n\n

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

\n\n---\n\n## News\n\n- 📢 **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.\n\n- 📢 **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**.\n\n---\n\n## Overview\n\nOpenSquilla is a token-efficient, microkernel AI agent. A local model\nrouter sends each turn to the cheapest model that can handle it, while\npersistent memory, a layered sandbox, built-in web search, and\non-device embeddings round out a single shared turn loop.\n\nEvery entry point — Web UI, CLI, and chat channels — runs through that\nsame loop, so tool dispatch, retries, and decision logging behave\nidentically everywhere. A pluggable provider layer speaks to\nTokenRhythm, OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini,\nQwen/DashScope, and 20+ other LLM providers with no change to your code or config\nschema.\n\nOpenSquilla 0.5.6 is the current stable release.\n\nFor task-oriented product documentation, start with the\n[OpenSquilla Product Guide](README.product.md) or the\n[documentation index](docs/README.md).\n\n---\n\n## Installation\n\nOpenSquilla runs on Windows, macOS, and Linux. Pick the path that\nmatches your use case.\n\nDesktop installers and Quick terminal install give you a prebuilt **release** —\nno Git required. The other two — Install from source and\nDevelop from source — build **from a Git checkout** (`git clone` + Git LFS),\nincluding the Vue control console. Release wheels and Desktop installers already\ncontain that console, so their users do **not** need Node.js or npm.\n\nRelease install commands use published GitHub release assets. Python wheel installs use versioned wheel filenames because installers validate the version\nembedded in the wheel filename.\n\nFor 0.5.6 desktop use, prefer the packaged desktop installers from\nthe GitHub Release: `OpenSquilla-0.5.6-mac-arm64.dmg` on macOS and\n`OpenSquilla-0.5.6-win-x64.exe` on Windows.\n\n| Path | Audience | When to use |\n| --- | --- | --- |\n| [Desktop installers](#desktop-installers) **(recommended desktop)** | macOS and Windows users | Packaged desktop app |\n| [Quick terminal install](#quick-terminal-install) **(recommended)** | End users on any OS | Release wheel from a terminal |\n| [Install from source](#install-from-source) | Users tracking `main` | Run from a checkout, not edit it |\n| [Develop from source](#develop-from-source) | Contributors | Edit, test, or debug the source |\n\n### Prerequisites\n\n| Requirement | Quick terminal install | Install from source | Develop from source |\n| --- | :---: | :---: | :---: |\n| Python 3.12+ | via `uv` | via `uv` or system | via `uv` |\n| Git + Git LFS | — | required | required |\n| Node.js 22.12+ + npm | — | required to build the Web UI | required for Web UI and wheels |\n| `uv` | installed if missing | recommended | required |\n\nThe default `recommended` profile installs **SquillaRouter** —\nOpenSquilla's on-device model router — and its model assets;\n`OPENSQUILLA_INSTALL_PROFILE=core` omits those dependencies. The\nseparate `--router disabled` onboarding flag keeps the dependencies\ninstalled but turns the router off at runtime.\n\nOn Windows, SquillaRouter's bundled ONNX runtime also needs the Visual\nC++ runtime. The from-source PowerShell installer installs it automatically via\n`winget`; the **Quick terminal install** (`uv tool install`) path does not — if\nstartup logs a `DLL load failed` error, install it manually (see\n[Troubleshooting](#troubleshooting)). OpenSquilla keeps running with direct\nsingle-model routing until it is installed.\n\nOn macOS terminal installs, SquillaRouter's LightGBM runtime may also\nneed the system OpenMP library. The desktop app bundles the\nruntime it needs, but **Quick terminal install** does not install\nHomebrew/system libraries. If startup logs `Library not loaded:\n@rpath/libomp.dylib`, run `brew install libomp`, then restart the\ngateway. OpenSquilla keeps running with direct single-model routing\nuntil it is installed.\n\nInstall links: [Git](https://git-scm.com/downloads) ·\n[Git LFS](https://git-lfs.com/) ·\n[Node.js](https://nodejs.org/en/download) ·\n[uv](https://docs.astral.sh/uv/getting-started/installation/).\n\n### Desktop installers\n\nThe 0.5.6 desktop installers package the Vue control console and\ngateway runtime in an Electron shell.\n\n- macOS Apple Silicon: \n- Windows x64: \n\nFor faster Mainland China downloads, use the OSS direct-download aliases:\n- macOS Apple Silicon: \n- Windows x64: \n\nThese fixed links advance only after a newer eligible release passes mirror\nverification. Use the versioned GitHub Release links above when you need a\nspecific release.\n\nQuit any running OpenSquilla desktop app before upgrading. On macOS, drag the\napp from the DMG into Applications for installation or updates, eject the DMG,\nthen open the Applications copy. The existing Desktop profile in the platform\napplication-data directory is reused. A terminal installation's\n`~/.opensquilla` is a separate profile; transfer it explicitly from Settings\nonly if needed.\n\nWhen upgrading the Windows Desktop from RC3 to RC4 or later, run the new\ninstaller directly over the existing installation. Do **not** uninstall RC3\nfirst: its uninstaller may remove Desktop user data. Back up\n`%APPDATA%\\OpenSquilla` before upgrading. RC4 and later installers preserve\nprofile data during a normal uninstall.\n\nCode signing policy: [`docs/code-signing-policy.md`](docs/code-signing-policy.md).\n\n> [!NOTE]\n> The 0.5.6 Windows installer is Authenticode signed as Beijing TokenRhythm\n> Technologies Co., Ltd. The published v0.5.4 Windows installer remains unsigned.\n> SmartScreen reputation can still take time\n> to build for a new publisher or application. If enterprise policy blocks the\n> Desktop app, use [Quick terminal install](#quick-terminal-install) instead.\n\n### Quick terminal install\n\nThe recommended path on Windows, macOS, and Linux. `uv` installs\nOpenSquilla into its own isolated environment and manages its own\nPython — no system Python required. This path installs published\nreleases only; for `main`, development branches, or local checkouts\nuse [Install from source](#install-from-source).\n\n**1. Install `uv`** — skip if `uv --version` already works.\n\nLinux / macOS:\n\n```sh\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n. \"$HOME/.local/bin/env\"\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n$env:Path = \"$env:USERPROFILE\\.local\\bin;\" + $env:Path\n```\n\n**2. Install OpenSquilla** — the same command on every platform.\n\n```sh\nuv tool install --python 3.12 \"opensquilla[recommended] @ https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.6/opensquilla-0.5.6-py3-none-any.whl\"\n```\n\nThis installs the OpenSquilla wheel from the release URL, then lets\n`uv` download the dependencies declared by the selected extras. The\ndefault `recommended` extra includes SquillaRouter runtime dependencies\nsuch as ONNX Runtime, LightGBM, NumPy, and tokenizers, so a first install\nneeds network access unless those wheels are already cached. `uv` does\nnot install system native runtimes such as macOS `libomp` or the Windows\nVisual C++ Redistributable; see [Troubleshooting](#troubleshooting) if\nthe router runtime reports a native-library load error.\n\n**3. Configure and run.**\n\n```sh\nopensquilla onboard\nopensquilla gateway run\n```\n\n> [!NOTE]\n> If `opensquilla` is not found right after a fresh `uv` install, open\n> a new terminal, or re-run the PATH line from step 1.\n\nFor a fully pinned install, use the versioned wheel URL:\n`https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.6/opensquilla-0.5.6-py3-none-any.whl`.\n\n### Install from source\n\nUse this path to run OpenSquilla from a checkout without editing it.\nThe clone is only the package source for the installer; after install,\nuse the `opensquilla` command — do not run `uv run`. Choose\n[Develop from source](#develop-from-source) instead if you intend to\nmodify the code.\n\n1. **Clone with LFS assets**\n\n ```sh\n git lfs install\n git clone https://github.com/TokenRhythm/opensquilla.git\n cd opensquilla\n git lfs pull --include=\"src/opensquilla/squilla_router/models/**\"\n ```\n\n2. **Run the installer**\n\n **macOS / Linux**\n\n ```sh\n bash scripts/install_source.sh\n ```\n\n **Windows PowerShell**\n\n ```powershell\n powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1\n ```\n\n The script installs `.[recommended]` (SquillaRouter + memory + local\n models) into a dedicated user environment via `uv tool install`. Before the\n Python install, it runs `npm ci` and `npm run build` in\n `opensquilla-webui`. Every source reinstall recreates the locked\n `node_modules` tree and rebuilds the console; the first run normally has the\n largest dependency download, while a warm npm cache reduces later network\n use but not all build time or disk writes. It then installs the built console\n with the Python package,\n falling back to `python -m pip install --user` when `uv` is\n unavailable. If `opensquilla` is not on `PATH` after install (common\n on a fresh host where `~/.local/bin` is not yet on `PATH`), run\n `uv tool update-shell` and open a new terminal; see\n [Troubleshooting](#troubleshooting) for details.\n\n Direct `pip install .`, `uv tool install .`, and VCS URL installs are\n low-level source-build paths, not substitutes for this installer. A local\n checkout works only after its Web UI has been built; a VCS URL checkout has\n no generated artifact and is intentionally rejected. Use this source\n installer or an official release wheel instead.\n\n3. **(optional) Install advanced extras.** Most channels — Feishu,\n Telegram, DingTalk, QQ, WeCom, Slack, and Discord — work from the\n base install. The opt-in extras are:\n\n - `matrix` — Matrix channel (pulls in `matrix-nio`)\n - `matrix-e2e` — Matrix channel with end-to-end encryption (requires\n libolm)\n - `document-extras` — PDF generation via WeasyPrint\n\n ```sh\n OPENSQUILLA_INSTALL_EXTRAS=matrix bash scripts/install_source.sh # macOS / Linux\n ```\n\n ```powershell\n powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1 -Extras matrix # Windows\n ```\n\n4. **Configure and run** — see [Configuration](#configuration).\n\n
\nInstall from source — terminal prerequisites and installer options\n\n**Install prerequisites (Git, Git LFS, Node.js 22.12+ with npm, uv) from a terminal**\n\nWindows PowerShell:\n\n```powershell\nwinget install --id Git.Git -e\nwinget install --id GitHub.GitLFS -e\nwinget install --id OpenJS.NodeJS.LTS -e\npowershell -ExecutionPolicy Bypass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\ngit lfs install\n```\n\nmacOS (Homebrew):\n\n```sh\nbrew install git git-lfs node uv\ngit lfs install\n```\n\nDebian / Ubuntu:\n\n```sh\nsudo apt update && sudo apt install -y git git-lfs curl\ncurl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -\nsudo apt install -y nodejs\ncurl -LsSf https://astral.sh/uv/install.sh | sh\ngit lfs install\n```\n\nOn Fedora use `sudo dnf install -y git git-lfs`; on Arch use\n`sudo pacman -S --needed git git-lfs`; install Node.js 22.12+ and npm from\nyour distribution or nodejs.org, then install `uv` with the `curl` command\nabove. PATH changes from these installers apply to new\nterminal sessions.\n\n**Installer environment variables and PATH checks**\n\n```sh\nOPENSQUILLA_INSTALL_PROFILE=core bash scripts/install_source.sh # minimal runtime, no SquillaRouter\nOPENSQUILLA_INSTALL_DRY_RUN=1 bash scripts/install_source.sh # print the plan only\n```\n\nVerify which `opensquilla` your shell runs with `command -v\nopensquilla` (macOS/Linux) or `where.exe opensquilla` (Windows). If it\nis not on `PATH`, run `uv tool update-shell`. After reinstalling from a\nlocal checkout, restart the gateway so it loads the updated package.\n\n
\n\n### Develop from source\n\nUse this path when you are working on OpenSquilla's source code:\nmaking changes, running tests, or debugging behavior against this\ncheckout. It is not the normal install path. Unlike\n[Install from source](#install-from-source), this path requires `uv`:\n`uv sync` creates a repository-local `.venv`, and `uv run` executes\ncommands against the files in this checkout.\n\n```sh\ncd opensquilla-webui\nnpm ci\nnpm run build\ncd ..\nuv sync --extra recommended --extra dev\nuv run opensquilla --help\n```\n\nRun `npm run build` again after changing Web UI sources. Standard wheel builds\nfail closed when the generated console is missing or stale; editable `uv sync`\ninstalls remain available for backend-only work.\n\nThe `recommended` extra includes SquillaRouter for development too;\nthe `dev` extra installs the test, lint, and typecheck tools. Install\nadditional extras into the same environment you run:\n\n```sh\nuv sync --extra recommended --extra dev --extra matrix\nuv run opensquilla channels status matrix --json\n```\n\nIn this mode, prefix every `opensquilla` command in\n[Configuration](#configuration) with `uv run`. Do not debug a\ndevelopment checkout through a user-local `opensquilla` command — that\ncommand runs in a different Python environment.\n\n### Uninstall\n\nRemove OpenSquilla with `opensquilla uninstall`. It keeps your data by default\nand removes only the program:\n\n```sh\nopensquilla uninstall --dry-run # preview what would be removed and kept\nopensquilla uninstall # remove the program, keep your data\n```\n\nTo delete data too, opt in explicitly:\n\n```sh\nopensquilla uninstall --purge-state # sessions, logs, cache, scheduler, memory\nopensquilla uninstall --purge-config # config.toml and secrets (.env)\nopensquilla uninstall --purge-all # everything (asks you to type a confirmation)\n```\n\nThe running gateway is drained and stopped first, deletion stays inside the\nOpenSquilla home, and Docker/desktop installs get guided removal steps instead.\nDesktop or OS app removal remains platform-specific; the CLI guidance does not\nremove a desktop app bundle. See [`docs/cli.md`](docs/cli.md#uninstall) for the\nfull reference.\n\n---\n\n## Usage Statistics and Privacy\n\nOpenSquilla uses the existing **Network reporting** switch for V1 statistics and\nboth V2 statistics streams. Reporting is enabled by default and can be turned off\nin Privacy settings, without separate onboarding choices or consent popups:\n\n- **Reliability diagnostics** records bounded operation results for app and\n Gateway startup, crashes, turns, tools, file parsing, updates, and session\n performance.\n- **Product and growth analytics** records client launches, product activity,\n and one-time acquisition, onboarding,\n app-readiness, registration, and first-successful-turn milestones. Existing\n installations do not become new-user cohorts just by enabling reporting.\n\nThe streams retain separate session/journey identifiers, durable queues,\nupload endpoints, and retention policies. Reliability events\ngo to `/v1/reliability/events`; growth events go to `/v1/growth/events`.\nRetries reuse `event_id` for server-side deduplication, and growth events are\nnot sampled.\n\nApplication events also carry a one-way, application-specific `device_id`\nderived locally from the OS machine identifier when available. Daily/monthly\nactivity and feature device counts deduplicate this token across profiles and\nclient surfaces. Legacy events without it are excluded from device counts;\noperation totals and success rates still count actual operations.\n\nV2 statistics never include prompts, responses, file names, file paths, file\ncontents, tool arguments, task parameters, provider configuration, raw account\nIDs, order data, MAC addresses, IP addresses, or raw OS machine identifiers. Complete\ncrash stacks stay local unless the user explicitly prepares and shares a\nsupport bundle.\n\nV1 installation/version reporting at `/v1/install` and daily conversation/token\ntotals at `/v1/usage` run alongside V2 after Gateway readiness. Only completed\nUTC days are uploaded; pending days retry hourly. Existing installation state\nis retained. Daily event IDs use a persistent random identity per aggregate\ndatabase to separate profiles while keeping retries stable. V1 retains its pseudonymous installation\nID derived locally from MAC/IP data, with a persisted random fallback; raw MAC/IP\nvalues are not uploaded. The `X-OpenSquilla-Install-Id` provider header remains\nretired, and V2 keeps its independent identities.\n\nTo force all non-user-initiated network observability off before startup:\n\n```sh\nOPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true\n```\n\nor set:\n\n```toml\n[privacy]\ndisable_network_observability = true\n```\n\nThis is a hard veto over V1 and both V2 statistics streams, passive update checks, and\nautomatic desktop update checks. Disabling Network reporting pauses pending uploads and\nstops collection without deleting local statistics state. Previously saved\nper-scope declines are migrated to the unified switch being off; users can\nthen change that one setting. CI, test, and `DO_NOT_TRACK` environments\nalso fail closed for statistics uploads. Other user-initiated actions may still contact\nconfigured providers, search services, channels, or release hosts.\nExplicit update-availability checks remain disabled while the unified or\nlegacy update opt-out controls are active.\n\nLegacy opt-out environment variables remain honored:\n\n```sh\nOPENSQUILLA_TELEMETRY_DISABLED=true\nOPENSQUILLA_UPDATE_CHECK_DISABLED=true\n```\n\nThe legacy statistics variable disables V1 and V2 reporting. The legacy update\nvariable also suppresses V1 uploads for compatibility, but does not disable V2.\nSee [`PRIVACY.md`](PRIVACY.md) for the complete data, reporting, deletion, update,\nand external-producer rules.\n\n---\n\n## Configuration\n\n### First-run setup\n\n`opensquilla onboard` is the interactive first-run wizard. It writes\nthe active config file and keeps provider secrets in environment\nvariables when you pass `--api-key-env`. The router defaults to\n`recommended` (SquillaRouter on supported providers); pass\n`--router disabled` for direct single-model routing.\n\n```sh\nopensquilla onboard # full interactive wizard\nopensquilla onboard --if-needed # idempotent: safe for scripts and re-installs\nopensquilla onboard --minimal # provider only; skip channels and search\nopensquilla onboard status # inspect every setup section without writing\n```\n\nIn SSH, CI, or any environment without a TTY, use the non-interactive\nform — keep the secret in the environment and pass its **name**, not\nits value:\n\n**Linux / macOS**\n\n```sh\nexport OPENROUTER_API_KEY=\"sk-...\"\nopensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY\n```\n\n**Windows PowerShell**\n\n```powershell\n$env:OPENROUTER_API_KEY=\"sk-...\"\nopensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY\n```\n\nOpenRouter is only an example — substitute any supported provider and\nits API-key variable.\n\nRe-configure one section later without redoing the whole wizard (these\nexamples assume the relevant API key is already in the environment):\n\n```sh\nopensquilla configure provider --provider openai --model gpt-4o --api-key-env OPENAI_API_KEY\nopensquilla configure router --router recommended\nopensquilla configure search --search-provider duckduckgo\nopensquilla configure search --search-provider exa --api-key-env EXA_API_KEY\nopensquilla configure channels\n```\n\nSections: `provider`, `router`, `channels`, `search`,\n`image-generation`, `memory-embedding`. The Web UI exposes the same\ncatalog and status model at `/control/setup`: Provider and Router are\nthe fast path, while Channels, Search, Image generation, and Memory\nembedding sit in the Capability Center and can be configured later.\nEmpty channels are treated as an opt-out, not a failed setup.\n\n**Config load order:** `OPENSQUILLA_GATEWAY_CONFIG_PATH` →\n`./opensquilla.toml` → `~/.opensquilla/config.toml` → built-in\ndefaults. Environment values for individual secrets always win over\nfile values.\n\n### Migrate from OpenClaw or Hermes Agent\n\nIf you already have state under `~/.openclaw` or `~/.hermes`, run a\ndry run first to inspect the migration report, then apply it explicitly:\n\n```sh\nopensquilla migrate openclaw --json\nopensquilla migrate openclaw --apply\n\nopensquilla migrate hermes --json\nopensquilla migrate hermes --apply\n```\n\nUse `opensquilla migrate --source openclaw,hermes --apply` to import\nboth default homes. Add `--migrate-secrets` only after reviewing the dry-run\nreport. See [`MIGRATION.md`](MIGRATION.md) for custom paths and conflict\nhandling.\n\n### Run\n\n```sh\nopensquilla gateway run # foreground, 127.0.0.1:18791\nopensquilla gateway start --json # background + health wait\nopensquilla chat # interactive REPL\nopensquilla agent -m \"your prompt\" # one-shot, automation-friendly\n```\n\nFor subprocess progress, add `--event-stream-stderr`. The final result keeps\nits existing stdout format, while stderr receives incrementally flushed,\nprivacy-bounded v1 JSONL events. Consumers must drain stderr continuously and\nonly treat objects with `\"_event\": true` as events because ordinary diagnostics\ncan share the stream. See [docs/cli.md](docs/cli.md#agent-progress-event-stream)\nfor the versioned schema and compatibility contract.\n\nParallel agent subprocesses must use separate profile homes and persistent\nstate roots. Set both variables for every child:\n\n```sh\nOPENSQUILLA_STATE_DIR=/tmp/agent-a \\\nOPENSQUILLA_GATEWAY_STATE_DIR=/tmp/agent-a/state \\\n opensquilla agent -m \"task A\" --json --event-stream-stderr &\nOPENSQUILLA_STATE_DIR=/tmp/agent-b \\\nOPENSQUILLA_GATEWAY_STATE_DIR=/tmp/agent-b/state \\\n opensquilla agent -m \"task B\" --json --event-stream-stderr &\nwait\n```\n\nOn Windows, set both values in each child process environment. If an\norchestrator copies `config.toml` or `.env`, remove or rewrite every `state_dir`\nor `OPENSQUILLA_GATEWAY_STATE_DIR` value as well. Explicitly shared session DB,\nworkspace, scratch, transcript, and usage paths remain shared by design.\n\n> **Development-only OpenTUI terminal UI.** Release installs continue to use\n> the Python-native chat. The richer full-screen frontend currently runs only\n> from a [Develop from source](#develop-from-source) checkout; no companion host\n> is published in release assets or installed by the release installer. From\n> the checkout, install the pinned Bun dependencies once, then launch against\n> that same source tree:\n>\n> ```sh\n> bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package\n> OPENSQUILLA_TUI_DEV_SOURCE_HOST=1 uv run opensquilla chat --ui tui\n> ```\n>\n> Use `opensquilla chat --ui plain` to require the stable renderer. See\n> [docs/tui.md](docs/tui.md) for terminal chat usage and\n> [docs/features/tui-frontend.md](docs/features/tui-frontend.md) for backend\n> details.\n\nOpen the Web UI at . The **Health**\nview shows whether OpenSquilla is ready, what is not ready, and the\nnext recovery steps. From the CLI, run:\n\n```sh\nopensquilla doctor\nopensquilla doctor --json\nopensquilla doctor --config ./opensquilla.toml --json\n```\n\n`/health` and `/healthz` are lightweight liveness endpoints for process\nchecks. `opensquilla doctor` and the Web UI Health view are the readiness\nsurfaces for provider config, memory, logs, search, channels, sandbox\nposture, router, image generation, and recovery guidance. Press\n`Ctrl+C` to stop a foreground gateway.\n\nOther command groups include `sessions`, `skills`, `memory`, `migrate`,\n`cron`, `channels`, `providers`, `models`, and `cost`. Run\n`opensquilla --help` or `opensquilla --help` for details.\n\n
\nAdvanced configuration — verify a channel, public network binding, Docker\n\n**Connect and verify a messaging channel**\n\nChannel saves are config changes, not runtime-connectivity proof.\nRestart the gateway after channel edits, then verify the live channel:\n\n```sh\nopensquilla gateway restart\nopensquilla channels status --json\n```\n\nTreat a channel as connected only when the status payload reports\n`enabled=true`, `configured=true`, and `connected=true`. Feishu\ndefaults to websocket mode, Telegram to polling, and Slack can use\nSocket Mode — none of those modes needs a public URL. Feishu webhook\nmode, Telegram webhook mode, Slack webhook mode, and WeCom require a\npublic, provider-reachable URL.\n\n**Public network binding**\n\nTo reach the Web UI from another machine, bind the gateway to all\ninterfaces and use the host's public IP:\n\n```sh\nopensquilla gateway run --listen 0.0.0.0 --port 18791\n```\n\nPublic access also requires the host firewall or cloud security group\nto allow inbound TCP on that port. Do not expose the gateway with\n`[auth] mode = \"none\"` — configure token auth before binding to\n`0.0.0.0`.\n\n**Docker**\n\nPrebuilt multi-arch images (`amd64`/`arm64`) are published to\n`ghcr.io/tokenrhythm/opensquilla` on release tags. 0.5.6 is published as\nboth `v0.5.6` and the moving `latest` tag —\n[`docs/docker.md`](docs/docker.md) is the full container guide\n(home servers and NAS, LAN exposure with token auth, upgrades):\n\n```sh\nOPENSQUILLA_GATEWAY_IMAGE=ghcr.io/tokenrhythm/opensquilla:latest docker compose up -d\n```\n\nWithout `OPENSQUILLA_GATEWAY_IMAGE`, the compose path runs an\n`opensquilla:local` image you build yourself. Build it from a source\ncheckout with the Git LFS router assets pulled\n(see [Install from source](#install-from-source) for the clone and\n`git lfs pull`):\n\n```sh\ndocker build -t opensquilla:local .\n```\n\n`./start.sh` (or `start.ps1` on Windows) then runs `docker compose\nup -d` and tails the gateway logs. Docker avoids a host Python\ntoolchain — not the local image build.\n\n
\n\nProvider tiers, sandbox tuning, image generation, and concurrency\nsettings live in `opensquilla.toml.example`.\n\n---\n\n## Release Notes\n\nPer-version highlights live in [`CHANGELOG.md`](CHANGELOG.md) and\n[`docs/releases/`](docs/releases/).\n\n---\n\n## Key Features\n\n| Capability | What it does |\n| --- | --- |\n| **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 tiers (C0–C3; legacy T0–T3 names are aliases) to the cheapest capable model. Classification runs on-device; your prompt never leaves the machine to make that decision. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **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`. |\n| **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`. |\n| **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. |\n\n\n---\n\n## Benchmark Results\n\nResults from our [technical report](https://aixiv.science/abs/aixiv.260822.000001). Scores come\nfrom each benchmark's own grader, and costs use one provider price list across all frameworks.\nAn OpenSquilla row is either a forced single-model run — the full harness with routing disabled,\nwhich isolates the harness contribution — or a multi-tier routing pool.\n\n### PinchBench\n\n25 tasks covering file operations, data processing, web retrieval, creative output, tool use,\nand memory recall. Score is the cross-task mean; cost is the total for the run.\n\n| Framework | Model (pool) | Score | Cost |\n| --- | --- | ---: | ---: |\n| OpenClaw | Opus-4.7 | 92.55 | $6.23 |\n| OpenClaw | GLM-5.1 | 88.33 | $1.60 |\n| OpenClaw | OpenRouter Auto | 88.10 | $3.01 |\n| Hermes Agent | Opus-4.7 | 92.65 | $6.66 |\n| OpenSquilla | Opus-4.7 | 93.85 | $4.84 |\n| OpenSquilla | {DeepSeek-V4 Flash, DeepSeek-V4 Flash, GLM-5.1, Opus-4.7} | 92.51 | $0.69 |\n| OpenSquilla | {MiniMax M2.5 (free), DeepSeek-V4 Flash, DeepSeek-V4 Flash, GLM-5.1} | 90.48 | $0.13 |\n\nForced single-model OpenSquilla takes the top score, +1.3 over OpenClaw's Opus-4.7 run at 22%\nlower cost. The Opus-4.7-backstopped routing pool holds 99.96% of the 92.55 baseline score at\n$0.69. The OpenRouter Auto row is a query-level routing baseline measured under a separate\nprotocol and is not directly comparable to the other rows.\n\n### ClawMark\n\n100 domain-specific business tasks across 13 domains, from clinical assistance and content\noperations to legal, HR, insurance, and real estate. Cost is average billed cost per task.\n\n| Framework | Model (pool) | Score | Cost per task |\n| --- | --- | ---: | ---: |\n| OpenClaw | GLM-5.1 | 71.2 | $0.62 |\n| OpenSquilla | GLM-5.1 | 77.0 | $0.87 |\n| OpenSquilla | {MiniMax M2.5 (free), DeepSeek-V4 Pro, GLM-5.1, GLM-5.1} | 70.6 | $0.39 |\n\nThe harness alone adds 5.8 points to the same model, at higher cost — this is the one benchmark\nwhere the quality point sits above the baseline on price. The routing pool trades the gain back\nfor a 37% cheaper task, landing near the GLM-5.1 direct run.\n\n### ClawSWEBench\n\n350 multilingual SWE-bench-style repair tasks from 8 languages and 43 repositories, with the\ntask set, containers, prompts, turn limits, and timeouts all fixed. Cost is average billed cost\nper task.\n\n| Framework | Model (pool) | Resolve rate | Cost per task |\n| --- | --- | ---: | ---: |\n| OpenClaw | Opus-4.7 | 77.1% | $3.09 |\n| OpenClaw | GLM-5.2 | 74.3% | $0.87 |\n| OpenClaw | GLM-5.1 | 73.4% | $0.79 |\n| OpenClaw | Qwen3.7-Max | 73.1% | $1.25 |\n| OpenSquilla | GLM-5.2 | 79.4% | $0.95 |\n| OpenSquilla | GLM-5.1 | 74.9% | $0.87 |\n| OpenSquilla | {DeepSeek-V4 Flash, GLM-5.1, GLM-5.2} | 74.0% | $0.44 |\n\nForced single-model GLM-5.2 resolves the most tasks: +5.1 points over OpenClaw's direct GLM-5.2\nrun, and ahead of OpenClaw's strongest single model at about 31% of its cost. The routing pool\nmatches OpenClaw's GLM-5.2 run at half the cost, delegating 207 of the 350 tasks (59%) to the\ninexpensive DeepSeek-V4 Flash tier and escalating 139 to the top tier.\n\n### DRACO\n\n100 cross-domain deep-research tasks, graded on factual accuracy, completeness, objectivity,\npresentation quality, and citation quality. Cost is average billed cost per task; tokens are\ninput plus output, in thousands.\n\n| Framework | Model (pool) | Score | Cost per task | Tokens (K) |\n| --- | --- | ---: | ---: | ---: |\n| OpenClaw | Opus-4.8 | 52.13 | $1.1420 | 54.2 |\n| OpenSquilla | Opus-4.8 | 52.36 | $0.6559 | 103.5 |\n| OpenSquilla | {DeepSeek-V4 Pro, GLM-5.2, Opus-4.8} | 52.33 | $0.3729 | 108.6 |\n\nThe harness alone edges past OpenClaw's direct run while nearly halving cost; turning routing on\nkeeps 99.94% of that score at 67% below the OpenClaw run. The routed run spends more tokens than\nthe fixed one, so the saving comes from the price mix of the calls rather than from shorter\nprompts.\n\n### Multi-model ensemble routing\n\nThe high-accuracy mode drafts with several proposer models and fuses the drafts with an\naggregator. Every row runs in the same OpenSquilla harness over DRACO, so the execution\nsubstrate is fixed and only the model allocation changes.\n\n| Search | Method | Score | Cost per task | Tokens (K) |\n| --- | --- | ---: | ---: | ---: |\n| DuckDuckGo | Fable 5 | 59.80 | $1.2122 | 93.7 |\n| DuckDuckGo | Opus-4.8 | 52.36 | $0.6559 | 103.5 |\n| DuckDuckGo | DeepSeek-V4 Pro | 50.32 | $0.1320 | 83.4 |\n| DuckDuckGo | GPT-5.5 | 50.22 | $0.4505 | 81.9 |\n| DuckDuckGo | Qwen3.7-Max | 49.34 | $0.0432 | 99.5 |\n| DuckDuckGo | GLM-5.2 | 48.28 | $0.1214 | 116.8 |\n| DuckDuckGo | Kimi K2.7 Code | 45.48 | $0.0676 | 86.3 |\n| DuckDuckGo | Gemini-3 Flash | 40.79 | $0.0117 | 9.5 |\n| DuckDuckGo | Multi-model ensemble routing (ours) | 60.82 | $0.3766 | 579.7 |\n| Brave | Fable 5 | 62.06 | $1.3241 | 106.7 |\n| Brave | Opus-4.8 | 59.11 | $1.6177 | 257.7 |\n| Brave | GPT-5.5 | 53.28 | $0.8407 | 189.4 |\n| Brave | Multi-model ensemble routing (ours) | 64.09 | $0.1218 | 500.1 |\n\nThe ensemble outscores the strongest single model on both search providers: +1.02 points at 31%\nof its cost under DuckDuckGo, and +2.03 points at 90.8% lower cost under Brave. Fable 5\ncompleted 94 of the 100 tasks under DuckDuckGo and 93 under Brave, and is scored on the tasks it\ncompleted; every other row completed all 100. Letting the router assemble the proposer set at\nrun time, with only the aggregator fixed, comes within 0.51 points of the hand-picked\nconfiguration at 15.8% lower cost.\n\nThe quality is paid for in tokens and wall-clock time, which parallel proposer execution, early\nstopping, and per-proposer budgets control.\n\n---\n\n## Troubleshooting\n\n
\nmacOS desktop app keeps bouncing or reports AppTranslocation\n\nIf macOS starts OpenSquilla from a temporary AppTranslocation path, quit\nOpenSquilla, drag the app into Applications if you are installing it, eject the\nDMG, then open OpenSquilla again. If an old OpenSquilla icon is still bouncing,\nforce quit the old process first and reopen OpenSquilla.\n\n
\n\n
\nmacOS: Library not loaded: @rpath/libomp.dylib\n\nIf startup logs `Library not loaded: @rpath/libomp.dylib` from\n`lightgbm/lib/lib_lightgbm.dylib`, OpenSquilla keeps running with\ndirect single-model routing, but the bundled `SquillaRouter` runtime\nstays inactive until the macOS OpenMP runtime is installed.\n\nThe desktop app bundles the native runtime it needs. If you used\nQuick terminal install or source install from a shell, install `libomp`\nwith Homebrew and restart the gateway:\n\n```sh\nbrew install libomp\nopensquilla gateway restart\n```\n\n
\n\n
\nWindows: DLL load failed / Visual C++ runtime\n\nIf startup logs `DLL load failed while importing\nonnxruntime_pybind11_state`, OpenSquilla keeps running with direct\nsingle-model routing, but the bundled `SquillaRouter` runtime stays\ninactive until the Visual C++ Redistributable for Visual Studio\n2015–2022 (x64) is installed.\n\nThe from-source PowerShell installer attempts to install the redistributable via\n`winget`. If you used Quick terminal install, or `winget` is unavailable,\ninstall it manually and restart PowerShell:\n. Then restore the recommended\nrouter:\n\n```powershell\nopensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router recommended\nopensquilla gateway restart\n```\n\n
\n\n---\n\n## Credits\n\nOpenSquilla is inspired by\n[OpenClaw](https://github.com/openclaw/openclaw). Bundled third-party\ncontent is attributed in\n[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).\n\nCommunity contributors are acknowledged in\n[`CONTRIBUTORS.md`](CONTRIBUTORS.md), including release-specific attribution\nnotes for squash-merged or replayed work.\n\n---\n\n## Contributors\n\nThanks to all the people who contribute to OpenSquilla.\n\n

\n \n \"OpenSquilla\n \n

\n\n---\n\n## Contributing\n\nContributions of every kind are welcome — bug reports, feature ideas,\ndocumentation, new provider or channel adapters, skills, and core\nruntime work. See [`CONTRIBUTING.md`](CONTRIBUTING.md), then open an\nissue or pull request on\n[GitHub](https://github.com/TokenRhythm/opensquilla).\n\n[Code of Conduct](CODE_OF_CONDUCT.md) · [Security](SECURITY.md) ·\n[Privacy](PRIVACY.md) · [Code signing policy](docs/code-signing-policy.md) ·\n[Third-party notices](THIRD_PARTY_NOTICES.md) · [Support](SUPPORT.md) ·\n[License](LICENSE) (Apache-2.0)\n\n---\n\n## Citation\n\nIf you use OpenSquilla in your research, please cite our technical report:\n\n```bibtex\n@misc{opensquilla2026,\n title = {OpenSquilla: Token-Efficient Agent = Models + Routing Harness},\n author = {{TokenRhythm Technologies}},\n year = {2026},\n month = aug,\n eprint = {aixiv.260822.000001},\n archivePrefix = {aiXiv},\n howpublished = {aiXiv preprint},\n url = {https://aixiv.science/abs/aixiv.260822.000001},\n note = {Version 1.0, under review}\n}\n```\n", "bytes": 40521, "sha": "16c803512f6e8de351757d0850c40c35c11529f3ec5268be8f9bd5bdbae94f66", "repo_slug": "tokenrhythm/opensquilla", "fonte": "repo", "truncated": false, "api": "https://api.agentalog.com/api/listings/skl_tokenrhythm_opensquilla_ai_video_script_19a5e218/readme" }