SearXNG setup¶

OpenSearch uses SearXNG as its web provider.

Official SearXNG references:

Requirements¶

Your instance must:

be reachable from the machine running OpenCode
expose /search
support format=json

The official settings docs show that json must be enabled in search.formats, not just html.

Example local URL:

export OPENSEARCH_WEB_URL="http://localhost:8080"

Local Docker Compose example¶

If you want a local instance, a minimal Compose setup looks like this:

services:
  searxng:
    image: ghcr.io/searxng/searxng:latest
    ports:
      - "127.0.0.1:8888:8080"
    environment:
      SEARXNG_BASE_URL: http://127.0.0.1:8888/
      FORCE_OWNERSHIP: "false"
    volumes:
      - ./config:/etc/searxng
      - ./data:/var/cache/searxng

With a matching config/settings.yml:

use_default_settings: true

server:
  secret_key: change-me
  limiter: false
  image_proxy: false

search:
  formats:
    - html
    - json

Then point OpenSearch at it:

export OPENSEARCH_WEB_URL="http://127.0.0.1:8888"

Optional shell aliases:

alias searstart='docker compose -f ~/.config/opencode/searxng/docker-compose.yml up -d'
alias searstop='docker compose -f ~/.config/opencode/searxng/docker-compose.yml down -v --remove-orphans'

Why self-hosting is preferred¶

Public instances often:

disable JSON output
rate-limit automated queries
change enabled engines without notice

Self-hosting gives you stable behavior and avoids vendor lock-in.

If you just want to get moving, the SearXNG docs recommend the container install or installation script.

Quick check¶

This should return JSON:

curl "http://localhost:8080/search?q=opensearch&format=json"

If you get 403, JSON output is probably disabled on the instance.