Install Numa and Access Its Dashboard with Localtonet

What Numa runs and what this guide exposes

Numa is a portable DNS resolver distributed as a single Rust binary. Its documented capabilities include caching, ad and tracker blocking, local .numa service names, hostname overrides, optional recursive resolution, DNSSEC validation in recursive mode when enabled, and a DNS-over-TLS listener. It can also provide an HTTP dashboard and REST API on port 5380.

Those endpoints do not all have the same security profile. The dashboard is an HTTP application intended for management and observation. Traditional DNS uses UDP and TCP port 53, while Numa's optional DNS-over-TLS listener uses port 853. Publishing a DNS listener to the internet can create an open-resolver risk if access is not restricted correctly. It can also require firewall policy, abuse controls, certificate planning, and careful resolver configuration.

For that reason, this tutorial uses the documented dashboard endpoint at http://localhost:5380 for the Localtonet integration. We do not expose port 53 or port 853. The result is a clear separation between Numa's DNS work and its web management surface:

Prerequisites and installation choices

Choose one installation path rather than combining several. A native installation is appropriate when Numa should integrate directly with the host operating system and run as a system service. Docker provides an isolated deployment and is especially convenient when you already operate containers. Cargo is an all-platform source-based installation path for systems with a working Rust toolchain. Nix can run Numa directly from its repository.

Before starting, confirm the following:

• You have administrator or root access if Numa will bind DNS port 53 or install itself as a system service.
• Port 5380 is not already occupied by another local application.
• If you choose Docker, Docker is installed and the daemon or Docker Desktop is running.
• If you choose Cargo, a functional Rust and Cargo toolchain is already installed.
• If you choose Nix, the nix command is already available.
• You can run the Localtonet client on the Numa host or on another device that can reach the dashboard's local IP address and port.

Numa's documented container image supports linux/amd64 and linux/arm64. Native package and release support can change between versions, so check that the selected download matches your operating system and processor architecture. This guide does not guess an asset filename or an unverified minimum operating-system version.

Install and start Numa

Use the subsection for your chosen platform. The foreground startup command is useful for an initial test because it keeps output visible in the current terminal. Installing Numa as a persistent operating-system service is covered separately.

macOS with Homebrew

Install Numa from its documented Homebrew tap:

brew install razvandimescu/tap/numa

Start it in the foreground with administrator privileges:

sudo numa

Administrator privileges are relevant because the standard DNS listener uses port 53. Keep the terminal open during this initial run, then visit http://localhost:5380 from the same Mac.

Linux with the installation script

The project documents this command for a standard Linux installation:

curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh

A pipe-to-shell command retrieves the current script from the project's main branch and immediately executes it. In controlled environments, retrieve and inspect the script before running it instead of piping it directly to the shell. The supplied evidence documents the one-line command but does not specify every file that the script writes, so do not build automation around assumed paths without reviewing the current script.

After installation, start Numa in the foreground:

sudo numa

Arch Linux with pacman

Install the documented package:

pacman -S numa

Depending on the current user's permissions and the system's package-management policy, the package command may need to be run with elevated privileges. The authoritative command in the supplied project evidence is shown above. Start the resolver for an initial foreground test with:

sudo numa

Windows from a release download

For Windows, the documented path is to download Numa from the project's GitHub Releases page. Select a release asset that matches the Windows system and processor architecture, extract it if the asset is archived, and place the executable in a controlled location.

The available evidence does not establish an exact current Windows asset filename, archive layout, installation directory, or whether the download automatically modifies PATH. We therefore do not invent those details. Run the executable from its actual extracted directory, or add that directory to PATH using your normal Windows administration process.

Start Numa from an elevated terminal for a foreground test:

numa

Windows has a special DNS binding behavior. The built-in DNS cache service owns 127.0.0.1:53, so Numa binds 127.0.0.2:53 and installs a Name Resolution Policy Table rule when configured through its system installation workflow. If you edit bind_addr or api_bind_addr for that setup, use the documented Windows behavior as your reference rather than assuming that every Numa endpoint must bind to 127.0.0.1.

All-platform Cargo installation

If a working Rust toolchain and Cargo are already installed, use:

cargo install numa

After Cargo completes, make sure Cargo's binary directory is available through the current shell's PATH. The evidence does not specify a minimum Rust version for end-user source installation, so if compilation fails, inspect the error and the current project requirements rather than guessing a toolchain version.

Start Numa with:

sudo numa

On Windows, run the command in an administrator terminal instead of using sudo.

Nix

Run the documented repository target through Nix:

nix run github:razvandimescu/numa

Whether additional privileges are needed depends on the resulting listener configuration, especially binding port 53. The project quick start also documents running Numa with administrator privileges for the default DNS port.

Docker on Linux with host networking

The recommended documented Linux container command uses host networking:

docker run -d --name numa --network host ghcr.io/razvandimescu/numa

With host networking, the container shares the host network namespace. The dashboard should then be reachable on the host at http://localhost:5380, assuming Numa starts successfully and no conflicting service owns the required ports.

Docker Desktop on macOS or Windows

The documented Docker Desktop command explicitly publishes both DNS transports and the HTTP dashboard:

docker run -d --name numa -p 53:53/udp -p 53:53/tcp -p 5380:5380 ghcr.io/razvandimescu/numa

This maps host UDP port 53, host TCP port 53, and host TCP port 5380 to the corresponding container ports. The image binds its API and proxy to 0.0.0.0 by default. Port mapping makes the dashboard available through http://localhost:5380 on the Docker host.

Docker with a custom configuration file

On a Linux host using host networking, the project documents mounting a custom configuration file at the following container path:

docker run -d --name numa --network host \
  -v /path/to/numa.toml:/root/.config/numa/numa.toml \
  ghcr.io/razvandimescu/numa

Replace /path/to/numa.toml with the real host path to your configuration. Do not copy a placeholder literally. This exact mount target is documented for the container workflow. Native configuration paths can differ, so use Numa's effective-configuration commands rather than assuming that a native installation reads the container path.

Install Numa as a persistent system service

A foreground process is useful for initial diagnostics, but it ends when the terminal closes or the process is interrupted. Once local verification succeeds, Numa can install itself into the operating system's startup mechanism. On macOS and Linux it runs as a service through launchd or systemd. On Windows it is configured to start automatically at login through the registry.

To remove the operating-system integration on macOS or Linux, use:

sudo numa uninstall

On Windows, run the following from an administrator terminal and then reboot:

numa uninstall

Uninstalling the service integration and deleting configuration or data are not necessarily the same operation. The supplied evidence does not define a universal data-removal procedure, so inspect your effective configuration and preserve any files you need before removing a deployment.

Verify Numa locally before adding remote access

Local verification isolates Numa issues from tunnel issues. If the dashboard does not work on the host, a Localtonet tunnel cannot make it healthy. Confirm the process, HTTP endpoint, and installation mode in that order.

curl http://localhost:5380

The exact HTML returned by the dashboard can change between Numa releases, so this guide does not prescribe a fragile text match. The useful result is a successful HTTP response from the expected service rather than a connection-refused, timeout, or unrelated application response.

Configuration, upgrades, and routine operation

Find the effective configuration

Numa v0.23.0 includes commands for identifying and editing the configuration used by the running service:

numa config path
numa config edit

This is safer than assuming a native configuration path based on another operating system or on the Docker example. Use numa config path to identify the effective file. Use numa config edit when you intend to modify that configuration.

Configuration changes can affect DNS binding, API binding, recursive behavior, DNSSEC, DNS-over-TLS, mobile setup, local services, and other capabilities. Change one concern at a time, restart through the appropriate service or container workflow, and repeat local dashboard verification.

Understand the resolution modes

Create a local developer service mapping

Numa can associate a local service name with a development port through its REST API. The documented example creates frontend.numa for a service on port 5173:

curl -X POST localhost:5380/services \
  -d ' {"name":"frontend","target_port":5173} '

This is separate from the Localtonet tunnel. A .numa name is handled by Numa for local service discovery and proxying, while the Localtonet HTTP tunnel creates a public address for the dashboard target. Do not assume that a remote browser can resolve a local .numa name merely because the dashboard is tunneled.

Operate the Docker container

Use normal Docker lifecycle commands to inspect and control the container:

docker ps
docker logs numa
docker stop numa
docker start numa

Before replacing a container during an upgrade, identify whether configuration or other persistent state is mounted outside the container. The documented custom configuration example mounts numa.toml, but the supplied evidence does not define a complete persistence and backup policy for every Numa data file. Do not delete a container on the assumption that all relevant state is external.

Review release notes before upgrading

Resolver software is security-sensitive infrastructure. Numa v0.23.0 included recursive-resolver hardening, stricter reply validation, protections around referrals and nameserver addresses, query-work limits, and corrections to ad-blocking list handling. It also added per-source blocking health reporting and retained a last-known-good copy of remote lists.

If an existing numa.toml explicitly pins an older HaGeZi hosts/ or domains/ URL, the release notes state that it must be changed to the corresponding wildcard/ source. The newer default applies automatically only when the source was not overridden. This is an example of why an upgrade should include configuration review and dashboard verification rather than only replacing the binary.

Access the Numa dashboard remotely with Localtonet

Once http://localhost:5380 works locally, the HTTP dashboard can be exposed through Localtonet. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes.

An HTTP tunnel points a public HTTPS address to the Numa HTTP service. Creating the tunnel configuration does not automatically make it active. The selected Localtonet device must be connected and the tunnel must be started. The public address remains available only while that client is connected and the tunnel is running.

For the current dashboard fields and supported HTTP options, consult the Localtonet HTTP tunnel documentation while configuring the tunnel. The essential target for this workflow is Numa's HTTP service on port 5380, not its DNS listeners.

Security boundaries and a safer exposure model

The safest workflow starts with the narrowest required endpoint. Remote dashboard access requires HTTP port 5380. It does not require publishing raw DNS on port 53, DNS-over-TLS on port 853, unrelated local services, or the whole host network.

Localtonet terminates the public HTTP process type at a public HTTPS address and forwards traffic to the configured local HTTP target. This protects the public browser connection at the tunnel edge, but it does not answer whether every user should be authorized to administer Numa. Authorization remains a separate application and deployment decision.

If the dashboard cannot be adequately restricted for your threat model, do not leave it publicly reachable. Start the tunnel only for short administrative sessions, share the address only with intended operators, and stop it immediately afterward. If your requirements call for private network membership rather than a public URL, evaluate that architecture separately instead of presenting a standard HTTP tunnel as a VPN.

Troubleshooting Numa and Localtonet

The dashboard does not open locally

First confirm that Numa is still running. A foreground process ends when its terminal closes. A system installation can fail to start because a required port is occupied or the configuration is invalid. A Docker container may start and then exit immediately.

For Docker, inspect the container and its logs:

docker ps
docker logs numa

Then test the direct endpoint:

curl http://localhost:5380

A connection-refused error usually means nothing is listening at that address and port. A timeout can indicate an address, bind, container, or filtering problem. An unexpected page suggests another application may own port 5380.

Numa reports that an address is already in use

The most likely conflicts are the DNS listener on port 53 or the dashboard on port 5380. Stop duplicate Numa processes and identify whether another resolver, web application, or container owns the port. On Windows, remember that the built-in DNS cache service owns 127.0.0.1:53 and Numa's documented installed behavior uses 127.0.0.2:53.

Do not change ports blindly. A nonstandard DNS port will not automatically be used by operating-system clients. If only the dashboard port changes, the Localtonet tunnel target must be updated to match the verified endpoint.

The Docker container works internally but not from the host

On Linux, use the documented host-network command when that network mode fits your environment. On Docker Desktop, confirm that -p 5380:5380 is present. The documented image binds the API and proxy to 0.0.0.0 by default, but a custom configuration can alter binding behavior.

If a custom numa.toml is mounted, verify the mount path and inspect the effective settings rather than assuming the defaults still apply.

The Localtonet tunnel starts but the public address fails

Test the target from the device running the Localtonet client. If the client runs on the Numa host, verify http://localhost:5380 there. If the client runs on a different device, test the actual Numa host address from that device. A loopback address on the second machine will not reach Numa on the first machine.

Also confirm that the selected Localtonet device is connected, the correct HTTP tunnel is running, and the target port is 5380. Creating a tunnel does not start it. The public endpoint works only while the selected client remains connected and the tunnel remains active.

The public page is not the expected dashboard

Stop the tunnel and confirm the local target. Check whether a different application is listening on port 5380, whether the target IP belongs to the intended Numa host, and whether multiple Numa environments are running. Restart the tunnel only after the local response clearly identifies the expected instance.

Numa works in forward mode but recursive mode does not

Forward and recursive modes have different network requirements. Forward mode uses the existing system DNS and is designed to preserve captive portal, VPN, and corporate DNS behavior. Recursive mode contacts root and authoritative DNS infrastructure directly. Networks can block or interfere with that traffic.

Numa's auto mode probes root-server reachability at startup, uses recursive resolution when available, and falls back to encrypted DNS-over-HTTPS when direct recursion is blocked. Changing resolution mode is a Numa configuration decision and is independent of the Localtonet dashboard tunnel.

Ad blocking appears empty or unhealthy after an upgrade

Numa v0.23.0 changed the default HaGeZi source after older hosts/ and domains/ formats were discontinued. If your configuration pins one of those older URLs, update it to the documented wildcard/ source. The newer release reports per-source health through /blocking/stats and retains a last-known-good disk copy for upstream outages.

Do not assume that upgrading the binary replaces an explicit custom source. Review the effective configuration with numa config path or numa config edit.

Frequently asked questions