Opensquilla
OpenSquilla β Token-Efficient AI Agent with same budget, higher intelligence density
Ask AI about Opensquilla
Powered by Claude Β· Grounded in docs
I know everything about Opensquilla. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
OpenSquilla β Token-Efficient AI Agent
Overview
OpenSquilla is a token-efficient, microkernel AI agent β same budget,
more capability, better results. It combines smart routing, persistent
memory, a secure sandbox, built-in web search, and local embeddings
under a single model loop.
Every entry point β Web UI, CLI, and chat channels β runs through a
shared TurnRunner, and a pluggable provider layer lets it speak to
OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini, Qwen/DashScope,
and roughly twenty other LLM providers without changes to your code or
config schema.
Quick start
Choose the path that matches how you want to use OpenSquilla:
| User type | Path | Status |
|---|---|---|
| New user | Release package | Coming soon |
| Command-line user | Install from source | Available now |
| Developer | Develop from source | Available now |
SquillaRouter is included by default in every currently available install path.
Only choose the core profile or --router disabled if you intentionally want
to skip the bundled router.
Release package β coming soon
This will be the recommended path for non-developers: download a release package, extract it, set an API key, start OpenSquilla, and open the Web UI. Public release packages are not published yet. Until release packages are published, new users should use Install from source.
Install from source
Use this path when you want to run OpenSquilla as a local app from the current
source tree. The clone is only the package source the installer reads from; after
installing, use opensquilla ... commands, not uv run.
-
Install prerequisites: Git, Git LFS, and uv.
Download links:
- Git: https://git-scm.com/downloads
- Git LFS: https://git-lfs.com/
- uv: https://docs.astral.sh/uv/getting-started/installation/
Optional: install prerequisites from a terminal
Windows 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 installmacOS, if you already use Homebrew:
brew install git git-lfs uv git lfs installHomebrew is optional: https://brew.sh/. If you do not use Homebrew, use the download links above.
Debian / Ubuntu:
sudo apt update sudo apt install -y git git-lfs curl -LsSf https://astral.sh/uv/install.sh | sh git lfs installFedora:
sudo dnf install -y git git-lfs curl -LsSf https://astral.sh/uv/install.sh | sh git lfs installArch:
sudo pacman -S --needed git git-lfs curl -LsSf https://astral.sh/uv/install.sh | sh git lfs installOpen a new terminal if
git,git lfs, oruvis not found after installation. -
Clone with LFS assets:
git lfs install git clone https://github.com/opensquilla/opensquilla.git cd opensquilla git lfs pull --include="src/opensquilla/squilla_router/models/**" -
Install with the recommended profile. This creates a user-local
opensquillacommand. The checkout-local.venv, if any, is not used. The normal install commands above already install SquillaRouter.macOS / Linux:
bash install.shWindows PowerShell:
powershell -ExecutionPolicy Bypass -File .\install.ps1PowerShell 7 users can run
pwsh -ExecutionPolicy Bypass -File .\install.ps1.Optional: add a channel adapter only if you need one. For example, add Feishu websocket channel support with these full install commands:
Windows PowerShell:
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Extras feishumacOS / Linux:
OPENSQUILLA_INSTALL_EXTRAS=feishu bash install.shOnly set
OPENSQUILLA_INSTALL_PROFILE=coreif you intentionally want to skip the bundled router.Open a new terminal if
opensquillais not found after installation. -
Configure. Use the installed
opensquillacommand below. Do not prefix these commands withuv rununless you chose Develop from source.Recommended for beginners:
opensquilla onboardThe wizard asks you to choose a provider and enter or reference its API key.
For automation, this OpenRouter example is copy-pasteable. If you choose OpenRouter, create a key at https://openrouter.ai/docs/api-keys, then replace
sk-...with the real key value. Theexportand$env:examples below set the key for the current terminal only. OpenRouter is only an example; substitute any supported provider and its API key variable.macOS / Linux:
export OPENROUTER_API_KEY="sk-..." opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEYWindows PowerShell:
$env:OPENROUTER_API_KEY="sk-..." opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY -
Run the gateway:
opensquilla gateway run
Wait until the gateway says it is running before opening the Web UI at
http://127.0.0.1:18790/control/. Press Ctrl+C to stop the foreground
gateway. If Windows lacks the Visual C++ Redistributable, the gateway still
starts but the bundled router falls back to a safe direct route. If Windows
prints an onnxruntime or DLL load failed warning, see the Visual C++ runtime
note in Prerequisites.
Setup details and troubleshooting
Setup details expands the Quick start paths; it is not a separate install path. Use Install from source when you only want to run OpenSquilla. Use Develop from source only when you want to edit, test, or debug the code.
Sections marked (optional) can be skipped depending on your environment; everything else is required for a working source install.
Prerequisites
- Python 3.12+ β required only when you skip
uvand use thepip --userfallback, or when you develop from source. (optional) for portable-zip users, since the release zip already bundles its own CPython. - Git and Git LFS β required. The bundled SquillaRouter assets are
stored as LFS pointers; without
git-lfstherecommendedprofile fails withversion https://git-lfs.github.com/spec/v1pointer files in place of the model bytes. Install once: https://git-lfs.com/. uvβ recommended for normal source installs. The installer scripts useuv tool installwhen available. Install once: https://docs.astral.sh/uv/.pip>= 23 β fallback only whenuvis unavailable. The scripts fall back topython -m pip install --user.- Windows Visual C++ runtime β recommended when using the bundled router
on Windows.
install.ps1tries to install the Microsoft Visual C++ Redistributable for Visual Studio 2015-2022 (x64) withwingetwhen it is missing. If startup still printsDLL load failed while importing onnxruntime_pybind11_state, install it manually, then restart PowerShell: https://aka.ms/vs/17/release/vc_redist.x64.exe. Ifwingetis not present, download and run the Visual C++ installer manually. If you need to run while fixing the runtime, use the--router disabled --minimalworkaround in First-run config.
Clone the repo
git lfs install
git clone https://github.com/opensquilla/opensquilla.git
cd opensquilla
git lfs pull --include="src/opensquilla/squilla_router/models/**"
git lfs install is idempotent and safe to run again.
Install from source (detailed)
Use this path when you want to run OpenSquilla, not edit its source.
The clone is only the package source for the installer. After install,
use opensquilla ...; do not use uv run.
The scripts install .[recommended] by default. recommended is the
normal runtime profile: SquillaRouter, memory, and local model dependencies.
Messaging channel adapters are opt-in extras. Most users do not need
every chat platform SDK.
The install scripts default to the recommended profile, which installs
.[recommended]. That path includes SquillaRouter dependencies and checks the
bundled router model assets before installing. The only normal opt-out is the
core profile.
macOS / Linux:
bash install.sh
Windows PowerShell:
powershell -ExecutionPolicy Bypass -File .\install.ps1
PowerShell 7 users can run pwsh -ExecutionPolicy Bypass -File .\install.ps1.
Install channel extras into the same user-local command. Feishu is shown only as an example channel adapter:
Windows PowerShell:
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Extras feishu
macOS/Linux:
OPENSQUILLA_INSTALL_EXTRAS=feishu bash install.sh
Supported channel extras include dingtalk, feishu, matrix, matrix-e2e,
msteams, qq, telegram, and wecom. The optional non-channel extra is
document-extras.
The scripts prefer uv tool install and fall back to
python -m pip install --user. The installed command uses its own
Python environment; it is separate from a checkout-local .venv.
Useful install options:
$env:OPENSQUILLA_INSTALL_PROFILE="core" # minimal runtime
$env:OPENSQUILLA_INSTALL_DRY_RUN="1" # print the plan only
OPENSQUILLA_INSTALL_PROFILE=core bash install.sh
OPENSQUILLA_INSTALL_DRY_RUN=1 bash install.sh
To check which command your shell will run:
where.exe opensquilla
command -v opensquilla
If a new terminal still cannot find it, run uv tool update-shell, reopen the
terminal, and try again.
After reinstalling from a local checkout, restart the gateway process so it loads the updated package.
Develop from source
Use this path only when you want to modify, test, or debug the current
checkout. uv sync creates the checkout-local .venv, and uv run
executes against the live source tree.
uv sync --extra recommended
uv run opensquilla --help
The recommended extra includes SquillaRouter for development too. Use
uv sync without --extra recommended only when you are intentionally testing
a minimal environment.
Install extras into the same environment you run:
uv sync --extra recommended --extra feishu
uv run opensquilla channels status feishu --json
In this mode, prefix every command below with uv run. Do not debug a
development checkout through a user-local opensquilla command; that
command runs in a different Python environment.
First-run config
opensquilla onboard --if-needed is the recommended post-install
entrypoint for first-run setup and automation. It writes the active
config file, skips when an LLM provider is already configured, and keeps
provider secrets in environment variables when you pass --api-key-env.
The router defaults to recommended; recommended enables SquillaRouter for
supported provider profiles. Pass --router disabled only if you
intentionally want direct single-model routing, or --router openrouter-mix to keep the built-in OpenRouter mixed model routes.
Useful invocations:
opensquilla onboard # full interactive wizard
opensquilla onboard --if-needed # idempotent: skip if already configured
opensquilla onboard --minimal # provider only, skip channels/search
In SSH, CI, or any environment without a TTY the interactive flow exits with code 2. Use the non-interactive form β keep the secret in the environment and pass its name, not its value, to onboard:
export OPENROUTER_API_KEY="sk-..."
opensquilla onboard \
--provider openrouter \
--api-key-env OPENROUTER_API_KEY
For example, with OpenAI:
export OPENAI_API_KEY="sk-..."
opensquilla onboard --provider openai --api-key-env OPENAI_API_KEY
To persist the key on macOS or Linux, add the same export line to your shell
profile.
Windows PowerShell:
$env:OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
To persist the key for future PowerShell windows:
setx OPENROUTER_API_KEY "sk-..."
Close and reopen PowerShell after setx, then run:
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
If a Windows machine cannot initialize onnxruntime and logs
DLL load failed while importing onnxruntime_pybind11_state, OpenSquilla will
keep running with a safe router fallback, but the bundled router runtime is not
active until the Visual C++ runtime is fixed. To make a first install quiet and
direct while fixing the Windows runtime, use:
$env:OPENROUTER_API_KEY="sk-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router disabled --minimal
opensquilla gateway run
After installing the Visual C++ Redistributable and reopening PowerShell, restore
the recommended router. If you used only $env:OPENROUTER_API_KEY, set it again
in the new PowerShell window.
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY --router recommended
opensquilla gateway restart
(optional) Re-configure one section later without redoing the whole wizard:
opensquilla configure provider --provider openai --model gpt-4o
opensquilla configure router --router recommended
opensquilla configure search --search-provider brave
opensquilla configure channels # interactive section
Sections: provider, router, channels, search,
image-generation, memory-embedding. The Web UI also exposes a setup
flow at /control/setup for provider, router tiers, optional channels,
and extras. Later CLI edits should use `opensquilla configure
Messaging channel saves are config changes, not runtime connectivity proof. Restart the gateway process after channel edits, then verify the live adapter state:
opensquilla gateway restart
opensquilla channels status <name> --json
Treat a channel as connected only when the status payload reports
enabled=true, configured=true, and connected=true. Feishu defaults
to websocket mode and does not need a public URL in that mode; Feishu
webhook mode, Slack, WeCom, and Microsoft Teams require a public
provider-reachable URL.
Config load order: OPENSQUILLA_GATEWAY_CONFIG_PATH β
./opensquilla.toml β ~/.opensquilla/config.toml β built-in
defaults. Onboarding writes the file at the path the runtime would
read; environment values for individual secrets always win over file
values.
Run
opensquilla gateway run # foreground, 127.0.0.1:18790
opensquilla gateway start --json # background + health wait
opensquilla chat # interactive REPL
opensquilla agent -m "your prompt" # one-shot, automation-friendly
Open the Web UI at http://127.0.0.1:18790/control/ and check health
with curl http://127.0.0.1:18790/health.
Public network binding β (optional)
To make the Web UI reachable from another machine, bind the gateway to all interfaces and use the host's public IP address:
opensquilla gateway run --listen 0.0.0.0 --port 18790
# or, for a background process:
opensquilla gateway start --listen 0.0.0.0 --port 18790 --json
Then open http://<public-ip>:18790/control/ and verify the public
health endpoint with:
curl http://<public-ip>:18790/health
If another gateway is already bound to 18790, stop it first or choose
a different --port. Public access also requires the host firewall or
cloud security group to allow inbound TCP traffic on that port.
Do not expose the gateway publicly with [auth] mode = "none"; configure
token or password auth before binding to 0.0.0.0.
Docker and portable paths β (optional)
./start.sh (or start.ps1 on Windows) wraps docker compose up -d
and tails the gateway logs β convenient if you do not want a Python
toolchain on the host. Release zips that bundle a CPython runtime are
produced by the Wheelhouse Zip Release workflow; portable users
extract the zip and run its bundled launcher without a system Python
install.
Further tuning
Provider-specific config, tier profiles, sandbox tuning, image
generation, and concurrency settings are managed through
opensquilla onboard, opensquilla config, and
opensquilla.toml.example.
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 |
Key Features
- Token-efficient routing β local
SquillaRouter(LightGBM + ONNX BGE classifier,recommendedextra) routes each turn across four tiers (T0βT3). Hybrid features (length, language, code blocks, keywords + semantic embeddings) pick the cheapest model that can handle the turn; classification runs on-device, so your prompt never leaves the machine to make the decision. - Adaptive reasoning and prompts β reasoning-token billing only kicks in when the turn needs deep thought, and the system prompt scales with task complexity (lightweight for trivial turns, full instructions for complex ones). No paying reasoning tokens for "hello".
- On-demand skills β built-in MCP client plus 16 bundled skills (coding agents, GitHub, cron, deep research, pptx/docx/xlsx/pdf toolkits, summarization, tmux, weather, and more); only the skills needed for the current task are loaded into context, avoiding steady-state token waste.
- Four-tier cognitive memory β working (current task) β episodic (experience and causality) β semantic (facts and rules) β raw (audit and retraining base), mirroring human cognition.
- Hybrid memory search + local embeddings β Markdown source-of-truth
memory with FTS keyword search alongside
sqlite-vecsemantic recall. Bundled ONNX inference runs on CPU so embeddings stay on your machine; optionally swap to OpenAI- or Ollama-hosted embeddings. - Adaptive recall and consolidation β frequently used memories auto-promote and dated ones decay exponentially (with an "evergreen" opt-out); periodic Dream consolidation merges scattered episodic traces into structured knowledge, mirroring sleep consolidation, with bounded prompt-injection budgets throughout.
- Layered security sandbox β three policy tiers (Standard / Strict / Locked) on a permission-tier matrix, with Bubblewrap on Linux executing code in isolated environments (the macOS Seatbelt backend currently renders SBPL profiles only; process execution is pending). A denial ledger auto-pauses autonomous execution after repeated sandbox denials, rejected outputs are purged via intent + stale-output caches so the agent can't recover them through a side channel, and all skill metadata and tool results are XML-escaped to close common prompt-injection vectors.
- Unified gateway across all entry points β Starlette ASGI server on
127.0.0.1:18790with WebSocket RPC and an embedded control console (/control/). Web UI, CLI, and first-class adapters for Terminal, WebSocket, Slack, Telegram, Discord, Feishu, DingTalk, WeCom, MS Teams, Matrix, and QQ all converge on a sharedTurnRunnerfor consistent tool dispatch, retry, and decision logging. - 20+ LLM providers β OpenRouter, OpenAI, Anthropic, Ollama, DeepSeek, Gemini, DashScope/Qwen, Moonshot, Mistral, Groq, Zhipu, SiliconFlow, Volcengine, BytePlus, MiniMax, vLLM, LM Studio, OVMS, and more, with a primary-plus-fallback selector.
- Durable sessions, agents, and scheduling β SQLite-backed session,
transcript, and replay storage with per-agent workspaces and a
reset/flush contract that proves persistence before destructive rewrites;SchedulerEnginewith an in-treeCronExpressionparser plus stagger, reaper, and heartbeat services exposed via theopensquilla cronCLI.
Credits
OpenSquilla is a token-efficient AI Agent inspired by
OpenClaw. Bundled third-party content is fully attributed
in THIRD_PARTY_NOTICES.md.
Contributing
OpenSquilla is an open-source project and we welcome contributions of every kind β bug reports, feature ideas, documentation, new provider or channel adapters, skills, and core runtime work. Open an issue or a pull request on GitHub to get involved.
