Skip to content

Web search

A local model knows nothing recent. With assistant.webSearch the assistant can search the web for what your homelab can’t answer: a new release, a how-to, today’s news. It’s off unless you set it, and a config without it works as before.

config.yaml
assistant:
model: qwen3:14b
webSearch:
provider: searxng
url: http://searxng:8080

This is not the top-level search: option. That one is a link ⌘K opens in your browser. This one gives the assistant two tools.

The chat after “Search the web for how to back up Immich”: a Searched the web step, a card of three results with their sites and snippets, and the answer citing two of them.
ToolWhat it does
web_searchSends a few words to your provider and gets back titles, addresses, short snippets and dates. You get the same results as a card, each title a link.
web_readOpens one page that a search returned and reads its text, for when a snippet is too thin.

Both are read tools, so neither asks first. In chat they show as “Searched the web” and “Read a web page”. They work in Telegram too, and on a read-only page, since they only look. An MCP client is never offered them.

Turn either off by name, like any tool:

config.yaml
assistant:
access:
valet.web_read: none # or webSearch.read: false

SearXNG runs on your own machine and asks the search engines for you. Nothing but the search words leaves, and they leave from SearXNG, not tied to an account. This is the one to pick if you can.

Valet uses its JSON API, which is off by default. Turn it on in SearXNG’s settings.yml and restart it:

settings.yml
search:
formats: [html, json]
config.yaml
assistant:
webSearch: { provider: searxng, url: http://searxng:8080 }

If Valet says SearXNG answered 403, the JSON format is still off.

Get a key from the Brave Search API and put it in .env as BRAVE_SEARCH_KEY.

config.yaml
assistant:
webSearch: { provider: brave, apiKey: "${BRAVE_SEARCH_KEY}" }

Get a key from Tavily and put it in .env as TAVILY_KEY.

config.yaml
assistant:
webSearch: { provider: tavily, apiKey: "${TAVILY_KEY}" }
  • What’s searched for leaves your network. With Brave or Tavily, each query goes to that company with your key. With SearXNG it goes to the engines your SearXNG asks, without a key.
  • The model writes the query. It’s told to search only for what the homelab’s own tools can’t answer, and never to put anything private in a query: nothing from your documents, no names, addresses or hostnames. That’s an instruction to a model, so it’s a strong hint and not a guarantee. If the assistant can read things that must never leave, use SearXNG, or leave web search off.
  • web_read contacts the page’s own server. That site sees a request from your address for that page, with no cookies and nothing about you.
  • Keys stay on the server, and are redacted from anything a provider sends back.
  • Search words are not logged. They are in the conversation, which your browser keeps.

A search result or a web page can say “ignore your instructions”. Valet treats them like a feed or a saved page:

  • Nothing changes without your press. A page can make the model ask to do something. The approval card still comes to you, in the tool’s own words.
  • web_read opens only what a search returned. The model can’t make up an address, so a page can’t talk it into sending what it read to a server of the page’s choosing.
  • web_read can’t reach your network. See below.
  • A page can still mislead the answer. The result card links every source, so you can check.
  • A page could get the model to search for something it read elsewhere in the chat. Those words go to your search provider, not to the page’s author. valet.web_search: none takes that away.

npm run test:hostile gives Valet a model that follows a poisoned result, and npm run eval:inject runs poisoned results past your own model.

Valet sits inside your network, so a tool that fetches an address is a way in if it’s careless. web_read:

  • takes http and https only, and no address with a sign-in in it;
  • looks the name up and refuses it unless every address it has is public. Loopback, the private ranges of RFC 1918, link-local (169.254/16, fe80::/10), unique-local (fc00::/7), carrier NAT (100.64/10), multicast, reserved and unspecified addresses are all refused, also when an IPv4 address is written as IPv6;
  • connects to the address it checked, so a second lookup can’t swap in another;
  • follows at most four redirects itself, and checks each one the same way;
  • sends a plain GET with no cookies and no keys;
  • gives up after 10 seconds, reads at most 2 MB, and takes only HTML and plain text;
  • hands the model the page’s words only, at most 6,000 characters. Scripts, styles and menus are dropped.

It doesn’t run a page’s scripts, so a page drawn by JavaScript reads as empty. It can’t read PDFs.

  • perDay caps the searches sent to the provider in a day, 100 by default, counted from midnight and from when Valet started. Past it, the model is told to answer from what it has.
  • The same search within an hour isn’t sent again. So a search pinned to the page costs at most one search an hour while the page is open.
  • results is how many each search hands the model, 5 by default and 10 at most. Fewer is cheaper for a small model.
  • One answer makes at most assistant.maxSteps tool calls, searches included.
  • It’s off in a sandbox.
OptionDefaultWhat it does
providerrequiredsearxng, brave or tavily.
urlnoneSearXNG only: where yours is.
apiKeynoneBrave and Tavily: the key, as ${NAME} from .env.
results5Results per search, 1 to 10.
safemoderateSafe search: off, moderate or strict. SearXNG and Brave. Tavily has no such setting.
languagenoneTwo letters, like en or de. SearXNG and Brave.
regionnoneA two-letter country, like CA. Brave; SearXNG uses it with language (de-CH).
readtruefalse leaves out web_read, so the assistant answers from snippets alone.
perDay100Searches sent to the provider in a day.