OpenSquilla智能代理框架

Prerequisites

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). OpenSquilla keeps running with direct single-model routing until it is installed.

On macOS terminal installs, SquillaRouter's LightGBM runtime may also need the system OpenMP library. The desktop app bundles the runtime it needs, but Quick terminal install does not install Homebrew/system libraries. If startup logs `Library not loaded: @rpath/libomp.dylib, run brew install libomp`, then restart the gateway. OpenSquilla keeps running with direct single-model routing until it is installed.

Install links: Git · Git LFS · Node.js · uv.

Installation

OpenSquilla runs on Windows, macOS, and Linux. Pick the path that matches your use case.

Desktop installers and Quick terminal install give you a prebuilt release — no Git required. The other two — Install from source and Develop from source — build from a Git checkout (git clone + Git LFS), including the Vue control console. Release wheels and Desktop installers already contain that console, so their users do not need Node.js or npm.

Release install commands use published GitHub release assets. Python wheel installs use versioned wheel filenames because installers validate the version embedded in the wheel filename.

For 0.5.4 desktop use, prefer the packaged desktop installers from the GitHub Release: OpenSquilla-0.5.4-mac-arm64.dmg on macOS and OpenSquilla-0.5.4-win-x64.exe on Windows.

Desktop installers

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

• macOS Apple Silicon: <https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/OpenSquilla-0.5.4-mac-arm64.dmg>
• Windows x64: <https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/OpenSquilla-0.5.4-win-x64.exe>

For faster Mainland China downloads, use the OSS direct-download aliases: - macOS Apple Silicon: <https://opensquilla-releases.oss-cn-beijing.aliyuncs.com/releases/latest/OpenSquilla-mac-arm64.dmg> - Windows x64: <https://opensquilla-releases.oss-cn-beijing.aliyuncs.com/releases/latest/OpenSquilla-win-x64.exe>

These fixed links advance only after a newer eligible release passes mirror verification. Use the versioned GitHub Release links above when you need a specific release.

Quit any running OpenSquilla desktop app before upgrading. On macOS, drag the app from the DMG into Applications for installation or updates, eject the DMG, then open the Applications copy. The existing Desktop profile in the platform application-data directory is reused. A terminal installation's ~/.opensquilla is a separate profile; transfer it explicitly from Settings only if needed.

When upgrading the Windows Desktop from RC3 to RC4 or later, run the new installer directly over the existing installation. Do not uninstall RC3 first: its uninstaller may remove Desktop user data. Back up %APPDATA%\OpenSquilla before upgrading. RC4 and later installers preserve profile data during a normal uninstall.

Code signing policy: docs/code-signing-policy.md.

[!NOTE] The published v0.5.4 Windows installer remains unsigned. The current Release Assets workflow Authenticode signs new Windows installers as Beijing TokenRhythm Technologies Co., Ltd. SmartScreen reputation can still take time to build for a new publisher or application. If enterprise policy blocks the Desktop app, use Quick terminal install 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.

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

Linux / macOS:

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

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

uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-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 if the router runtime reports a native-library load error.

3. Configure and run.

opensquilla onboard
opensquilla gateway run

[!NOTE] If opensquilla is not found right after a fresh uv install, open a new terminal, or re-run the PATH line from step 1.

For a fully pinned install, use the versioned wheel URL: https://github.com/TokenRhythm/opensquilla/releases/download/v0.5.4/opensquilla-0.5.4-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 instead if you intend to modify the code.

1. Clone with LFS assets

   git lfs install
   git clone https://github.com/TokenRhythm/opensquilla.git
   cd opensquilla
   git lfs pull --include="src/opensquilla/squilla_router/models/**"
   

1. Run the installer

macOS / Linux

   bash scripts/install_source.sh
   

Windows PowerShell

   powershell -ExecutionPolicy Bypass -File ./scripts/install_source.ps1
   

The script installs .[recommended] (SquillaRouter + memory + local models) into a dedicated user environment via uv tool install. Before the Python install, it runs npm ci and npm run build in opensquilla-webui. Every source reinstall recreates the locked node_modules tree and rebuilds the console; the first run normally has the largest dependency download, while a warm npm cache reduces later network use but not all build time or disk writes. It then installs the built console with the Python package, falling back to python -m pip install --user when uv is unavailable. If opensquilla is not on PATH after install (common on a fresh host where ~/.local/bin is not yet on PATH), run uv tool update-shell and open a new terminal; see Troubleshooting for details.

Direct pip install ., uv tool install ., and VCS URL installs are low-level source-build paths, not substitutes for this installer. A local checkout works only after its Web UI has been built; a VCS URL checkout has no generated artifact and is intentionally rejected. Use this source installer or an official release wheel instead.

3. (optional) Install advanced extras. Most channels — Feishu, Telegram, DingTalk, QQ, WeCom, Slack, and Discord — work from the base install. The opt-in extras are:

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

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

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

1. Configure and run — see Configuration.

<details> <summary>Install from source — terminal prerequisites and installer options</summary>

Install prerequisites (Git, Git LFS, Node.js 22.12+ with npm, uv) from a terminal

Windows PowerShell:

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

macOS (Homebrew):

brew install git git-lfs node uv
git lfs install

Debian / Ubuntu:

sudo apt update && sudo apt install -y git git-lfs curl
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

On Fedora use sudo dnf install -y git git-lfs; on Arch use sudo pacman -S --needed git git-lfs; install Node.js 22.12+ and npm from your distribution or nodejs.org, then install uv with the curl command above. PATH changes from these installers apply to new terminal sessions.

Installer environment variables and PATH checks

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.

</details>

Uninstall

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

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:

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 for the full reference.

---

Installation Privacy

OpenSquilla uses pseudonymous installation telemetry to estimate install counts, version adoption, and runtime compatibility. Data is sent on first gateway startup and once per OpenSquilla version. It also records content-free daily aggregates of completed top-level conversations and token usage by UTC date, and attempts to upload pending cumulative UTC-day snapshots to the telemetry service at startup and once per hour. OpenSquilla may also make passive update checks, including automatic desktop update checks at startup and, while the app remains open, at most once per day. Uploads use a short timeout and never block startup.

See PRIVACY.md 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, version_seen, or daily_usage) - 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) - completed UTC day, conversation count, and aggregate input/output/cache/cache-write token counts for daily-usage events

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.

By default, requests sent directly to the official TokenRhythm HTTPS API may also carry the same pseudonymous, cross-session installation identifier in the optional X-OpenSquilla-Install-Id header. Only the exact official tokenrhythm.studio and api.tokenrhythm.studio HTTPS hosts on port 443 are eligible; custom proxies, OpenRouter, other providers, browser pages, redirected nonofficial targets, and returned image/CDN downloads are excluded. The raw MAC/IP values are never sent. The header is omitted if its background resolution is not ready or fails, so requests continue normally.

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:

OPENSQUILLA_PRIVACY_DISABLE_NETWORK_OBSERVABILITY=true

or set:

[privacy]
disable_network_observability = true

That unified switch covers automatic install telemetry, daily aggregate usage telemetry, passive update checks, and automatic desktop update checks at startup and during long-running app sessions, as well as the TokenRhythm installation header. Explicit update-availability checks remain disabled while the unified or legacy opt-out is active. CI and test environments also suppress the installation header and installation telemetry automatically. Other user-initiated actions may still contact network services after user intent, including release downloads and configured providers, search, or channels.

Legacy opt-out environment variables remain honored:

OPENSQUILLA_TELEMETRY_DISABLED=true
OPENSQUILLA_UPDATE_CHECK_DISABLED=true

The legacy telemetry opt-out suppresses the TokenRhythm installation header; the update-check opt-out by itself does not. TokenRhythm must treat the header as optional and untrusted, and must not use it for authentication, authorization, billing, rate limiting, or anti-abuse decisions. See PRIVACY.md for the complete target and data-handling rules.

Advanced deployments can use their own installation telemetry endpoint:

OPENSQUILLA_TELEMETRY_ENDPOINT=https://example.com/v1/install

---

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.

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

export OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

Windows 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):

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.

Configuration

Troubleshooting

<details> <summary>macOS desktop app keeps bouncing or reports AppTranslocation</summary>

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.

</details>

<details> <summary>macOS: <code>Library not loaded: @rpath/libomp.dylib</code></summary>

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:

brew install libomp
opensquilla gateway restart

</details>

<details> <summary>Windows: <code>DLL load failed</code> / Visual C++ runtime</summary>

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: <https://aka.ms/vs/17/release/vc_redist.x64.exe>. Then restore the recommended router:

opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router recommended
opensquilla gateway restart

</details>

---