> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/omnibox. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt

# 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](https://specstream.ai/integrations/omnibox.md)

## 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](https://specstream.ai/workspace/search?route=searxng&utm_source=omnibox&utm_medium=howto) on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

1.  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

    ```bash
    OBW_TOOLS_SEARXNG_BASE_URL="https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY"
    OBW_TOOLS_SEARXNG_ENGINES=""
    ```

2.  2

    ## 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

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

3.  3

    ## 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

    ```text
    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](https://specstream.ai/benchmarks.md).

## 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: [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for OmniBox](https://specstream.ai/integrations/omnibox.md) covers what it does in OmniBox on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).