OpenSquilla Agent Gateway Setup Guide

TL;DR

TL;DR: OpenSquilla is a Python 3.12+ agent gateway and CLI with packaged release installs, optional SquillaRouter, onboarding commands, migration tools, background gateway mode, chat, one-shot agent execution, and explicit artifact-safety warnings.

Source and Accuracy Notes

This guide uses official material from opensquilla/opensquilla, especially the installation, configuration, gateway, migration, development, and third-party notices sections. Commands are copied from project docs only. Where the project gives multiple install paths, this article explains when each path fits instead of flattening them into one generic Python setup.

OpenSquilla is release-oriented. Windows portable, quick terminal install, source install, and developer checkout are different workflows with different assumptions. The project also calls out that router-related extras can pull heavy dependencies such as ONNX Runtime, LightGBM, NumPy, and tokenizers, so first install time and platform compatibility matter.

What Is opensquilla?

OpenSquilla is an AI agent runtime packaged as a Python application. It exposes a terminal command named opensquilla, an onboarding wizard, gateway server, chat REPL, one-shot agent command, provider configuration, migration tools, and optional routing/search/channel features. It targets Python 3.12+ but encourages uv so users do not have to manage system Python manually.

The repo’s most distinctive part is install discipline. It separates end-user release installs from source checkouts. Quick terminal install pulls a versioned wheel from GitHub Releases. Source install uses a checkout as installer source and then expects you to run the user-local opensquilla command. Developer mode uses a repository-local .venv and uv run. That separation reduces “works on my checkout” confusion.

Optional recommended extras install SquillaRouter, memory, and local model pieces. A lighter core profile leaves router pieces out. That makes OpenSquilla practical for two different users: someone who wants the full local routing stack, and someone who wants provider-driven agent behavior without large native dependencies.

Repo-Specific Setup Workflow

Step 1: Pick install path by machine type

Windows users who do not want Python tooling can use the portable release zip from GitHub Releases. It includes its own launcher and bundled Python. It does not install a global opensquilla command unless you use the provided shell wrapper.

For most terminal users on Windows, macOS, or Linux, quick terminal install is the recommended path. It installs a release wheel through uv, with Python handled by uv.

Step 2: Install uv if needed

macOS/Linux install command:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell install command:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a new terminal if PATH changes do not apply immediately.

Step 3: Install release wheel

The documented release install command pins Python 3.12 and installs the recommended extras from a GitHub Release wheel:

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

The project notes that a fully pinned install uses the same versioned wheel URL. First install can be large because recommended extras include router and ML dependencies.

Step 4: Run onboarding and gateway

After install, run first-run setup and start the gateway:

opensquilla onboard
opensquilla gateway run

For scripts and reinstalls, the onboarding command has safer variants:

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

Provider setup can be supplied directly. POSIX shell:

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

PowerShell:

$env:OPENROUTER_API_KEY="sk-or-..."
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY

Step 5: Configure provider, router, search, and channels

After onboarding, project docs show these configuration commands:

opensquilla configure provider --provider openai --model gpt-4o --api-key-env OPENAI_API_KEY
opensquilla configure router --router recommended
opensquilla configure search   --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
opensquilla configure channels

OpenSquilla reads configuration from ./opensquilla.toml, then ~/.opensquilla/config.toml, then built-in defaults. Project-local config can override user config for a repo-specific workspace.

Step 6: Use gateway, chat, and one-shot modes

OpenSquilla supports foreground gateway, background gateway, interactive chat, and automation-friendly one-shot agent execution:

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

If gateway state gets stale, restart command exists:

opensquilla gateway restart

Step 7: Use source install only when needed

Source install requires Git LFS because model assets may live under LFS paths:

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

Then run installer:

bash scripts/install_source.sh

Windows installer command:

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

Optional matrix extras:

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

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

Developer checkout is separate:

uv sync --extra recommended --extra dev
uv run opensquilla --help

With matrix extras:

uv sync --extra recommended --extra dev --extra matrix
uv run opensquilla channels status matrix --json

Deeper Analysis

OpenSquilla’s setup documentation is unusually careful about execution context. In normal use, do not debug a developer checkout through a user-local command. In developer mode, prefix commands with uv run. In source install mode, the checkout is installer input, not the runtime environment. This matters when diagnosing config, dependencies, and PATH.

The router profile is another important design point. recommended gives richer capability but adds native ML dependencies. If startup logs mention DLL load failed, the docs point toward Microsoft Visual C++ Redistributable on Windows. A minimal or core path can keep router off at runtime while preserving provider-driven operation.

Migration support also hints at intended users: people coming from OpenClaw or Hermes. The documented commands are:

opensquilla migrate openclaw --json
opensquilla migrate openclaw --apply
opensquilla migrate hermes --json
opensquilla migrate hermes --apply

That makes OpenSquilla less of a toy and more of a continuity project for existing agent setups.

Practical Evaluation Checklist

• Use quick terminal install first unless you specifically need portable Windows or source tracking.
• Confirm opensquilla --help works from a new terminal after uv tool install.
• Start with opensquilla onboard --minimal if you only need provider setup.
• Choose recommended only when SquillaRouter and memory/local model features are worth heavier dependencies.
• Keep project-local opensquilla.toml under review; it overrides user config.
• Test opensquilla gateway start --json before scripting around gateway readiness.
• Use uv run inside developer checkout; avoid mixing with user-local install.
• Verify Git LFS pulled router model assets before source install.

Security Notes

OpenSquilla may store provider configuration, route prompts through local or remote models, run gateways, and use bundled artifacts. The project’s third-party notices warn that .pkl and .joblib artifacts in SquillaRouter should be treated as executable-code-equivalent inputs. Load only trusted release assets or assets matching artifact_manifest.json checksums.

Keep provider API keys in environment variables named in config, not pasted into shared files. Bind gateway to intended interfaces only; documented foreground gateway uses 127.0.0.1:18791. Be careful with migrations from other agents because imported memory or config can contain sensitive content.

FAQ

Q: Should I use portable Windows or quick terminal install? A: Use portable if you want no Python tooling. Use quick terminal install if you want a global opensquilla command and normal terminal workflow.

Q: Why does recommended install take time? A: Recommended extras include SquillaRouter and native ML dependencies, so dependency resolution and downloads are larger than a core install.

Q: Can I run from a cloned repo? A: Yes for development with uv run; source install uses the clone only to install a user-local command.

Q: What port does gateway use? A: The documented foreground gateway runs on 127.0.0.1:18791.

Related reading: GitHub Trending tools, Developer tools, dulus setup guide open source python ai tool, and codexplusplus setup guide open source rust ai tool.

Conclusion

OpenSquilla rewards careful setup. Pick release install for normal use, source install for tracking main, and developer mode for code changes. Its strongest repo-specific feature is clear separation between packaged runtime, config layers, gateway modes, router extras, and migration paths. That clarity makes it a serious candidate for users who need a Python agent CLI/gateway without guessing how the runtime should be launched.