How Dify with SearXNG for self-hosted web search works
A team that wants Dify agents to search the web without sending every query to a commercial search API has a supported route: the SearXNG tool plugin from the Dify Marketplace, published by langgenius, pointed at a SearXNG instance the team runs itself. SearXNG is a free internet metasearch engine, so the search provider is your own service rather than a third-party API key. The plugin is the link between a Dify workflow or agent tool call and that instance, and the search traffic leaves your network only as far as the upstream engines you configure on SearXNG. Confirm with the plugin listing which SearXNG settings it expects before you deploy, because this page does not cover its configuration keys.
The part that most often breaks is network access. Dify sends outbound HTTP requests through a Squid SSRF proxy that blocks private networks by default. If SearXNG runs on an internal host, such as a private IP address or a hostname that resolves to one, the plugin's requests will be refused until you allow that host. The Dify environment variable reference documents two settings for this: SSRF_PROXY_ALLOW_PRIVATE_IPS for addresses and SSRF_PROXY_ALLOW_PRIVATE_DOMAINS for hostnames. Use the narrowest one that fits, and add only the exact SearXNG endpoint, not a whole private range, so the proxy keeps blocking other internal services.
Before you open the allowlist, decide where SearXNG runs, who can reach it and what it is allowed to query. Document the single host or domain you permit, test a search from a workflow in a non-production workspace, and confirm that the SSRF proxy still refuses an internal address you did not list. Because the proxy setting is shared by every outbound call Dify makes, each entry widens what Dify can reach from any app, so review the list after each Dify upgrade. Ask your implementation partner or internal team to confirm the variable names against the Dify version you run, since configuration keys change between releases.
What you need before connecting SearXNG to Dify
Four things have to be in place before the SearXNG tool plugin can return results to a Dify agent or workflow. Each one touches a different part of the stack, so check them in order and confirm each before you install anything.
A self-hosted Dify deployment
The Docker Compose deployment needs at least 2 CPU cores and 4 GB of RAM, with Docker Compose 2.24.0 or later. Those minimums come from the Dify self-hosting docs, and they are a floor for a test install, not a sizing for production traffic. Confirm your host meets them, then confirm the api and plugin daemon containers are healthy, because the SearXNG tool runs inside that stack.
A running SearXNG instance
SearXNG has to be reachable by network address from the Dify api and plugin daemon containers, not only from your laptop. Confirm the hostname or IP and port that those containers resolve, and test it from inside the container network before you configure Dify. Note that a localhost address points back at the container itself, so it will fail.
SearXNG JSON output enabled
Dify reads SearXNG results as structured data, so the JSON response format has to be enabled on your instance. Confirm the setting, and the SearXNG version you run, in your SearXNG documentation, since output formats and default settings change between releases. Then send a test query with the format parameter set to JSON and check that the response parses before you move on.
Workspace admin access for the plugin
Installing the SearXNG tool plugin from the Dify Marketplace requires admin rights in the target workspace. The plugin is published by langgenius and describes SearXNG as a free internet metasearch engine. Confirm who holds the admin role, and record which workspace the tool will be enabled in, since each workspace manages its own tools and credentials.
Routes between the SSRF proxy and SearXNG
Dify sends outbound requests through a Squid SSRF proxy that blocks private networks by default. If SearXNG sits on an internal host, the proxy must be allowed to reach it through SSRF_PROXY_ALLOW_PRIVATE_IPS or SSRF_PROXY_ALLOW_PRIVATE_DOMAINS. Confirm the network path from the proxy container to the SearXNG host and port, and list the exact address you will allow so the exception stays narrow.
Configuration sequence for the SearXNG tool plugin
This sequence takes a SearXNG instance you run from a standalone service to a tool that a Dify agent or workflow can call, with each step confirmed before the next one begins. The result is web search that stays on infrastructure you control and returns results to a test run you have checked.
Deploy or confirm the SearXNG instance
The platform or infrastructure team deploys SearXNG on a host you control, or confirms an existing instance is running and reachable. Record its base URL, including scheme and port, because the same value is needed in the Dify plugin credentials. Confirm that the instance returns JSON search results, since Dify's tool reads structured output, and check the SearXNG settings for the output formats you enable. Done means you can run a search in a browser or with curl from the host itself and see results.
Confirm the instance answers from the Dify containers
Run a request from inside the Dify api container, because outbound tool calls originate there and not from your workstation. Use docker compose exec with the api service and a curl call to the SearXNG base URL with a simple query parameter. A successful response with search results shows that DNS, routing and firewall rules allow the containers to reach the instance. A timeout or connection refused at this point means the problem is network reachability, and the next step will not fix it.
Allow the private host in the SSRF proxy
Dify routes outbound HTTP requests through a Squid SSRF proxy that blocks private networks by default. Add the SearXNG host to SSRF_PROXY_ALLOW_PRIVATE_IPS if you reference it by IP address, or to SSRF_PROXY_ALLOW_PRIVATE_DOMAINS if you reference it by hostname, in the .env file. Keep the list limited to this host and do not widen it to a whole subnet. Restart the stack so the proxy reads the new values. Confirm the change by checking that the variable is set in the running api container and that the stack restarted without errors in the logs.
Install the SearXNG plugin from the Marketplace
An administrator opens the Dify Marketplace listing for the SearXNG tool plugin, published by langgenius, and installs it into the workspace. Review the plugin details before installation, including its publisher and the permissions it asks for, and record the version you install so upgrades can be tracked. Confirm that the plugin appears in the workspace tool list with its status shown as installed and enabled. If it does not appear, check the plugin daemon logs before going further.
Enter the instance URL in the plugin credentials
Open the SearXNG plugin's credential settings in the Dify workspace and enter the base URL you verified in the first two steps. Use the same scheme, hostname or IP and port that the api container used in its curl test, because a different form can route differently through the SSRF proxy. Save the credential and use the plugin's own test or validation action if one is offered. Done means the credential saves without an error and the validation call returns results from SearXNG.
Attach the search tool to a test agent or workflow
Create a test agent or a small workflow in a non-production app, and add the SearXNG search tool as a tool node or agent tool. Write a prompt or input that asks for a query, and map the tool's query input to it. Keep the test app separate from production apps so that search traffic and prompts from testing do not mix with user data. Confirm that the tool node appears in the workflow canvas and that its configuration validates without warnings.
Run a query and check the output
Run the test workflow or agent in the workflow debugger with a query whose results you can predict, such as a public documentation page. Open the run trace and check that the tool node executed, returned results from SearXNG, and passed those results to the next node or to the model. If the run fails, read the node error and compare it with the curl result from the api container, since most failures trace back to the URL form or the SSRF allowlist. When the run returns the expected results, the sequence is complete, and you can copy the same credential and allowlist entry to each environment you plan to use.
Why the SSRF proxy blocks SearXNG and how to allowlist it narrowly
An internal SearXNG host fails by default because Dify sends outbound HTTP requests through a Squid-based SSRF proxy that blocks private networks. The proxy exists to stop server-side request forgery, so a tool call that targets an address in a private range is refused unless you explicitly allow it. Dify provides two variables for this: SSRF_PROXY_ALLOW_PRIVATE_IPS lists specific addresses, and SSRF_PROXY_ALLOW_PRIVATE_DOMAINS lists specific domain names. The environment variable reference describes both, so check the exact value format for your release in that reference before editing .env.
Choose between IPs and domains based on how your SearXNG host is addressed. An IP entry is precise but breaks if the host is re-addressed, while a domain entry follows the name but depends on your internal DNS resolving it to the intended host. Whichever you choose, list only the one SearXNG endpoint. Opening private ranges broadly would let any tool, custom plugin or External Knowledge call reach other internal services, which undoes the control the proxy provides. Confirm with your network team that the name or address resolves to a single, stable service and that nothing else sits behind it.
Test the allowlist from both sides. Agent sandbox network isolation, added in Dify 1.16.1 and described in its release notes, also routes traffic through a Squid proxy, so a SearXNG call that succeeds in a workflow can still fail when an agent invokes the same tool. Run a search from a workflow and from an agent node, and after any upgrade, re-check the allowlist and the sandbox behavior together. Keep the change in version-controlled configuration so a later edit does not silently widen access.
Which Dify settings map to which SearXNG values
This table pairs each Dify-side setting with the SearXNG value it must match, so you can trace a failed search back to one field. Read each row as a pair: the value you take from your SearXNG deployment on the left, and where it goes in Dify on the right. Confirm the exact field names on the SearXNG plugin configuration screen in your Dify version before you enter anything.
| Dify setting | SearXNG value to supply | Where it is set | Check before you rely on it |
|---|---|---|---|
| Plugin base URL | Address of your SearXNG instance, including scheme and port | SearXNG tool plugin credentials in Dify | Open the instance's search page from the Dify api container, not only from your laptop |
| SSRF_PROXY_ALLOW_PRIVATE_IPS | IP address of the host running SearXNG | Dify .env file, then restart services | Use the exact address the base URL resolves to, including any non-default port scope |
| SSRF_PROXY_ALLOW_PRIVATE_DOMAINS | Internal hostname that resolves to the SearXNG host | Dify .env file, then restart services | Confirm the name resolves inside the Docker network and to the same address the proxy sees |
| Access restriction on SearXNG | API key, header value or allowed client address, if your SearXNG setup enforces one | SearXNG tool plugin credentials in Dify | Test with the same credential from a plain HTTP client before saving it in Dify |
| Result format | JSON output enabled on the SearXNG instance | SearXNG server configuration | Confirm the plugin requests a format your instance serves, since a text-only response will fail |
| Public or internal exposure | Whether the instance is reachable only on the internal network | Network design, outside Dify | Public exposure of a search endpoint should be a deliberate decision, not a side effect of the allowlist |
Security controls for web search from an internal host
Pointing Dify at a SearXNG instance on an internal host widens what Dify's outbound path can reach, so the controls below decide how much exposure that creates. Each card covers one decision to make before the tool goes live, and each one is easier to set during the build than to retrofit after agents are already searching.
Isolate the SearXNG network segment
Place SearXNG on a restricted network segment that accepts connections only from the Dify host or the SSRF proxy that carries its requests. Nothing else on the internal network should reach the search instance, and it should have no route to systems that hold sensitive data. Ask your network team to confirm the segment rules in writing before you add the host to Dify, and test the path from a machine outside that set to confirm it is blocked.
Allowlist the narrowest host
Add only the exact SearXNG host to SSRF_PROXY_ALLOW_PRIVATE_IPS, or a single domain to SSRF_PROXY_ALLOW_PRIVATE_DOMAINS if you resolve it by name. Avoid listing whole subnets because every host in them becomes reachable through Dify's proxy path. Record the entry in your change log with its owner so a later reviewer can see why the exception exists.
Avoid widening private ranges
Resist the temptation to relax the proxy's private network blocking to make a single connection work. Broad changes to the proxy affect every outbound request from every app and knowledge pipeline in the instance, including external knowledge and HTTP tool calls. If a broader range seems necessary, treat it as a separate security review with its own approval, not a troubleshooting step.
Treat SECRET_KEY and logs as sensitive
Search queries generated by agents can contain customer names, case details or internal project terms, so the outbound logs and the SearXNG query logs deserve the same protection as conversation data. Restrict who can read them and set a retention period you can defend. Plan any SECRET_KEY change as a maintenance window, because rotating it after deployment logs out all users.
Review what agents may search
Search access follows the workspace's access model, so decide which workspaces and apps can call the SearXNG tool and which can not. Review the system prompts and workflow nodes that build search queries, since an agent can send any text it has been given to the search engine. Ask the team that owns each app to confirm its search scope before publishing it to end users.
Why Dify web search fails and how to fix it
This table lists the failures teams most often hit when wiring the SearXNG tool into a self-hosted Dify, with the likely cause and the fix for each. Work down the rows in order, since the allowlist and restart checks resolve most blocked-request cases before you look at the instance itself.
| Failure | Likely cause | Fix |
|---|---|---|
| Blocked or connection refused from the plugin | The SearXNG host is on a private network and is not listed in the SSRF proxy allowlist, so Squid blocks the request. | Add the host or domain to SSRF_PROXY_ALLOW_PRIVATE_IPS or SSRF_PROXY_ALLOW_PRIVATE_DOMAINS in .env, keeping the list as narrow as possible. |
| Allowlist change has no effect | The variable was edited but the containers were not recreated, so the running proxy still uses the old configuration. | Recreate the stack with Docker Compose so the new environment values are loaded, then retest the tool from a workflow. |
| SearXNG unreachable from the plugin daemon | The URL uses localhost or a name that resolves only on the host, while the plugin daemon runs in its own container network. | Use an address the container can reach, such as a host-reachable IP or DNS name, and test it from inside the plugin daemon container. |
| Empty results with no error | The instance does not enable the JSON output format, so the plugin receives HTML it cannot parse. | Enable JSON in the SearXNG settings for the instance and confirm the search endpoint returns JSON for a test query. |
| Empty or sparse results over time | Upstream engines rate limit the instance because it sends many queries from one address, or several engines are disabled. | Review enabled engines and request volume, and confirm rate limit behavior with your instance administrator before raising load. |
| Agent never calls the tool | The tool is not added to the agent or node, or the instruction does not tell the model when web search is needed. | Add the tool explicitly to the agent, state in the prompt when to search, and test with a question that needs current information. |
Questions teams ask before connecting Dify to SearXNG
Is the SearXNG plugin for Dify free to use?
The SearXNG tool plugin is published by langgenius on the Dify Marketplace and describes SearXNG as a free internet metasearch engine, so the software itself carries no license fee for the plugin or the engine. Dify Community is also free to self-host, but it is limited to a single workspace. The costs that remain are the infrastructure you run for the SearXNG instance, the network paths and firewall work, and the staff time to configure and maintain both. Confirm those hosting costs in your own environment before you compare this with a commercial search API, whose per-query pricing is set by its vendor. Ask any partner quoting the work to separate one-time setup from recurring operations.
How long does it take to connect Dify to a SearXNG instance?
The duration depends mostly on two things: whether the SearXNG host is already running and reachable from Dify, and whether the network path needs new routing or firewall rules. If SearXNG is already stable and on a host the Dify api and sandbox can reach, the Dify side is a configuration change plus testing. If you need to build the SearXNG host, decide which engines it queries, and get security approval for the internal address, the work takes longer. No duration is given here because none is supplied for this topic. Ask for a fixed-scope estimate that lists each step, the approvals it depends on and what you must provide before the work starts.
Can our own team connect Dify to SearXNG without outside help?
Yes, if your team can operate Docker, edit the Dify .env file, restart the Compose services and read container logs. The plugin is installed from the Dify Marketplace, and the main Dify change is making the SearXNG host reachable through the SSRF proxy settings, which block private networks unless you allow the host. Your team also needs to test a workflow end to end and confirm that the search results it returns are the ones you expect. Teams without someone comfortable with container networking, or without a clear owner for the search host, often choose a partner for the first build and then run it internally.
What do we need to provide for the SearXNG work?
You need three things. First, network access: a route from the Dify api and sandbox containers to the SearXNG host, and a decision about whether that host is on a private address that the SSRF proxy must allow through SSRF_PROXY_ALLOW_PRIVATE_IPS or SSRF_PROXY_ALLOW_PRIVATE_DOMAINS. Second, a SearXNG host you control, with its own patching, logs and access rules. Third, a Dify administrator who can install plugins and change environment variables, plus someone who owns the search configuration. Ask for a written list of these inputs in any scope, so that missing access does not stall the schedule.
Can we restrict web search to approved sources only?
Restriction is a SearXNG configuration matter, not a Dify switch described in the sources supplied for this topic. SearXNG decides which upstream engines it queries and how results are filtered, so the practical control is to define the engine list and any result rules on the SearXNG instance itself, then test that queries return only the sources you approve. Confirm the exact configuration options with the SearXNG documentation and your chosen version before you promise a source list to a reviewer. Also remember that Dify fetches only what the search returns, so an agent can still follow links in results, which is why outbound filtering in the SSRF proxy matters alongside engine choice.
What should we check after a Dify upgrade breaks search?
Start with the upgrade guide for the target Dify version on the Dify GitHub Releases page, and compare your .env with the current .env.example, because new variables can appear between releases and the SSRF proxy allowlist is one of the settings you depend on. Confirm that the SearXNG plugin is still installed at a version compatible with your Dify release, that the SearXNG host is still reachable from the sandbox and api containers, and that the allowlist values survived the change. Take a backup before every upgrade, as the Docker Compose documentation advises, and rerun a test workflow after each step. Minor Dify releases have arrived roughly monthly, so build this check into your routine rather than treating it as a one-off.
How to test web search and keep it running after upgrades
Web search is only trustworthy after four checks pass in order, and each one isolates a different failure. Start with a direct connectivity check: run a request from inside the api container to your SearXNG instance's search endpoint with a known query and confirm a JSON or HTML response returns. If this fails, the problem is network reachability or the SearXNG configuration, not Dify. Next, run a workflow test with a small set of queries whose correct results you already know, using the SearXNG tool node in a workflow so you see the exact output the model will receive. Then run an agent test: give the agent prompts that should trigger search and prompts that should not, and confirm from the run logs that it selects the SearXNG tool only when it should. Finally, run a negative test: point a tool or workflow at an internal host that is not on your allowlist and confirm the SSRF proxy blocks it. A passing negative test is the evidence that your allowlist is as narrow as you intended.
Keep these checks as a written runbook, because the allowlist is the part most likely to drift. Before every Dify upgrade, take a backup of the database and volumes, as the Docker Compose docs advise. After pulling the new release, compare your .env file against .env.example for new or renamed variables, since an upgrade can change proxy-related settings without warning. Then re-run all four checks, including the negative test. Minor releases arrive roughly monthly, so schedule this as a recurring task rather than an event. Confirm the upgrade steps for each target version in the Dify releases page and in the upgrade guide linked from it, and record which SearXNG version and configuration you tested against so that a failing check later has a clear baseline.
How DeployOpen scopes and delivers Dify web search integrations
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Dify. For web search, that means a written scope covering the SearXNG instance, the SSRF proxy allowlist, the Dify tool configuration and the operating runbook that keeps them working together.
How we scope
- Confirm which agents and workflows need web search and what queries they will send.
- Map where the SearXNG instance will run and which internal host and port Dify must reach.
- Agree in writing which SSRF_PROXY_ALLOW_PRIVATE_IPS or domain entries are in scope and why.
How we build
- Deploy or confirm the SearXNG instance and its search engine configuration in your network.
- Install the SearXNG tool plugin from the Dify Marketplace and point it at the internal endpoint.
- Test allowlist changes against the Squid SSRF proxy, keeping every other private range blocked.
How we hand over
- Document the allowlist entries, their owners and the reason each one exists.
- Provide a test workflow and expected results so your team can repeat the verification.
- Record the environment settings, plugin version and SearXNG configuration in the handover pack.
How we support
- Review allowlist scope and plugin updates when Dify minor releases arrive, which come roughly monthly.
- Check .env.example for new variables after each Dify upgrade, with a backup taken first.
- Ongoing support and continuous testing are available as a retainer after handover.
