OmniBox

Point OmniBox's web search at SpecStream by changing one line in .env. The wizard's SearXNG search code stays as it is, and its Web Search tool runs on SpecStream's Search API, with no SearXNG instance to host.

SpecStream for OmniBoxAI assistants

What you need

A self-hosted OmniBox, started with Docker Compose from the omnibox repository. This guide follows release 0.1.56.
A SpecStream key. Get your key on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1
1. Set OBW_TOOLS_SEARXNG_BASE_URL in .env
In the .env you copied from example.env, replace the SearXNG address with SpecStream's, with your key in place of YOUR_SPECSTREAM_KEY. Give the address without /search: the wizard adds /search itself. Leave OBW_TOOLS_SEARXNG_ENGINES empty.
The address holds your key. Keep .env out of git and out of anything you share.
.env
OBW_TOOLS_SEARXNG_BASE_URL="https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY" OBW_TOOLS_SEARXNG_ENGINES=""

2. Restart the services

Run the start command from OmniBox's deploy guide again. Compose recreates the wizard and wizard-worker containers, which read .env, with the new address:

In the omnibox folder

docker compose -f compose.yaml -f compose/deps.yaml up -d

3. Ask with Web Search on

In an OmniBox chat, turn on Web Search in the chat tools, and ask about something recent:

In an OmniBox chat

What changed in the latest PostgreSQL release?

What changes and what stays

The wizard's search code, grimoire/retriever/searxng.py in wizard-common, is unchanged. It sends GET to the address plus /search, with q, pageno and format=json, and SpecStream answers in SearXNG's JSON shape: results[] with url, title and content, the fields the wizard turns into citations. publishedDate is empty on most results, so most citations carry no date.

Why a public SearXNG instance fails

OmniBox's example.env holds https://searxng.example.com, a placeholder. SearXNG's own docs say a format that is not turned on in settings.yml returns 403 Forbidden, and that many public instances have these formats disabled. The wizard asks for JSON. When the call fails, it logs a warning, tries three times in all, and the chat gets no web results.

With SpecStream, the JSON reply needs nothing turned on, and the search runs on SpecStream's servers. The Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions; scores and method are on the benchmarks page.

If Bing or DeepSeek search is set too

The wizard races up to three searches with staggered starts: Bing through a playwright server when OBW_TASK_SCRAPE_BASE_URL is set, DeepSeek when it has a key, then SearXNG. OmniBox's example.env sets neither, so SpecStream is the only web search. If you add them, SpecStream's search starts 2 seconds after the question, or as soon as the search before it fails, and the first one with results wins.

What each search costs

The SearXNG address runs the Search API's fast tier: $1 per 1,000 searches of up to 10 results. Each search comes out of your balance, with no quote and no approval. A call that returns no results costs nothing, and every call, charged or not, is in your account's request log.

Limits and errors

When the account has used its calls for the minute, SpecStream answers 429 with Retry-After. The wizard counts it as an empty search and tries again a second later, up to three times in all.
No web results in the chat: check the key in the address, then read the wizard's log with docker compose -f compose.yaml -f compose/deps.yaml logs wizard. The search warning there carries the error.
If the log still shows the old address, the containers were not recreated. Run the start command again.

Go back

Set OBW_TOOLS_SEARXNG_BASE_URL back to your SearXNG instance and run the start command again. Questions: [email protected].

SpecStream for OmniBox covers what it does in OmniBox on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].