Skip to the page
Get started free

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

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 on the Search API screen of your SpecStream workspace. New accounts start with $10 of credit, no card.

  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
    SEARCH_PROVIDER=searxng
    SEARXNG_BASE_URL=https://api.specstream.ai/searxng/YOUR_SPECSTREAM_KEY

  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
    docker-compose -f docker-compose.dev.yaml up -d

  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.

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 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: [email protected].

More

SpecStream for Farfalle covers what it does in Farfalle 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].