Quickstart

This guide gets OpenSquilla installed, configured, and running locally. It assumes you want the standard product experience: terminal commands, local Web UI, SquillaRouter, memory/search support, and safe local defaults.

Requirements

Python 3.12 or newer for terminal installs.
uv for the recommended terminal install.
Git, Git LFS, Node.js 22.12+, and npm only when installing or developing from source.
A provider API key unless you use a local provider such as Ollama.

Recommended Install

Install the current release wheel with the recommended extras:

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

The recommended extra includes SquillaRouter dependencies and memory/search support used by the default product experience.

If opensquilla is not found after install, open a new shell or run:

uv tool update-shell

First-Run Setup

Interactive setup:

opensquilla onboard

Script-friendly setup:

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

Useful variants:

opensquilla onboard --if-needed
opensquilla onboard --minimal
opensquilla onboard --provider openai --api-key-env OPENAI_API_KEY
opensquilla onboard --provider ollama --model llama3.1

--if-needed is safe for install scripts because it avoids rewriting an already-ready setup. --minimal configures the provider path and skips optional channels/search/image-generation sections.

Check onboarding state:

opensquilla onboard status

Run the Gateway

Foreground gateway:

opensquilla gateway run

Background gateway with readiness wait:

opensquilla gateway start --json
opensquilla gateway status

Default address:

http://127.0.0.1:18791/control/

The gateway defaults to loopback for safety. To bind elsewhere, opt in:

opensquilla gateway run --listen 0.0.0.0 --port 18791

Only expose a non-loopback gateway behind appropriate auth and network controls.

First Useful Run

Open the Web UI:

http://127.0.0.1:18791/control/

Start terminal chat:

opensquilla chat

Run one automation turn:

opensquilla agent -m "Inspect this workspace and suggest a test plan"

Run a one-shot task in a specific workspace:

opensquilla agent \
  --workspace /path/to/project \
  --workspace-strict \
  -m "Review the current diff and list the highest-risk changes"

Use the Web UI for browser-based chat, approvals, setup, channels, usage, and logs. Use opensquilla chat when you want a terminal conversation. Use opensquilla agent for one-shot automation.

Resume Work

Resume a terminal chat session:

opensquilla chat --session <session-key>

Inspect sessions:

opensquilla sessions list
opensquilla sessions show <session-key>
opensquilla sessions export <session-key>

Export a session when exact history matters for debugging or handoff.

Check Readiness

Run these after setup:

opensquilla doctor
opensquilla providers list
opensquilla search list
opensquilla channels types --json

If the gateway is running, inspect runtime status:

opensquilla gateway status
opensquilla providers status
opensquilla channels status
opensquilla memory status

For provider/model selection details, see providers-and-models.md. For search setup, see search.md.

For gateway lifecycle, host/port, and exposure guidance, see gateway.md.

Stop or Restart

Foreground gateway:

Ctrl+C

Managed background gateway:

opensquilla gateway stop
opensquilla gateway restart

Next Steps

After the first run:

Configure search if you want web research: search.md.
Enable channels if you want Slack, Telegram, Feishu/Lark, or another messaging surface: channels.md.
Review memory behavior if you want durable recall: features/memory.md.
Review tool permissions before unattended automation: tools-and-sandbox.md.
Learn SquillaRouter if you want cost-aware model routing: features/squilla-router.md.
Use the glossary if product terms are unfamiliar: glossary.md.

Install From Source

Use source install when you want a checkout-backed install:

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

The source installer runs npm ci and builds the Vue control console before installing Python. Official release wheels and Desktop installers already contain that console and do not require Node.js or npm.

For development, use the repository virtual environment:

cd opensquilla-webui
npm ci
npm run build
cd ..
uv sync --extra recommended --extra dev
uv run opensquilla --help
uv run opensquilla gateway run

When developing from source, prefix commands with uv run so they use the checkout you are editing. Rebuild after changing Web UI sources. Standard wheel and sdist builds reject a missing or stale console; backend-only editable uv sync remains available without it.

Direct pip install ., uv tool install ., and VCS URL installs are low-level source-build paths. A local checkout must have a verified Web UI artifact first, while a VCS URL checkout has none; use the source installer or an official release wheel instead.

Docs index · Product guide · Improve this page · Report a docs issue