From 31fd1e655cf679d3a23b0c0f01d055ddb9391d2f Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:56:47 +0000 Subject: [PATCH] docs: preserve upstream English README --- README.en.md | 812 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 812 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..8d1fcfb --- /dev/null +++ b/README.en.md @@ -0,0 +1,812 @@ +# OpenSquilla — Token-Efficient AI Agent + +

+ OpenSquilla logo +

+ +

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

+ +

+ CI + Website + GitHub release + Python 3.12+ + Apache 2.0 License +

+ +

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

+ +--- + +## News + +- 📢 **2026-07-03** — Our technical report **[Agentic Routing: The Harness-Native Data Flywheel](docs/releases/agentic_routing_v0.pdf)** (preview) is out, released alongside OpenSquilla **0.5.0 Preview 1**. It details how the harness-native router turns everyday agent traffic into a self-improving data flywheel. + +--- + +## 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 3 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 3 desktop use, prefer the packaged desktop installers from +the GitHub Release: `OpenSquilla-0.5.0-rc3-mac-arm64.dmg` on macOS and +`OpenSquilla-0.5.0-rc3-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](https://git-scm.com/downloads) · +[Git LFS](https://git-lfs.com/) · +[uv](https://docs.astral.sh/uv/getting-started/installation/). + +### Desktop installers + +The 0.5.0 Preview 3 desktop installers package the Vue control console and +gateway runtime in an Electron shell. + +- macOS Apple Silicon: +- Windows x64: + +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. Existing `~/.opensquilla/config.toml` and +session data are reused. + +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.0rc3/opensquilla-0.5.0rc3-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.0rc3/opensquilla-0.5.0rc3-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 desktop startup auto-update checks. 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 desktop startup auto-update checks. Manual user-initiated actions may still +contact network services after user intent, including manual release, download, +or update checks and configured providers, search, or channels. + +Legacy opt-out environment variables remain honored: + +```sh +OPENSQUILLA_TELEMETRY_DISABLED=true +OPENSQUILLA_UPDATE_CHECK_DISABLED=true +``` + +Advanced deployments can use their own endpoint: + +```sh +OPENSQUILLA_TELEMETRY_ENDPOINT=https://example.com/v1/install +``` + +--- + +## 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 +``` + +> **Preview — the OpenTUI terminal UI.** `opensquilla chat` runs the stable, +> Python-native chat by default. A richer OpenTUI frontend (themes, one-card +> turns, a live router HUD, drag-select copy) is an opt-in preview that runs +> **only from a [Develop from source](#develop-from-source) checkout**: the host +> is loaded from the OpenTUI package next to the running code, and that package +> (plus its [Bun](https://bun.sh) dependencies) is not shipped in the release +> wheel or the `Install from source` install. From the checkout, install the Bun +> deps once, then launch with `uv run` so it runs against that same tree: +> +> ```sh +> bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package +> OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat +> ``` +> +> Leave `OPENSQUILLA_TUI_BACKEND` unset for the stable chat. 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/opensquilla/opensquilla` on release tags. Preview 3 is published as +both `v0.5.0rc3` and the moving `latest` tag — +[`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/opensquilla/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`. + +--- + +## What's New in 0.5.0 Preview 3 + +OpenSquilla 0.5.0 Preview 3 is a broad preview update for migration, routing, +desktop, runtime, and deployment: + +- **Legacy-home migration** - detect and transactionally import older CLI, + desktop, portable, relocated, restored, and Docker-volume homes. +- **Providers and routing** - support expands across TokenRhythm, Tencent + TokenHub and Token Plan, and IQS, with live model discovery, probe and context + diagnostics, verified coding presets, richer ensemble configuration, and an + opt-in router self-learning loop. +- **Desktop, terminal, and Control UI** - improved updater behavior, onboarding, + terminal interaction, diagnostics, themes, attachments, chat navigation, and + desktop platform integration. +- **Runtime and safety hardening** - stronger persistence, MCP, session, tool, + sandbox, secret-redaction, same-origin, and provider retry contracts. +- **Container images** - prebuilt `linux/amd64` and `linux/arm64` gateway images + are published as `v0.5.0rc3` and `latest` on GHCR. +- **Simplified release assets** - 0.5 previews publish Electron installers, + updater metadata, the versioned Python wheel, and checksums; Windows portable + archives remain retired. + +Full notes: [`CHANGELOG.md`](CHANGELOG.md) · +[`docs/releases/0.5.0rc3.md`](docs/releases/0.5.0rc3.md). + +## What's New in 0.2.1 + +OpenSquilla 0.2.1 is a maintenance release focused on release-package +startup and long-running agent reliability: + +- **Windows portable startup** — the portable launcher better detects and + bootstraps the Visual C++ runtime needed by the bundled ONNX router. +- **Long-running agent turns** — tool-heavy WebUI sessions recover more + cleanly from oversized tool results, malformed tool calls, artifact + delivery handoffs, and degraded final responses. +- **Cleaner WebUI output** — generated artifact markers are kept out of + normal chat replay while delivered files remain visible. +- **Memory recall scoring** — local and OpenAI-compatible embedding vectors + are normalized before semantic search, and strong keyword matches remain + usable when vector scores are low. + +Full notes: [`CHANGELOG.md`](CHANGELOG.md) · +[release notes](https://opensquilla.ai/news/). + +## What's New in 0.2.0 + +This release expands OpenSquilla across migration, CLI chat, channels, +scheduling, and long-running tool work: + +- **Migration path from existing agent homes** — `opensquilla migrate` previews + and applies imports from existing OpenClaw/Hermes homes, including memory, + persona files, skills, MCP/channel config, conflict handling, and migration + reports. +- **Usable chat CLI** — `opensquilla chat` has a stable terminal UI, streaming + output, queued input, slash-mode discovery, tool/status strips, and more + deterministic live prompt behavior. +- **Cross-surface cron automation** — cron jobs now cover structured schedules, + timezone-aware exact/every/cron runs, channel or webhook delivery, failure + destinations, manual runs, and WebUI/CLI/RPC parity. +- **Better Feishu and Discord channels** — channel adapters expose clearer + capability metadata, safer DM/group handling, native file and artifact paths, + and improved attachment/thread behavior while privileged actions stay scoped. +- **Sturdier long-running turns** — failed turns are kept out of provider + replay, malformed tool calls are handled more safely, and approval-gated + retries wait for operator decisions. +- **Smarter context and tool budgeting** — provider-budget compaction, prompt + cache preservation, bounded tool results, and side-effect-aware concurrency + make large tool-heavy sessions more predictable. +- **Web UI and release polish** — recency ordering, table layout, mobile + controls, duplicate notifications, setup forms, release URLs, and install + paths are tightened for 0.2.0. + +Full notes: [`CHANGELOG.md`](CHANGELOG.md) · +[release notes](https://opensquilla.ai/news/). + +--- + +## 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 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. | +| **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. OpenSquilla is an MCP client, and can also run as an MCP server — `opensquilla mcp-server run` needs the `mcp` extra (install `opensquilla[recommended,mcp]`). 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. | + +MetaSkill docs: [`docs/features/meta-skills.md`](docs/features/meta-skills.md), +[`docs/features/meta-skill-user-guide.md`](docs/features/meta-skill-user-guide.md), +and [`docs/authoring/meta-skills.md`](docs/authoring/meta-skills.md). + +--- + +## Benchmark Results + +PinchBench 1.2.1 average results across 25 tasks: + +| Agent | Base Model | Avg. score | Total input tokens | Total output tokens | Total cost | +| --- | ---: | ---: | ---: | ---: | ---: | +| OpenSquilla | Model router (Opus4.7, GLM5.1, DS4 Flash) | 0.9251 | 1,721,328 | 61,475 | $0.688 | +| OpenClaw | Claude Opus 4.7 | 0.9255 | 3,066,243 | 50,890 | $6.233 | + +Score is the mean across the 25 tasks; token counts and cost are +totals for the full run. + +--- + +## 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. + +

+ + OpenSquilla contributors + +

+ +--- + +## 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/opensquilla/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)