> For the complete documentation index, see [llms.txt](https://docs.cherry-ai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherry-ai.com/docs/en-us/pre-basic/websearch/searxng.md).

# Local Deployment and Configuration of SearXNG

CherryStudio supports web search through SearXNG. SearXNG is an open-source project that can be deployed locally or on a server, so it is slightly different from other configuration methods that require an API provider.

**SearXNG project link**:[SearXNG](https://github.com/searxng/searxng)

## Advantages of SearXNG

* Open source and free, no API required
* Relatively high privacy
* Highly customizable

## Local deployment

### 1. Direct Docker deployment

Since SearXNG does not require a complex environment setup, you do not need docker compose. You only need to provide an available port to deploy it, so the fastest way is to use Docker to pull the image directly and deploy it.

#### 1. Download, install, and configure [docker](https://www.docker.com/)

<figure><img src="/files/9e82971de41d3a740f0e21428878c883f4d4cc55" alt=""><figcaption></figcaption></figure>

After installation, choose an image storage path:

<figure><img src="/files/348b09a1687298bb753c31dac0ee22e4d4764633" alt=""><figcaption></figcaption></figure>

#### 2. Search for and pull the SearXNG image

Enter in the search bar **searxng** :

<figure><img src="/files/4acf1aeeb48f5fee250401bc704c7d96039f6321" alt=""><figcaption></figcaption></figure>

Pull the image:

<figure><img src="/files/a77e2405fa5420b036799c9347bcd2427881189f" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/1d69c465ba041fbe1642316831d1677750752fe3" alt=""><figcaption></figcaption></figure>

#### 3. Run the image

After the pull succeeds, go to the **images** page:

<figure><img src="/files/9ec04b96e854d4798a7472c5fe3e954037d15f1e" alt=""><figcaption></figcaption></figure>

Select the pulled image and click Run:

<figure><img src="/files/4ee5345730a7214c153c5607b0903002bb0ec462" alt=""><figcaption></figcaption></figure>

Open the settings item to configure:

<figure><img src="/files/9c1fd22e823f1148738e3c41ba1fb315220c208e" alt=""><figcaption></figcaption></figure>

Using `8085` port as an example:

<figure><img src="/files/858f2e89d489a52b69c94c3c929246d36e419576" alt=""><figcaption></figcaption></figure>

After it runs successfully, click the link to open the SearXNG frontend:

<figure><img src="/files/0323e422883c1a83d5ab5040876db535cc2a8b2e" alt=""><figcaption></figcaption></figure>

If this page appears, deployment was successful:

<figure><img src="/files/b7f46bb5934d2c444a8d056abe1d948b7e5eed71" alt=""><figcaption></figcaption></figure>

## Server deployment

Given that installing Docker on Windows is rather troublesome, users can deploy SearXNG on a server and share it with others as well. Unfortunately, SearXNG itself does not currently support authentication, which allows others to scan and abuse your deployed instance through technical means.

For this reason, Cherry Studio now supports configuring [HTTP Basic Authentication (RFC7617)](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Guides/Authentication), if you want to expose your self-hosted SearXNG to the public network, please**be sure to**configure HTTP Basic Authentication through a reverse proxy such as Nginx. A brief tutorial is provided below; you need basic Linux operations and maintenance knowledge.

### Deploy SearXNG

Similarly, Docker is still used for deployment. Assuming you have already followed the[official tutorial](https://docs.docker.com/engine/install)to install the latest Docker CE on the server, here is a one-stop command for a fresh installation on Debian systems:

```bash
sudo apt update
sudo apt install git -y

# Pull the official repository
cd /opt
git clone https://github.com/searxng/searxng-docker.git
cd /opt/searxng-docker

# If your server has very limited bandwidth, you can set this to false
export IMAGE_PROXY=true

# Modify the configuration file
cat <<EOF > /opt/searxng-docker/searxng/settings.yml
# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
use_default_settings: true
server:
  # base_url is defined in the SEARXNG_BASE_URL environment variable, see .env and docker-compose.yml
  secret_key: $(openssl rand -hex 32)
  limiter: false  # can be disabled for a private instance
  image_proxy: $IMAGE_PROXY
ui:
  static_use_hash: true
redis:
  url: redis://redis:6379/0
search:
  formats:
    - html
    - json
EOF
```

If you need to change the local listening port or reuse an existing local nginx, you can edit `docker-compose.yaml` file, see the following example:

```yaml
version: "3.7"

services:
# If you do not need Caddy and want to reuse an existing local Nginx, remove the following part. By default, we do not need Caddy.
  caddy:
    container_name: caddy
    image: docker.io/library/caddy:2-alpine
    network_mode: host
    restart: unless-stopped
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data:rw
      - caddy-config:/config:rw
    environment:
      - SEARXNG_HOSTNAME=${SEARXNG_HOSTNAME:-http://localhost}
      - SEARXNG_TLS=${LETSENCRYPT_EMAIL:-internal}
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"
# If you do not need Caddy and want to reuse an existing local Nginx, remove the above part. By default, we do not need Caddy.
  redis:
    container_name: redis
    image: docker.io/valkey/valkey:8-alpine
    command: valkey-server --save 30 1 --loglevel warning
    restart: unless-stopped
    networks:
      - searxng
    volumes:
      - valkey-data2:/data
    cap_drop:
      - ALL
    cap_add:
      - SETGID
      - SETUID
      - DAC_OVERRIDE
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"

  searxng:
    container_name: searxng
    image: docker.io/searxng/searxng:latest
    restart: unless-stopped
    networks:
      - searxng
    # By default it maps to port 8080 on the host machine. If you want to listen on 8000, change it to "127.0.0.1:8000:8080"
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=https://${SEARXNG_HOSTNAME:-localhost}/
      - UWSGI_WORKERS=${SEARXNG_UWSGI_WORKERS:-4}
      - UWSGI_THREADS=${SEARXNG_UWSGI_THREADS:-4}
    cap_drop:
      - ALL
    cap_add:
      - CHOWN
      - SETGID
      - SETUID
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"

networks:
  searxng:

volumes:
# If you do not need Caddy and want to reuse an existing local Nginx, remove the following part
  caddy-data:
  caddy-config:
# If you do not need Caddy and want to reuse an existing local Nginx, remove the above part
  valkey-data2:
```

Run `docker compose up -d` to start. Run `docker compose logs -f searxng` to view the logs.

### Deploy Nginx reverse proxy and HTTP Basic Authentication

If you are using a server panel program, such as BaoTa Panel or 1Panel, please refer to its documentation to add a website and configure an nginx reverse proxy. Then find where you can modify the nginx configuration file and make changes according to the example below:

```conf
server
{
    listen 443 ssl;

    # This line is your hostname
    server_name search.example.com;

    # index index.html;
    # root /data/www/default;

    # If SSL is configured, these two lines should be present
    ssl_certificate    /path/to/your/cert/fullchain.pem;
    ssl_certificate_key    /path/to/your/cert/privkey.pem;

    # HSTS
    # add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";

    # By default, when configuring a reverse proxy through the panel, the default location block is like this
    location / {
        # Just add the following two lines to the location block; keep the rest unchanged.
        # This example assumes your configuration file is saved in the /etc/nginx/conf.d/ directory.
        # If it is BaoTa, it may be saved in a directory such as /www; note that.
        auth_basic "Please enter your username and password";
        auth_basic_user_file /etc/nginx/conf.d/search.htpasswd;

        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_protocol_addr;
        proxy_pass http://127.0.0.1:8000;
        client_max_body_size 0;
    }

    # access_log  ...;
    # error_log  ...;
}
```

Assuming the Nginx configuration file is saved under `/etc/nginx/conf.d` we will save the password file in the same directory.

Run the command (replace `example_name`、`example_password` with the username and password you want to set):

```bash
echo "example_name:$(openssl passwd -5 'example_password')" > /etc/nginx/conf.d/search.htpasswd
```

Restart Nginx (reloading the configuration is also fine).

At this point, you can open the webpage. It should prompt you to enter a username and password. Enter the username and password you set earlier to see whether you can successfully enter the SearXNG search page, thereby checking whether the configuration is correct.

<figure><img src="/files/556c7a0f904ddcd7ea89a597a21a3b88c4a95488" alt=""><figcaption></figcaption></figure>

## Cherry Studio related configuration

After SearXNG has been successfully deployed locally or on a server, the next step is the related Cherry Studio configuration.

Go to the web search settings page and select Searxng:

<figure><img src="/files/3a353f7c13612ceeaab7e16c22d2ec8bf6a380c7" alt=""><figcaption></figcaption></figure>

If you enter the locally deployed link directly, validation will fail. Do not worry at this point:

<figure><img src="/files/f5e19aa349b33f2bf89f806722ca9e0661528888" alt=""><figcaption></figcaption></figure>

Because after direct deployment, the json return type is not configured by default, so data cannot be obtained; you need to modify the configuration file.

Go back to Docker, go to the Files tab, and find the labeled folder in the image:

<figure><img src="/files/bbecf19a041e64524456e2fb7e72137122acf92d" alt=""><figcaption></figcaption></figure>

After expanding it, continue scrolling down, and you will find another labeled folder:

<figure><img src="/files/7e1227138bd651fede24b40d2215c617e736bbbb" alt=""><figcaption></figcaption></figure>

Continue expanding and find **settings.yml** configuration file:

<figure><img src="/files/0782b9e91f9369f7b1d72c2c56f928673a92fafa" alt=""><figcaption></figcaption></figure>

Click to open the file editor:

<figure><img src="/files/aa8f9d92869a2c06bdc95d961bd572872a79fae6" alt=""><figcaption></figcaption></figure>

Find line 78; you can see that the only type is html

<figure><img src="/files/fb0a7b5cc91865165fd87fedeb3cfbb30bd88115" alt=""><figcaption></figcaption></figure>

Add the json type, save it, and rerun the image

<figure><img src="/files/50ecb6d99939b8b920e32b4d5f6cd5dd7a6e898f" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2d916252cf79747966168c74eba90475c8342603" alt=""><figcaption></figcaption></figure>

Go back to Cherry Studio to verify again; verification succeeded:

<figure><img src="/files/4e90ca769884ac32a86fb556fc988001092596cc" alt=""><figcaption></figcaption></figure>

The address can be local: <http://localhost> : port number\
It can also be a docker address:<http://host.docker.internal> : port number

If the user follows the previous example to deploy on a server and configures the reverse proxy correctly, json return type has already been enabled. After entering the address and verifying, because HTTP Basic Authentication has been configured for the reverse proxy, verification should now return error code 401:

<figure><img src="/files/ffa5546330be32f58fd686bf98c7dd7a3e59754d" alt=""><figcaption></figcaption></figure>

Configure HTTP Basic Authentication on the client side and enter the username and password you just set:

<figure><img src="/files/7d4027cb7fe167a4ae1e48b56feeb2216a695643" alt=""><figcaption></figcaption></figure>

Verify, and it should succeed.

### Other configurations

At this point, SearXNG already has the ability to search the web by default. If you need to customize the search engines, you need to configure them yourself

Note that the preferences here do not affect the configuration used when calling the large model

<figure><img src="/files/5228c8b07611211e8baa636da7e4a73bf899dc62" alt=""><figcaption></figcaption></figure>

If you need to configure the search engines used by large model calls, set the following in the configuration file:

<figure><img src="/files/0482298bc45b2d635badd94a6f0770e9848be3cf" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/a3d3d8151d823238a33993fcade06974574a2030" alt=""><figcaption></figcaption></figure>

Configuration language reference:

<figure><img src="/files/28f6fb99c118e030ac3ff2854894269fc45324b3" alt=""><figcaption></figcaption></figure>

If the content is too long and inconvenient to edit directly, you can copy it into a local IDE, modify it, and then paste it back into the configuration file.

## Common causes of verification failure

### The return format does not include json

Add json to the return format in the configuration file:

<figure><img src="/files/f7bf7b98494381439b525a695a1c8496f3e330b4" alt=""><figcaption></figcaption></figure>

### Search engine not configured correctly

Cherry Studio will, by default, select engines whose categories include both web and general for search. Under normal circumstances, engines such as Google will be selected, but because mainland China cannot directly access sites such as Google, this leads to failure. Add the following configuration to force searxng to use the baidu engine, and the problem can be solved:

```
use_default_settings:
  engines:
    keep_only:
      - baidu
engines:
  - name: baidu
    engine: baidu 
    categories: 
      - web
      - general
    disabled: false
```

### Access rate too fast

The limiter configuration in searxng is blocking API access. Please try setting it to false in the settings:&#x20;

<figure><img src="/files/f765a271281448682a6fa769fb254320b612fe29" alt=""><figcaption></figcaption></figure>

***

### 💡 Get help and submit feedback

If you encounter any questions, bugs, or have suggestions for feature improvements during configuration or use, please refer to [Feedback and Suggestions](/docs/en-us/question-contact/suggestions.md) the official channels provided there.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherry-ai.com/docs/en-us/pre-basic/websearch/searxng.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.