Configuration

OpenSquilla can be configured from the onboarding wizard, the Web UI setup flow, CLI commands, environment variables, and TOML files. Use CLI commands for routine setup and edit TOML only for advanced or scripted deployments.

Config Load Order

OpenSquilla reads configuration in this order:

1. OPENSQUILLA_GATEWAY_CONFIG_PATH
2. ./opensquilla.toml
3. ~/.opensquilla/config.toml
4. built-in defaults

Use --config ./opensquilla.toml when you want to write or inspect a project-local config file.

Secret Handling

Prefer environment-variable references for secrets:

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

Avoid committing raw API keys to TOML files, shell history, examples, or issue reports.

First-Run Wizard

opensquilla onboard

Common options:

opensquilla onboard --if-needed
opensquilla onboard --minimal
opensquilla onboard --provider openrouter --api-key-env OPENROUTER_API_KEY
opensquilla onboard --provider openai --model gpt-5.4-mini --api-key-env OPENAI_API_KEY
opensquilla onboard --provider ollama --model llama3.1
opensquilla onboard status

The router mode defaults to recommended. Use --router disabled when you want direct single-model routing.

Reconfigure One Section

The configure command edits a selected section:

opensquilla configure provider --provider openrouter --api-key-env OPENROUTER_API_KEY
opensquilla configure router --router recommended
opensquilla configure router --router openrouter-mix
opensquilla configure router --router disabled
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY
opensquilla configure channels
opensquilla configure image-generation
opensquilla configure memory-embedding

Supported sections:

• provider
• router
• channels
• search
• image-generation
• memory-embedding

Configuration Decision Table

Provider Configuration

Inspect provider support:

opensquilla providers list
opensquilla providers configure openrouter
opensquilla providers status

Onboarding-verified providers include:

• OpenRouter
• OpenAI
• Anthropic
• Ollama
• DeepSeek
• Gemini
• DashScope / Qwen
• Moonshot AI
• Zhipu / Z.AI
• Baidu Qianfan
• Volcengine Ark

OpenSquilla also carries provider registry entries for additional OpenAI-compatible or self-hosted backends. Use opensquilla providers list on your install to see the current catalog.

Read: providers-and-models.md

Router Configuration

Router modes:

Commands:

opensquilla configure router --router recommended
opensquilla configure router --router openrouter-mix
opensquilla configure router --router disabled

Router-supported provider profiles depend on the installed build and configured provider. Read features/squilla-router.md before using direct model runs for evaluation.

Search Configuration

Inspect search providers:

opensquilla search list
opensquilla search status
opensquilla search query "OpenSquilla release notes"

Configure search:

opensquilla configure search --search-provider duckduckgo
opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY

Runtime-supported search providers in this build include Brave Search and DuckDuckGo. Additional provider metadata may be present for future or not-yet-runtime-supported integrations.

Read: search.md

Channel Configuration

List supported channel types:

opensquilla channels types --json
opensquilla channels describe feishu
opensquilla channels add telegram --name personal
opensquilla channels status

Channel saves update configuration. Restart the gateway after edits:

opensquilla gateway restart
opensquilla channels status <name> --json

See channels.md for details.

Memory Configuration

Useful commands:

opensquilla memory status
opensquilla memory index
opensquilla memory list
opensquilla memory search "project preference"
opensquilla memory show <path>
opensquilla memory dream
opensquilla memory flush-session <session-key>

Configure embedding behavior:

opensquilla configure memory-embedding

Memory can combine Markdown-backed sources with SQLite keyword and semantic indexes. The exact memory shape depends on the configured provider and local embedding support.

Read: features/memory.md

Sandbox and Permissions

Inspect or change posture:

opensquilla sandbox status
opensquilla sandbox on
opensquilla sandbox full
opensquilla sandbox bypass
opensquilla sandbox reset

Single-shot automation permissions:

opensquilla agent --permissions restricted -m "Read the repo and summarize it"
opensquilla agent --permissions full -m "Make a local patch and run tests"

For unattended automation that must stay inside a workspace:

opensquilla agent \
  --workspace /path/to/project \
  --workspace-lockdown \
  --scratch-dir /path/to/project/.scratch \
  -m "Investigate and propose the smallest fix"

Read: tools-and-sandbox.md

Gateway Binding

Foreground:

opensquilla gateway run --listen 127.0.0.1 --port 18791

Managed:

opensquilla gateway start --json
opensquilla gateway status
opensquilla gateway stop
opensquilla gateway restart

Bind precedence:

1. --listen
2. --bind
3. OPENSQUILLA_LISTEN
4. OPENSQUILLA_GATEWAY_HOST
5. config host
6. 127.0.0.1

Raw Config Editing

For advanced settings, inspect opensquilla.toml.example and edit the active config file directly. Use CLI commands for routine provider, router, search, channel, and sandbox changes because they avoid common key-shape mistakes.

After changing files by hand, restart the gateway and run:

opensquilla doctor
opensquilla gateway status

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