Web Search

Web search lets the chat assistant look things up on the web when your notes don’t have the answer — current events, library versions, anything outside the vault. It is the only way the assistant can look things up online, and it is designed so you stay in control of exactly when that happens:

• Off by default. Until you enable it, the assistant cannot search the web at all.
• You see every query first. Each search shows you the exact query text in a confirmation card before anything leaves the machine. Nothing is sent until you choose Send search. If you would rather not be asked each time, Allow in this chat stops the prompts for the rest of that one conversation — it never carries over to another chat and ends when DocGraph quits.
• Results are untrusted input. Whatever comes back is fenced and marked as web content the assistant may summarize or cite, but must never follow as instructions.
• No DocGraph-hosted service, no API key. DocGraph never routes your queries through any server of ours — you point it at your own search backend.

Requirements

Web search needs one thing: a SearXNG instance it can query.

SearXNG is a free, open-source metasearch engine that queries the big search engines for you and returns the results as JSON. DocGraph talks only to your SearXNG — never to Google, Bing, or anyone else directly. Running it on your own machine means your search queries never leave it in a form tied to you.

The recommended setup — a local instance — runs SearXNG in Docker, so for that path Docker is a requirement too. If you’d rather not install Docker, the alternatives are a non-Docker SearXNG installation or pointing DocGraph at an instance you already run elsewhere (a home server, your LAN); either way, DocGraph itself only needs the address. A public server from searx.space also works, but every search then passes through a stranger’s machine, and public servers are often throttled or refuse automated searches. A loopback (127.0.0.1) instance is the recommended setup: the query never leaves your machine, and the privacy badge stays green.

Set it up for me

Open Settings → AI → Web search. If no server is set and a SearXNG is already answering on this computer (on port 8888 or 8080), the status reads SearXNG is already running on this machine with its address: click Use it to fill in the Server address and turn web search on. The check only looks at this computer. If a server you already set stops answering and another local SearXNG is found, the status offers Use that one.

Otherwise, click Don’t have a server? Set one up on this machine. The panel checks Docker first and shows what is missing:

• Docker isn’t installed — Download Docker Desktop (or Or OrbStack, a lighter option for Mac), install and open it, wait until it says the engine is running, then Check again.
• Docker is installed but not running — Open Docker Desktop. The page notices when the engine has started.
• Docker is running — click Set it up for me.

Set it up for me runs a fixed Docker command you asked for with that click, and shows four steps with a running clock: Download SearXNG (first time only, about 200 MB), Start it, Wait for it to answer, and Run a test search. When the test passes, DocGraph fills in the Server address as http://127.0.0.1:8888 and turns on Enable web search.

What it creates, so you know what is on your machine:

• A container named docgraph-searxng, from the image searxng/searxng, restarted automatically after a reboot (--restart unless-stopped).
• Published on 127.0.0.1:8888 only — no other computer can reach it.
• A config file at ~/.docgraph/searxng/settings.yml. DocGraph writes it once and never overwrites it, so your edits are kept.

The config turns on the JSON output DocGraph reads, and it spreads searches over ten engines: Bing, Yahoo, Startpage, Mojeek, Presearch, DuckDuckGo, Brave, Google, Qwant and Wikipedia. That is deliberate: search engines answer an unattended server with CAPTCHAs, rate limits and suspensions, and which ones do changes from week to week. With a single engine, one refusal means a server that looks healthy and returns zero results; with several, the others keep answering. Engines that refuse are skipped, so they cost no time.

Set it up yourself instead

Under Set it up yourself instead:

1. Make sure Docker is running.
2. Click Copy terminal command and paste it into Terminal. It writes the same settings.yml and starts the same docgraph-searxng container on this machine only.
3. Paste http://127.0.0.1:8888 into Server address and click Test.

Use that command rather than a plain docker run searxng/searxng: the stock image keeps the default engines, and its JSON output is off, so searches fail or return nothing.

If you run SearXNG some other way, the two things it must have are the JSON format and engines that answer:

search:
  formats:
    - html
    - json

For engines, click Copy working settings (it appears when a test finds your server’s engines refusing, returning nothing, or down to one) and paste the result over your server’s settings.yml, then restart it. For the server DocGraph set up, restart with docker restart docgraph-searxng.

Configuration

Everything lives in Settings → AI → Web search. A status line at the top answers “does web search work right now, and if not, what do I do?” and always reflects the last Test.

Setting	What it does	Default
Enable web search	Turns the web_search tool on for the assistant.	Off
Server address	Your SearXNG’s base address, e.g. http://127.0.0.1:8888. Empty means web search stays off even when enabled. A pasted results-page link is tidied to the server’s address, and the value is saved, when you leave the field.	Empty
Test	Sends one real search through the server and reports how many results came back, which engines answered, which refused, and how long it took. It warns when only one engine answered, since searches then depend on it alone. The status line names the problem when it fails.	—
Local server only	Hard guard: refuse any server that isn’t on this machine, so a search can never leave it regardless of what the address says.	Off
Language	The language results are searched in: server default, any language, or one of 18 named languages.	Server default
SafeSearch	Filter explicit results: server default, Off, Moderate or Strict.	Server default
Published within	Only pages from the past day, week, month or year. Any time turns it off. If the test finds your server’s engines can’t filter by date, the status says so and suggests Any time; in chat, such a search is retried without the date filter.	Any time
Results per search	How many results the assistant reads: 3, 5, 8 or 10. More gives it more to work with and makes answers slower.	5

Recent searches lists the searches the assistant ran, with result counts. They are kept in memory until DocGraph quits, never saved to disk; Clear empties the list, and See every request in Network activity opens the Activity log. The log lists only searches sent to a server off this computer; a search to a SearXNG server on this computer isn’t recorded there.

How it behaves in chat

With web search enabled, the assistant gains a web_search tool. When it decides a question needs the web, you see a confirmation card with the verbatim query:

Button	Effect
Send search	Runs this one search.
Not now	Declines; the assistant carries on without it.
Allow in this chat	Runs this search and stops asking for web searches in this conversation. A banner reads Web searches in this chat are sent without asking, with Ask again to undo it. Other chats still ask, and it ends when DocGraph quits. Approve all this session for other changes never covers web searches.

Results are capped at Results per search (five unless you changed it), each reduced to a title, URL, and short snippet. If your server’s engines ignore Published within, DocGraph retries the search without the date filter rather than coming back empty.

Start a message with Search the web: (or search the web for, search online, web search, google …) to make sure it searches. Such a message is never answered as a list of matching notes. If the model answers without searching, DocGraph runs the search for the rest of your message itself, once per message. The usual card still asks first, and when web search is off you get the offer to turn it on.

Each web result is cited in the answer as a link named by its site, such as nodejs.org. Hover it for the full address; click it to open it in your browser. When none of your notes matched, the line under the answer says the answer came from web search.

When the assistant answers a question about DocGraph itself from the built-in user guide, it doesn’t offer web search for that question.

When web search is disabled, the assistant doesn’t silently give up on questions it can’t answer from your notes — it may offer to search, showing the query it would run. The card reads Enable & search and Not now; approving it is the only way the setting flips on, and the assistant (or anything it read) can never enable it by itself. If no server address is configured yet, the offer instead points you to Settings.

What happens to the privacy badge

DocGraph’s title bar always shows the privacy badge: 100% local while nothing is leaving your machine. Enabling web search doesn’t change it by itself — but the moment a search actually goes to an off-machine server, the badge flips to an amber External for as long as the request is in flight, and its tooltip names exactly what is connecting and where. When the response arrives, it returns to green.

This is the deal you’re making when you activate web search: your approved query — which the assistant writes, and which may quote your notes — travels to the search server you configured. The badge makes that moment visible instead of silent, and the network log keeps a record of it whenever the server is off this computer.

If your SearXNG runs on 127.0.0.1, the badge stays green even during a search — the query never leaves the machine, so there is no egress to report. That’s the recommended setup, and turning on Local server only makes it a hard guarantee.

Privacy guarantees

• The query is egress, and treated like it. A search against a non-local server is inspected by the egress check (“When content is about to leave this machine”) before it’s sent — the query is written by the model and can quote your notes. A loopback server skips the check, because nothing is leaving. A server that isn’t on this machine must use https.
• The network ledger records every search sent off this computer, including the full query text. If a query quoted your notes, that quote is in the log — something to know if you share log files. Searches to a SearXNG server on this computer (loopback) are not recorded, because nothing leaves the machine.
• A loopback server keeps the privacy badge green; an external one flags the request for its duration.
• Results can’t impersonate you or the app. Web content is wrapped in a tamper-proof fence with structural markers neutralized, so a malicious page can’t inject instructions that read as coming from you.
• Not exposed over MCP. A connected external agent never gets this tool — it has its own web access and its own policies.

Troubleshooting

Run Test first: its status line names the problem and offers the fix.

• Nothing is answering at … — SearXNG isn’t running. First make sure Docker Desktop (or OrbStack) itself is running; then docker ps should list docgraph-searxng, and docker start docgraph-searxng brings it back if not. (The restart policy makes this automatic after reboots.)
• Your server has its JSON output turned off — add - json under formats: in the server’s settings.yml and restart it. This is the cause of a 403.
• Web search works, but only one engine answered — the others are refusing your server. Searches still work, but will find nothing if that engine refuses too. Click Copy working settings, paste them over settings.yml, and restart the server.
• Your server answered, but its search engines refused (or answered with no results) — the engines are being blocked as automated traffic. Click Copy working settings, paste them over settings.yml, and restart the server.
• That address isn’t a SearXNG server — use the server’s base address, like http://127.0.0.1:8888, not a results page or another app’s port.
• Your server took too long to answer — it may still be starting. Wait a moment and test again. If it keeps stalling, check that the container is healthy.
• This server isn’t on this machine — Local server only is on but the address points off-machine. Point it at 127.0.0.1, or turn the guard off.
• DocGraph refused this address — a server that isn’t on this machine must use https.
• Your server is limiting requests — public servers throttle heavily. Running your own avoids this.
• Enabled but nothing happens — check the Server address isn’t empty; an empty address keeps the tool unregistered even with the toggle on. Test confirms the whole path.