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

# Farfalle

Point Farfalle's search at SpecStream by changing `SEARXNG_BASE_URL` in `.env`. Farfalle's own SearXNG provider stays as it is, and every search runs on SpecStream's Search API, so a Farfalle deploy needs no SearXNG container beside it.

[SpecStream for FarfalleAI assistants](https://specstream.ai/integrations/farfalle.md)

## What you need

-   Farfalle, run with `docker-compose -f docker-compose.dev.yaml up -d` or deployed with its Render and Vercel buttons.
-   A SpecStream key. [Get your key](https://specstream.ai/workspace/search?route=searxng&utm_source=farfalle&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 SEARXNG\_BASE\_URL in .env

    In Farfalle's `.env`, keep `SEARCH_PROVIDER=searxng` and replace the SearXNG address with SpecStream's, with your key in place of `YOUR_SPECSTREAM_KEY`. Give the address without `/search`: Farfalle adds `/search` itself.

    Farfalle sends no key header to SearXNG, so the key goes in the address. The address then holds your key: keep `.env` out of git and out of anything you share.

    .env

    ```bash
    SEARCH_PROVIDER=searxng
    SEARXNG_BASE_URL=https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY
    ```

2.  2

    ## 2. Restart the backend

    `docker-compose.dev.yaml` passes `SEARCH_PROVIDER` and `SEARXNG_BASE_URL` from `.env` to the backend container. Run the same command again, and Compose recreates the backend with the new address:

    Shell

    ```bash
    docker-compose -f docker-compose.dev.yaml up -d
    ```

3.  3

    ## 3. Ask a question

    Open `http://localhost:3000` and ask something recent. The answer cites the pages SpecStream found, and Farfalle shows images from the same search.

## On Render, or any host without SearXNG

Farfalle's Render blueprint sets `TAVILY_API_KEY`, `OPENAI_API_KEY` and `GROQ_API_KEY`, while Farfalle's search falls back to `searxng` when `SEARCH_PROVIDER` is not set. A fresh deploy then answers every question with `SEARXNG_BASE_URL is not set in the environment variables.`

In the Render service's environment, add `SEARCH_PROVIDER` with the value `searxng` and `SEARXNG_BASE_URL` with SpecStream's address and your key, as in `.env` above. The backend searches with no SearXNG server to run.

## What changes and what stays

Farfalle's search code, `src/backend/search/providers/searxng.py`, is unchanged. For each search it sends two `GET` calls to the address plus `/search`: one with `q` and `format=json` for the web results, and one with `categories=images` for the images. SpecStream answers both in SearXNG's JSON shape: `results[]` with `title`, `url` and `content`, and `img_src` on image results. Farfalle keeps the first 6 web results and the first 4 images.

The local `searxng` service in `docker-compose.dev.yaml` is no longer on the search path. The backend still lists it under `depends_on`, so leave it in the file or remove both lines together.

## Expert search

With **Expert Mode** on, Farfalle plans up to 4 steps and runs each step's queries at the same time. Every query is one Farfalle search, so one web call and one image call.

## What each search costs

The web call is one Search API call on the fast tier: $1 per 1,000 searches of up to 10 results, a fifth of the default search's $5.

The image call asks for SearXNG's image page, which holds up to 100 results. It is charged as a fast search of the results it returns, by started block of 10, so a full page of 100 images costs as a fast search of 100 results. The [Search API page](https://specstream.ai/search-api.md) lists both prices.

With `REDIS_URL` set, Farfalle keeps each search's results for 7,200 seconds and answers the same query again from Redis, with no new call. 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`, and nothing is charged. Farfalle shows `There was an error while searching.` Ask again after a moment.
-   The same message after every question usually means a wrong key or address. Check that `SEARXNG_BASE_URL` starts with `https://api.specstream.ai/searxng/` and holds your key, and that the backend was recreated after the change.

## Go back to the local SearXNG

Set `SEARXNG_BASE_URL` back to `http://searxng:8080` and run `docker-compose -f docker-compose.dev.yaml up -d` again. Questions: [support@specstream.ai](mailto:support@specstream.ai).

## More

[SpecStream for Farfalle](https://specstream.ai/integrations/farfalle.md) covers what it does in Farfalle 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).