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