v0.3.1 · Apache License 2.0 · Python 3.12+

Token-Efficient AI Agent Intelligence

Microkernel AI Agent — same budget, have your Agent do more, do it better.
Smart routing, persistent memory, secure sandbox, plus built-in search and local embeddings.

Quickstart GitHub

60-80%¹

Token Cost Savings

N+

Meta-skills

1-click

Migrate from OpenClaw / Hermes

10+

Channels Built-in

See It in Action

Quick demos showing how OpenSquilla solves real workflows

Windows portable install walkthrough

Short drama meta-skill

Paper writing meta-skill

Quickstart

Four paths to get started — pick the one that fits you

The fastest path on Windows — the zip ships a bundled CPython runtime, so no separate Python install is required.

Video tutorial

Watch the end-to-end install and configuration walkthrough.

Recorded on v0.2.1; the steps are essentially the same across versions.

Download and extract

Download the latest portable zip

Current preview package:

OpenSquilla-windows-x64-portable.zip

Extract to a writable folder such as Downloads or Documents.

Right-click Start OpenSquilla.cmd → Run as administrator

Start OpenSquilla.cmd Run as Admin

Keep the terminal window open — closing it stops the gateway.

Complete first-run setup and open the Web UI

The launcher opens onboarding before the gateway starts. On first run, choose a provider and paste the requested keys; later starts let you review or change the config.

Then open http://127.0.0.1:18791/control/ in your browser.

Preview builds are unsigned; administrator launch is the supported path. If SmartScreen appears, choose More info → Run anyway. If Smart App Control or enterprise policy blocks the unsigned app, use Quick terminal install instead.

Advanced portable usage

Use these options only when you want scripted setup or portable CLI commands.

Provide an OpenRouter key before first start:

# Launcher writes an env-reference config and starts the gateway directly
> $env:OPENROUTER_API_KEY="sk-..."
> Set-ExecutionPolicy -Scope Process Bypass
> .\start.ps1

When OPENROUTER_API_KEY is set and no local config exists, the launcher writes an OpenRouter env-reference config and starts the gateway without prompting for the key. Without the variable, the onboarding wizard lets you choose any provider freely.

The portable zip does not install a global opensquilla command. For a terminal where opensquilla ... commands work, run OpenSquilla Shell.cmd, or call the bundled launcher directly via .\opensquilla.cmd:

# Example: configure OpenRouter from the extracted folder
> .\opensquilla.cmd onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

Portable troubleshooting

If Windows blocks the launcher, make sure the zip came from the official GitHub Releases page, then use the Windows prompt to allow it.
If the Web UI does not open, keep the gateway terminal open and visit http://127.0.0.1:18791/control/ manually.
If opensquilla is not recognized, use OpenSquilla Shell.cmd or .\opensquilla.cmd from the extracted folder.

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.

Install uv

Skip if uv --version already works.

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

Install OpenSquilla

The same command on every platform.

$ uv tool install --python 3.12 "opensquilla[recommended] @ https://github.com/opensquilla/opensquilla/releases/download/v0.3.1/opensquilla-0.3.1-py3-none-any.whl"

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 (ONNX Runtime, LightGBM, NumPy, tokenizers).

Configure and run

# Interactive onboarding wizard
$ opensquilla onboard

# Start ASGI server
$ opensquilla gateway run

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

Wheel URLs are versioned by design — installers validate the version in the filename. The command above pins to v0.3.1.

Prerequisites: Git · Git LFS · uv

If uv is unavailable, the installer falls back to Python 3.12+ with pip ≥ 23.

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 install

macOS (Homebrew)

brew install git git-lfs uv
git lfs install

Debian / Ubuntu

sudo apt update
sudo apt install -y git git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

Fedora

sudo dnf install -y git git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

Arch

sudo pacman -S --needed git git-lfs
curl -LsSf https://astral.sh/uv/install.sh | sh
git lfs install

Clone with LFS

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

Git LFS pulls bundled ML routing models. The pull is idempotent — it fetches missing assets and exits quietly when the checkout is already complete.

Run the installer

# Installs .[recommended] via uv tool install (falls back to pip --user)
$ bash scripts/install_source.sh

Most channels work from the base install. Optional extras: matrix, matrix-e2e, document-extras — pass via OPENSQUILLA_INSTALL_EXTRAS=matrix (bash) or -Extras matrix (PowerShell).

Configure (interactive wizard)

$ opensquilla onboard

Walks you through model providers, channels, and security policies. Use the installed opensquilla command — do not prefix with uv run unless you chose Develop from source.

Run the Gateway

# Start ASGI server (default 127.0.0.1:18791)
$ opensquilla gateway run

Then visit http://127.0.0.1:18791/control/ to open the control panel.

On Windows without the Visual C++ Redistributable, the gateway still starts; the bundled router falls back to a safe direct route.

Use this path only to modify, test, or debug the current checkout. Unlike Install from source, this path requires uv: uv sync creates a checkout-local .venv and uv run executes against the live source tree.

# Create the checkout-local .venv with recommended + dev extras
$ uv sync --extra recommended --extra dev

# Verify the install
$ 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: uv sync --extra recommended --extra dev --extra matrix

In this mode, prefix every opensquilla command with uv run. Do not debug a development checkout through a user-local opensquilla command — that command runs in a different Python environment.

Open the contributor guide on GitHub

For advanced usage, visit GitHub repo

Deploy Once, Reach Everywhere ³

Configure one Agent, serve users across multiple channels

Terminal Web Slack Discord Telegram MS Teams Matrix Lark DingTalk WeCom QQ

Every Token Spent Where It Matters

OpenSquilla makes your Agent spend less, remember more, and run safer.

💰

Cost Optimization

Multiple strategies coordinated to maximize every Token

Smart Routing ²

Like ride-sharing — simple questions take the bus (cheap models), complex ones get the premium ride (top models). The system decides.

Hybrid Feature Analysis

Combines hand-crafted features (length, language, code blocks, keywords) with embedding-based semantic features to assess complexity and pick the right model.

Reasoning Depth Tiers

Disables reasoning billing for simple queries, only enabling deep thought for complex ones — no paying reasoning Tokens for "hello".

Adaptive Prompts

Auto-tunes the prompt based on task complexity — telling the model how deeply to think. Light for simple, full power for complex.

On-Demand Skills

No dumping all capabilities into context. Only loads what's needed for the current task to avoid Token waste.

🪄

MetaSkills Protocol

A meta-protocol that tells the Agent how to retrieve, filter, compose — and even evolve — skills at scale

Self-Organizing

Multi-step work becomes reusable, inspectable workflows. Composition parsing, step scheduling, and proposal gates — recipes you trust to run.

meta-skill-creator

A bundled MetaSkill that turns recurring multi-skill collaborations into proposed new MetaSkills — the Agent grows its own catalog by running it.

N+ Community Skills

The Agent autonomously discovers, ranks, and invokes Skills from the community catalog — no manual picking, the right one just gets loaded.

10+ Bundled MetaSkills

Curated MetaSkills out of the box — research-to-report, paper drafting, job-search prep, project planning, short-drama production, and more high-quality workflows, ready to run.

Replay & Dream Mode

Every workflow execution leaves an auditable, replayable trail. While you are idle, OpenSquilla revisits those traces, distills usage patterns, and drafts candidate MetaSkills — capability grows in the background.

🧠

Human-Like Memory

Four-tier cognitive architecture — gets smarter the more you use it

Four-Tier Memory Structure

Working memory (current task) → Episodic (experience & causality) → Semantic (facts & rules) → Raw (audit & retraining base) — mirrors human cognition.

Hybrid Search + Local Embeddings

Vector semantic + full-text keyword search side by side. Bundled ONNX inference runs on CPU — embeddings stay on your machine, optionally swap to OpenAI / Ollama.

Hot Memory Promotion

Frequently recalled memories auto-bubble to the top. The more useful, the more accessible. Cold memories naturally sink.

Temporal Decay

Dated memories fade exponentially over time, while items marked "evergreen" stay sharp forever.

Memory Dream Consolidation

Every 24 hours, the AI "dreams" — consolidating scattered memories into structured knowledge. Just like sleep consolidates human memory.

🛡️

Security Sandbox

Let your Agent take action — without fearing what it might do

Three-Tier Policy

Standard runs directly, Strict requires sandbox approval, Locked enforces human review — risk-based escalation.

Real Sandbox Isolation

Bubblewrap on Linux, Seatbelt on macOS — code executes in isolated environments, never touching your real files.

Denial Ledger

Three rejections in a row? AI auto-pauses. Stops "brute-force" attempts to bypass security policies.

Stale Output Protection

Rejected operation results are immediately purged — AI can't use "read previous output" as a side-channel.

Prompt Injection Defense

XML-escapes all skill metadata and tool results — closing common injection attack vectors.

Microkernel: Tiny Core, Vast Ecosystem

Inspired by OS microkernels — the core engine does the minimum: orchestration and state management. Everything else runs as plugins in "user space". Switch LLM providers? Implement a Protocol. Add new tools? 5 lines of code. Plugin crashes don't affect the core; core upgrades don't break plugins.

OpenSquilla Core Engine

Compact pipeline orchestrator · State machine · Fully async · Auto-rollback on errors

⚙️

engine/

State Machine

🤖

provider/

Multi-LLM Provider

🌐

gateway/

ASGI RPC Gateway

🧠

memory/

Multi-Tier Memory

📡

channels/

Channel Adapters

🔧

tools/ + mcp/

MCP-First Tools

🛡️

sandbox/

Security Sandbox

⏰

scheduler/

Task Scheduler

🧩

skills/

Skill Plugins

🎭

identity/

Identity & Prompts

Built-in

🔍 Search: Brave / DuckDuckGo 🧬 Local Embeddings: ONNX local inference (offline · data stays on-device) 🔌 Optional Embeddings: OpenAI / Ollama

Same Budget, Higher Intelligence Density

Side-by-side comparison with peer open-source Agent frameworks⁴

Dimension	OpenSquilla	OpenClaw	Hermes Agent
🏗️Architecture	✅ Microkernel with 5-layer separation, ultra-compact core orchestrator (~100 lines), all capabilities pluggable, auto-skip + rollback on errors	⚠️ Mature plugin ecosystem (dozens of extensions), clean boundaries but more layers	❌ Massive monolithic sync main loop (thousands of lines), all logic tightly coupled
💰Cost Optimization	✅ ML routing + reasoning depth tiers + prompt cache isolation + on-demand skills — multi-strategy savings of 60-80%	⚠️ Config-pinned primary + fallback chain, no content-aware selection	⚠️ Crude keyword + length heuristics, single routing strategy only
🪄MetaSkills Protocol	✅ Composable workflows + meta-skill-creator for self-authoring + 10+ bundled & N+ community Skills auto-retrieved + Dream Mode distills usage into new candidates while idle	⚠️ Prompt-driven skill chains, no meta-protocol layer, no self-evolution; new workflows live as docs, not first-class runtime objects	❌ No reusable workflow abstraction — multi-step work is re-prompted from scratch every session
💾Memory System	✅ Vector + keyword + dedup + temporal decay + hot memory promotion + auto schema migration	⚠️ Has decay / promotion / diversity reranking, but lacks four-tier cognitive structure & Memory Dream consolidation	⚠️ Keyword-only search, no vector semantics, requires external integration for semantic memory
🛡️Security Sandbox	✅ No Docker dependency — syscall-level CPU/memory/time isolation + 3-tier network control. Fits in serverless	⚠️ Docker optional with OpenShell as a lighter alternative, still heavier than syscall-level isolation	✅ Dangerous command approval + 6 execution environments (local/Docker/SSH etc)
💰Cost Tracking	✅ Actual cost per call out of the box, quota hooks for auto-throttling on overspend	✅ Built-in pricing table, cost written to session metadata	✅ Input/output/cache-read/cache-write/reasoning tokens tracked separately
📊Observability	✅ Decision logs store hashes, not raw text (compliance-friendly), every pipeline stage instrumented	✅ Native OpenTelemetry (as plugin), plug-and-play with Prometheus/Grafana	⚠️ SQLite session table + call counter, basic level
🧩Extension DX	✅ 5-line duck-typed class is a valid plugin — no base class, no SDK package, no manifest	⚠️ Implement interface in plugin-sdk + write manifest file	⚠️ Tools auto-register on import (implicit side effects)

🏗️Architecture

OpenSquilla

✅ Microkernel with 5-layer separation, ultra-compact core orchestrator (~100 lines), all capabilities pluggable, auto-skip + rollback on errors

OpenClaw

⚠️ Mature plugin ecosystem (dozens of extensions), clean boundaries but more layers

Hermes Agent

❌ Massive monolithic sync main loop (thousands of lines), all logic tightly coupled

💰Cost Optimization

OpenSquilla

✅ ML routing + reasoning depth tiers + prompt cache isolation + on-demand skills — multi-strategy savings of 60-80%

OpenClaw

⚠️ Config-pinned primary + fallback chain, no content-aware selection

Hermes Agent

⚠️ Crude keyword + length heuristics, single routing strategy only

🪄MetaSkills Protocol

OpenSquilla

✅ Composable workflows + meta-skill-creator for self-authoring + 10+ bundled & N+ community Skills auto-retrieved + Dream Mode distills usage into new candidates while idle

OpenClaw

⚠️ Prompt-driven skill chains, no meta-protocol layer, no self-evolution; new workflows live as docs, not first-class runtime objects

Hermes Agent

❌ No reusable workflow abstraction — multi-step work is re-prompted from scratch every session

💾Memory System

OpenSquilla

✅ Vector + keyword + dedup + temporal decay + hot memory promotion + auto schema migration

OpenClaw

⚠️ Has decay / promotion / diversity reranking, but lacks four-tier cognitive structure & Memory Dream consolidation

Hermes Agent

⚠️ Keyword-only search, no vector semantics, requires external integration for semantic memory

🛡️Security Sandbox

OpenSquilla

✅ No Docker dependency — syscall-level CPU/memory/time isolation + 3-tier network control. Fits in serverless

OpenClaw

⚠️ Docker optional with OpenShell as a lighter alternative, still heavier than syscall-level isolation

Hermes Agent

✅ Dangerous command approval + 6 execution environments (local/Docker/SSH etc)

💰Cost Tracking

OpenSquilla

✅ Actual cost per call out of the box, quota hooks for auto-throttling on overspend

OpenClaw

✅ Built-in pricing table, cost written to session metadata

Hermes Agent

✅ Input/output/cache-read/cache-write/reasoning tokens tracked separately

📊Observability

OpenSquilla

✅ Decision logs store hashes, not raw text (compliance-friendly), every pipeline stage instrumented

OpenClaw

✅ Native OpenTelemetry (as plugin), plug-and-play with Prometheus/Grafana

Hermes Agent

⚠️ SQLite session table + call counter, basic level

🧩Extension DX

OpenSquilla

✅ 5-line duck-typed class is a valid plugin — no base class, no SDK package, no manifest

OpenClaw

⚠️ Implement interface in plugin-sdk + write manifest file

Hermes Agent

⚠️ Tools auto-register on import (implicit side effects)

Who Benefits Most from OpenSquilla?

These scenarios get the highest ROI

🏢

On-Prem Deployment

Fully offline, data never leaves your network, ML routing runs locally

📋

Compliance & Audit

Three-tier policies + hashed decision logs + human approval gates

💸

Tight Budget, High Bar

Run more tasks for the same cost — smart routing picks the most cost-effective model

🧠

Agent That Gets You

Four-tier human-like memory accumulates context — never start from zero again

Limited-Time Free Token Offer

Free Tokens, Zero-Cost Trial

OpenSquilla is fully open source — pull from GitHub and self-host anytime.
But running LLMs still costs Tokens. We're giving you a starting Token credit so you can verify "OpenSquilla saves 60-80%" with zero risk.

10 seconds to fill out, no credit card required.

Claim Free Tokens

Have your own Tokens? Use the open-source version on GitHub

Apache 2.0 Open Source

No Credit Card

Priority Support

Limited Quantity · First Come First Served

Token-Efficient AI Agent Intelligence

See It in Action

Quickstart

Video tutorial

Download and extract

Right-click Start OpenSquilla.cmd → Run as administrator

Complete first-run setup and open the Web UI

Install uv

Install OpenSquilla

Configure and run

Clone with LFS

Run the installer

Configure (interactive wizard)

Run the Gateway

Deploy Once, Reach Everywhere 3

Every Token Spent Where It Matters

Cost Optimization

MetaSkills Protocol

Human-Like Memory

Security Sandbox

Microkernel: Tiny Core, Vast Ecosystem

Same Budget, Higher Intelligence Density

Who Benefits Most from OpenSquilla?

Free Tokens, Zero-Cost Trial

Deploy Once, Reach Everywhere ³