# 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: ```sh 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 ```sh opensquilla onboard ``` Common options: ```sh 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: ```sh 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 duckduckgo opensquilla configure search --search-provider tavily --api-key-env TAVILY_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 | Need | Preferred command | | --- | --- | | First setup | `opensquilla onboard` | | CI or install scripts | `opensquilla onboard --if-needed` | | Change provider | `opensquilla configure provider ...` | | Enable or disable routing | `opensquilla configure router ...` | | Configure web search | `opensquilla configure search ...` | | Configure messaging platforms | `opensquilla configure channels` | | Inspect current values | `opensquilla config get` | | Persist an advanced key | `opensquilla config set --config ` | ## Tool Policy Advanced scripted runs can narrow the model-visible tool surface with `[tools]`. To compare tool surfaces across otherwise identical runs, keep the calling harness unchanged and express the tool difference in config: ```toml [tools] profile = "coding" also_allow = ["retrieve_tool_result"] deny = ["execute_code", "background_process", "process"] file_edit_requires_fresh_read = true file_edit_flexible_recovery = true ``` `profile = "coding"` keeps filesystem, search, shell, session, and memory tools available, and enables fresh `read_file` context before existing workspace file edits. The `deny` list above removes the extra Python/background process surfaces for a narrowed run; omit it for the default coding surface. `file_edit_flexible_recovery` defaults to `true`: after an exact `old_text` miss, `edit_file` may apply a unique whitespace/indentation recovery and records used or rejected recovery events for diagnostics. ## Provider Configuration Inspect provider support: ```sh opensquilla providers list opensquilla providers configure openrouter opensquilla providers status ``` Onboarding-verified providers include: - TokenRhythm - 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`](providers-and-models.md) ## Router Configuration Router modes: | Mode | Use when | | --- | --- | | `recommended` | You want the selected provider's default routing profile. | | `openrouter-mix` | You want OpenRouter mixed-model defaults. | | `disabled` | You want one configured provider/model for every turn. | Commands: ```sh 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`](features/squilla-router.md) before using direct model runs for evaluation. ## Search Configuration Inspect search providers: ```sh opensquilla search list opensquilla search status opensquilla search query "OpenSquilla release notes" ``` Configure search: ```sh opensquilla configure search --search-provider duckduckgo opensquilla configure search --search-provider bocha --api-key-env BOCHA_SEARCH_API_KEY opensquilla configure search --search-provider brave --api-key-env BRAVE_SEARCH_API_KEY opensquilla configure search --search-provider tavily --api-key-env TAVILY_API_KEY opensquilla configure search --search-provider exa --api-key-env EXA_API_KEY opensquilla configure search --search-provider iqs --api-key-env IQS_SEARCH_API_KEY ``` Runtime-supported search providers in this build include DuckDuckGo, Bocha, Brave Search, Alibaba Cloud IQS, Tavily, and Exa. DuckDuckGo is the no-key path. A partial-key setup can configure only one keyed provider; an all-key setup can expose `BOCHA_SEARCH_API_KEY`, `BRAVE_SEARCH_API_KEY`, `IQS_SEARCH_API_KEY`, `TAVILY_API_KEY`, and `EXA_API_KEY` so runtime provider selection can choose by mode and capability unless a request names an explicit provider. `search_provider` is the credential anchor for `search_api_key` and `search_api_key_env`; it is not a hard routing promise for automatic searches. Additional provider metadata may be present for future or not-yet-runtime-supported integrations. Read: [`search.md`](search.md) ## Channel Configuration List supported channel types: ```sh 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: ```sh opensquilla gateway restart opensquilla channels status --json ``` See [`channels.md`](channels.md) for details. ## Attachments Attachment ingestion accepts **any file type**. Rendered families (images, PDF, text, Office documents, email) are extracted or inlined for the model; everything else is an *opaque* attachment: the bytes are staged into the agent workspace for tool access and are never parsed, decompressed, or inlined into a provider prompt. ```toml [attachments] # Admit opaque (non-rendered) attachment types: archives, binaries, # audio/video, unknown formats. false restores the legacy fail-closed # rendered-types-only admission gate on every surface. accept_opaque = true # Per-file ceiling for opaque attachments (bytes). opaque_max_bytes = 31457280 # 30 MiB # Aggregate RAM ceiling for the in-memory staged-upload store. When reached, # new uploads get HTTP 507 UPLOAD_STORE_FULL (retryable; staged entries # expire within the 10-minute TTL); a payload larger than the cap itself is a # permanent 413. Non-positive or invalid values fall back to the default — # this cap can be raised but not disabled. Requires a gateway restart. upload_store_max_total_bytes = 314572800 # 300 MiB # Disk budget for attachment copies materialized into an agent workspace # (/.opensquilla/attachments). When exceeded, new materializations # degrade to an unavailable marker; existing files are never evicted. Set to # 0 (or any non-positive value) to disable the budget entirely. workspace_attachment_disk_budget_bytes = 1073741824 # 1 GiB # Persist attachment bytes with session transcripts. persist_transcripts = true # media_root = "" # default: resolved from the cache dir transcript_disk_budget_bytes = 2147483648 # 2 GiB artifact_max_bytes = 31457280 # 30 MiB artifact_disk_budget_bytes = 536870912 # 512 MiB ``` Env overrides use the `OPENSQUILLA_ATTACHMENTS_` prefix (`OPENSQUILLA_ATTACHMENTS_ACCEPT_OPAQUE`, `OPENSQUILLA_ATTACHMENTS_OPAQUE_MAX_BYTES`, …). Size policy at a glance: inline attachments up to 2 MB ride the RPC message; larger files stage through `POST /api/v1/files/upload` (10-minute TTL) up to 30 MiB per file for text (whole-payload UTF-8 proven), PDF, Office, and opaque types. Email is always capped at the 2 MB text limit and never stages. Per turn: at most 10 attachments and 60 MiB total. Behavior notes: - With `accept_opaque = true` (the default), the upload endpoint no longer returns HTTP 415 `UNSUPPORTED_MEDIA_TYPE` for unrendered types, and `sessions.send` no longer rejects them; strict deployments that disable the flag keep the legacy errors and codes unchanged. - Opaque files reach the model only as an escaped metadata envelope plus a workspace path marker; the agent inspects or converts them with filesystem, shell, or code tools under the active safety tier and approval policy. On platforms without a sandbox backend those tool actions rely on approvals. ## Memory Configuration Useful commands: ```sh opensquilla memory status opensquilla memory index opensquilla memory list opensquilla memory search "project preference" opensquilla memory show opensquilla memory dream opensquilla memory flush-session ``` Configure embedding behavior: ```sh 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`](features/memory.md) ## Sandbox and Permissions Inspect or change posture: ```sh opensquilla sandbox status opensquilla sandbox on opensquilla sandbox full opensquilla sandbox bypass opensquilla sandbox reset ``` Single-shot automation permissions: ```sh 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: ```sh 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`](tools-and-sandbox.md) ## Outbound URL Filtering And Fake-IP DNS URL-fetching tools validate resolved addresses through the shared SSRF guard in `opensquilla.tools.ssrf`. Private, loopback, link-local, and reserved ranges are blocked by default. Some trusted proxy or fake-IP DNS setups resolve public hostnames such as `github.com` to addresses in the RFC 2544 benchmark range `198.18.0.0/15`. OpenSquilla keeps blocking those addresses unless the operator explicitly opts in: ```toml [tools] trusted_fake_ip_cidrs = ["198.18.0.0/15"] ``` Only subnets of `198.18.0.0/15` are accepted in this setting. Loopback, RFC 1918 private ranges, link-local addresses, and other internal ranges remain hard-blocked even if configured. If a public hostname resolves to one of those hard-blocked ranges, fix the DNS or proxy setup instead of bypassing the guard. ## Gateway Binding Foreground: ```sh opensquilla gateway run --listen 127.0.0.1 --port 18791 ``` Managed: ```sh 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: ```sh opensquilla doctor opensquilla gateway status ``` --- [Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)