Quick Start

This page has one goal: install OxiDNS and complete the first successful DNS query. Use the dedicated installation guides for version selection, portable mode, uninstallation, and production deployment details.

Choose an installation path

Environment	Recommended guide
Linux / macOS / Windows host	Native installer
Docker / Compose	Docker deployment
OpenWrt router	OpenWrt and LuCI
Manual archive, Debian package, or source	Releases, Debian, and source installation
Custom plugin and protocol selection	Custom Builds

1. Install

Linux / macOS

curl -fsSL https://oxidns.org/install.sh | sudo sh

Windows

Run in an administrator PowerShell session:

irm https://oxidns.org/install.ps1 | iex

Docker

Prepare the configuration:

mkdir -p oxidns && cd oxidns
docker run --rm --entrypoint /bin/cat \
  svenshi/oxidns:latest /etc/oxidns/config.yaml > config.yaml

Then start the container:

docker run -d --name oxidns --restart unless-stopped \
  -p 53:53/udp -p 53:53/tcp -p 127.0.0.1:9199:9199/tcp \
  -v "$(pwd)/config.yaml:/etc/oxidns/config.yaml:ro" \
  svenshi/oxidns:latest

OpenWrt

curl -fsSL https://oxidns.org/install.sh | sh

If curl is unavailable, use wget -O- https://oxidns.org/install.sh | sh.

OpenWrt also needs the core

The OpenWrt script installs only luci-app-oxidns. After it finishes, open Services → OxiDNS → Core to install and start the OxiDNS core, then continue with verification.

2. Verify

Linux / macOS

oxidns --version
oxidns build-info
curl -fsS http://127.0.0.1:9199/api/readyz
dig @127.0.0.1 example.com

Windows

oxidns.exe --version
oxidns.exe build-info
Invoke-RestMethod http://127.0.0.1:9199/api/readyz
Resolve-DnsName example.com -Server 127.0.0.1

Docker

docker ps --filter name=oxidns
docker logs --tail 50 oxidns
curl -fsS http://127.0.0.1:9199/api/readyz
dig @127.0.0.1 example.com

OpenWrt

Confirm that the core is running on the LuCI status page, then query from the router shell or a LAN device:

nslookup example.com 127.0.0.1

The first start is successful when all of these are true:

• version and build-info output normally;
• /api/readyz succeeds, or LuCI reports the core as running;
• the DNS query returns a valid result.

The default WebUI address is http://SERVER_IP:9199/. If readiness works but DNS does not, follow Operations and Troubleshooting to inspect listeners, configuration, and upstreams. Enable authentication and read Security Hardening before allowing other devices to reach the WebUI or API.

3. Next steps

• Choose a home, router, or server template from Scenarios.
• Read the Configuration Guide to understand plugins and the execution chain.
• Find specific capabilities and options in the Plugin Reference.
• Complete the deployment checks in Operations and Troubleshooting before production use.