Build a local DNS service first, verify it carefully, then publish only its web dashboard
Numa is a self-hostable DNS resolver with a browser dashboard, caching, ad blocking, local service names, hostname overrides, and multiple resolution modes. In this guide, we install Numa on Linux, test DNS without immediately changing the operating system resolver, optionally register it as a system service, and verify the dashboard at http://localhost:5380. Once the local installation works, we connect that dashboard to an HTTP tunnel with Localtonet. We deliberately keep the DNS listeners private because exposing a recursive DNS service publicly creates a different and substantially riskier security problem than providing controlled access to its administrative dashboard.
📋 What's in this guide
Understand what Numa runs and what we will expose
A DNS resolver and a web dashboard are separate network surfaces even when one application provides both. Numa normally listens for conventional DNS queries on UDP and TCP port 53. It also supports a DNS-over-TLS listener on port 853. Its administrative dashboard and REST API are served over HTTP on port 5380, with the documented local address http://localhost:5380.
This distinction determines the correct Localtonet integration. The dashboard is an HTTP application, so an HTTP tunnel can point to its local IP address and port. DNS on port 53 is not an HTTP application. It involves UDP and TCP behavior, recursion policy, client controls, and abuse risks that should not be treated as ordinary web publishing.
Our workflow therefore has two separate phases. First, Numa must operate correctly on the Linux host. Second, after local verification succeeds, the Localtonet client on that host creates an outbound connection to one of our relay servers and publishes the dashboard through a public HTTPS address. No inbound router port forwarding, public IP address, VPN setup, or inbound firewall change is required for that tunnel workflow.
sudo numa starts the resolver without automatically making it the host's system resolver. This creates a useful test stage before system-wide changes.
sudo numa install registers a systemd service, points system DNS at Numa, and installs trust for Numa's local certificate authority.
sudo numa token prints the current token and where it was loaded from.
Why the dashboard is the appropriate remote target
An open recursive DNS server can be abused by arbitrary internet clients, including as part of reflection or amplification activity. It can also reveal policy and operational information that was intended only for trusted clients. Publishing DNS safely requires explicit access-control design, transport decisions, query policy, monitoring, and protection against abuse. A dashboard tunnel does not solve those DNS-service concerns.
The dashboard is still sensitive. Numa's HTTP control plane can inspect operational information and mutate how DNS resolution behaves. It is not a harmless status page. The correct conclusion is not that the dashboard can be exposed casually, but that it is the narrowly scoped HTTP endpoint suited to this guide. Use Numa's token, restrict who receives the URL and token, stop the tunnel when it is no longer needed, and follow the principle of least privilege around the Linux host.
An HTTP tunnel must target Numa's dashboard on port 5380, not its UDP or TCP DNS listener. This guide does not publish port 53 or port 853 to the public internet. If your actual objective is network-wide DNS, configure trusted LAN clients or another explicitly secured private-network design instead of creating an unrestricted public resolver.
| Interface | Documented port | Role in this guide |
|---|---|---|
| DNS over UDP | 53/udp |
Test locally with dig; do not publish through the dashboard tunnel. |
| DNS over TCP | 53/tcp |
Part of normal DNS service behavior; keep private in this workflow. |
| DNS over TLS | 853/tcp |
Optional encrypted DNS listener for compatible clients; outside this HTTP dashboard workflow. |
| Dashboard and REST API | 5380/tcp |
Verify at http://localhost:5380, then use as the Localtonet HTTP target. |
Check the Linux host and prerequisites
Choose a Linux machine that can remain online whenever Numa or the remote dashboard is needed. A tunnel is not independent hosting. The Numa process, the Localtonet client, the selected device connection, and the tunnel all need to be running for the public address to work.
You need administrative privileges because binding to port 53 requires elevated capability and because system service installation modifies resolver and trust configuration. You also need a shell, internet access for the chosen installation method, and a DNS query utility such as dig for direct verification. The supplied project evidence documents the dig test but does not provide one universal package-manager command for installing dig across all Linux distributions. Install the DNS utility package appropriate to your distribution if the command is missing.
Before changing anything, identify whether port 53 is already occupied. Ubuntu, Linux Mint, NetworkManager configurations, systemd-resolved, dnsmasq, another DNS server, or a previous resolver installation may already own it. The Numa documentation specifically notes that systemd-resolved commonly occupies port 53 on Ubuntu and Mint. Numa's installer can reconfigure systemd-resolved, but another process such as dnsmasq may have to be stopped manually.
The exact port-inspection utility available depends on the distribution. If ss is installed, the following command is a useful read-only check:
sudo ss -lntup | grep ':53 'An empty result does not prove that every future bind will succeed, but a result naming another process is a clear signal to investigate before starting Numa. Do not stop a resolver blindly on a remote server. Doing so can break name resolution and make package downloads or remote administration fail.
Choose the least disruptive installation path
Numa documents several installation methods, but this Linux guide concentrates on three practical paths: the project's installation script, the Arch Linux package, and Cargo. Docker is also useful for an isolated evaluation because it avoids changing the host DNS and maps the container's DNS port to host port 5553.
| Method | Best suited to | Important behavior |
|---|---|---|
| Linux install script | A direct Linux binary installation | Installs the binary at /usr/local/bin/numa according to the documented cleanup information. |
| Arch package | Arch Linux users who prefer package management | Uses pacman -S numa; removal uses pacman -R. |
| Cargo | Users with a working Rust toolchain | Uses cargo install numa. Service installation may copy a binary that cannot run from its original location into /usr/local/bin/numa. |
| Docker | Evaluation without changing host DNS | Maps host port 5553 to container port 53 and keeps the dashboard on host loopback port 5380. |
The documented Linux command downloads the project's current install.sh and pipes it to a shell. That is convenient, but it executes remote content. In a security-sensitive or controlled environment, download and inspect the script first, verify that it comes from the expected project repository, and then run the reviewed copy according to your organization's software-installation policy.
Install and start Numa on Linux
The safest sequence is to install the binary, run Numa in the foreground, test it directly, and only then decide whether it should become the machine's system DNS service. This keeps the first test reversible and isolates installation problems from system resolver changes.
Option A: Install with the documented Linux script
Run the project's documented installer:
curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | shAfter installation, confirm that the shell can locate the executable:
command -v numa
The documented cleanup details identify /usr/local/bin/numa as the binary location used by the Linux installation script. If command -v cannot find it, start a new shell or inspect the installer result rather than guessing another path.
Option B: Install on Arch Linux
Numa documents installation through pacman:
sudo pacman -S numaConfirm the executable is available:
command -v numaOption C: Install through Cargo
If a compatible Rust toolchain and Cargo are already installed, Numa documents:
cargo install numa
This normally places user-installed Cargo binaries in the Cargo binary directory configured for that account. Do not assume that directory is in the root user's path. Run command -v numa as the user who installed it and invoke the discovered executable when testing.
The project notes that, on Linux, numa install copies a binary that cannot be run from its original location, such as one under ~/.cargo/bin, into /usr/local/bin/numa. Its uninstall operation leaves that copied binary behind. This matters later if you want to remove every installed file.
Start in the foreground without changing system DNS
Run Numa with administrative privileges:
sudo numa
Port 53 normally requires elevated privileges. At this stage, Numa listens for DNS, but the operating system continues using its existing resolver because you have not run numa install. Keep this terminal open and use a second terminal for testing. Press Ctrl-C when you want to stop the foreground process.
Installing a binary is not the same as making Numa the system resolver. Running sudo numa lets you query it explicitly at 127.0.0.1, while ordinary applications continue using the host's current DNS configuration. This separation is useful for validating startup, port availability, query handling, and dashboard access before making persistent changes.
Optional Docker evaluation
If port 53 is already occupied or you want a disposable trial, the documented Docker command binds Numa's DNS service to host loopback port 5553 and its dashboard to host loopback port 5380:
docker run -d --name numa -p 127.0.0.1:5553:53/udp -p 127.0.0.1:5553:53/tcp \
-p 127.0.0.1:5380:5380 ghcr.io/razvandimescu/numaTest containerized DNS using the mapped port:
dig @127.0.0.1 -p 5553 example.comObtain the dashboard token from inside the container:
docker exec numa numa token
Then open http://localhost:5380. For this Docker mapping, Numa asks for authentication. The documented login behavior accepts any username and uses the generated token as the password. Because the host is not using Numa as its DNS resolver in this trial, the special numa.numa name will not resolve from the host.
Remove the trial container when finished:
docker rm -f numaChoose whether Numa should become the system DNS service
Do not make this change merely because the foreground test started. First confirm that direct DNS queries return valid answers and that the dashboard opens locally. Once those tests pass, decide whether this Linux machine should route its own DNS through Numa.
Numa documents three resolution modes. The default forward mode proxies requests through the existing system DNS while adding Numa's caching and blocking behavior. This preserves compatibility with environments such as captive portals, VPNs, corporate DNS, and local search domains. The recursive mode resolves from root nameservers and can optionally enable full DNSSEC chain-of-trust validation. The auto mode probes root-server reachability during startup, uses recursive resolution when available, and otherwise falls back to DNS over HTTPS through Quad9.
Those modes affect how Numa resolves queries after receiving them. They do not change the dashboard tunnel procedure. For a first deployment, avoid modifying advanced resolver settings and the remote-access layer simultaneously. Establish a working baseline, then make one controlled change at a time.
Install the Linux system service
When you are ready for persistent operation, stop the foreground process with Ctrl-C and run:
sudo numa install
On Linux, this registers Numa as a systemd service, configures the system to use Numa for DNS, and trusts Numa's local certificate authority. The service is designed to start on boot and restart automatically. The documented systemd unit uses DynamicUser=yes and only the CAP_NET_BIND_SERVICE capability rather than running the resolver process as an unrestricted root service.
The installer reconfigures systemd-resolved through a drop-in, and numa uninstall removes that drop-in. A separate process holding port 53, including some dnsmasq or NetworkManager arrangements, must be handled manually. If the install reports a port conflict, do not disable services until you understand their role on that host.
Know what configuration persists
Numa's Linux root daemon stores persistent data under /var/lib/numa. It can also use ~/.config/numa for user configuration, and the project supports configuration through numa.toml. If you explicitly set a different data_dir, that custom path also needs to be considered during backup or complete removal.
Uninstalling the service restores DNS configuration but intentionally retains the data directory. A later reinstall therefore keeps the same generated token and local certificate authority unless you remove the retained data yourself. This is helpful for continuity, but it also means uninstalling alone is not credential erasure.
Use foreground testing before sudo numa install, especially on a remotely administered Linux machine. Keep an existing administrative session open while validating the new resolver. If name resolution fails, use sudo numa uninstall to reverse Numa's service, DNS, and trust-store changes rather than manually deleting resolver files.
Verify DNS, service state, dashboard access, and authentication
Verification should be layered. A successful process start does not prove that DNS answers correctly. A successful DNS query does not prove that the host is using Numa as its resolver. A working dashboard on loopback does not prove that a non-loopback request will require authentication. Check each property separately.
Query Numa directly
While running in the foreground, execute dig @127.0.0.1 example.com. For the documented Docker mapping, use dig @127.0.0.1 -p 5553 example.com. A valid DNS response confirms that the listener accepted and processed the explicit query.
Open the local dashboard
On the Linux host, open http://localhost:5380. If the host has no graphical browser, use an SSH port-forwarding method approved for your environment or an HTTP client to check whether the endpoint responds. Do not create the public tunnel merely to diagnose an unverified local service.
Retrieve and protect the token
Run sudo numa token for a native service, or docker exec numa numa token for the documented container. Treat the printed value as a credential. Do not place it in screenshots, shell transcripts, tunnel names, public tickets, or shared documentation.
Confirm system resolver state
After running sudo numa install, use numa service status. Current Numa behavior reports the resolver the operating system actually uses, which helps identify a host that is running Numa but no longer sending normal system queries to it.
Test an ordinary lookup
Run dig example.com without an explicit server after system installation. Compare that result with the direct query and the service-status output. This checks the host's normal resolver path rather than only Numa's listener.
dig @127.0.0.1 example.com
sudo numa token
numa service status
dig example.comUnderstand Numa's dashboard authentication boundary
Numa permits dashboard access without a login for recognized local hosts such as localhost, 127.0.0.1, IP literals, and .numa names under its documented loopback behavior. Requests arriving through other hostnames, a LAN address, or a Docker port mapping require the API token. The browser can prompt for credentials using any username and the token as the password.
Current Numa behavior also guards against a DNS-rebinding scenario. A loopback connection does not receive an automatic authentication exemption when the HTTP Host identifies a foreign domain. This is important for reverse proxies and tunnels because the TCP connection can terminate on loopback while the browser is visiting a public hostname.
That protection is exactly why remote verification must include an authentication test. Open the future public URL in a private browser window where no Numa credentials are cached. The expected safe outcome is an authentication challenge before dashboard content appears. If dashboard content is available remotely without a token, stop the Localtonet tunnel and investigate Numa's bind address, version, host-header behavior, and any intermediary proxy configuration.
Numa documents its API token as protection against unauthorized use, not as encryption for plain HTTP. The public side of a Localtonet HTTP tunnel uses an HTTPS address, while the configured local target remains Numa's HTTP endpoint. Do not represent the Numa token as a replacement for secure transport, host security, or access controls.
Reach the verified Numa dashboard remotely with Localtonet
Begin this phase only after http://localhost:5380 works on the same machine that will run our client. Localtonet forwards traffic to a local target that the connected device can reach. It does not repair a stopped process, resolve a port conflict, or configure Numa on your behalf.
For this use case, select an HTTP tunnel. HTTP and File Server tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, with availability and exact choices depending on the current dashboard and plan. All three process types serve content at a public HTTPS address. Do not hardcode a relay server code or region from an article because available values must come from the current Localtonet dashboard.
The documented Localtonet workflow separates tunnel creation from tunnel startup. Saving or creating a tunnel does not make it live. You must start it, and the selected device must remain connected.
Install and run the Localtonet client
Install our client on the Linux device that runs Numa, or on a device that can reliably reach its dashboard target. Start the client before creating the tunnel. Use the current Localtonet installation instructions for the selected Linux distribution rather than copying an unverified command.
Authenticate or select the device
Use the device-specific authentication token through the supported client or dashboard workflow. Never paste that token into the Numa configuration, article notes, screenshots, public repositories, or the tunnel's public URL.
Select an available relay server
Choose from the relay servers or regions currently offered in your Localtonet dashboard. Availability can vary, so this guide intentionally does not invent or hardcode a server code.
Create an HTTP tunnel to the dashboard
Choose an HTTP tunnel and configure its local target as the Numa dashboard address reachable from the client device. When both applications run directly on the same host, use local IP 127.0.0.1 and port 5380. Choose the available process type appropriate to your account.
Start the tunnel
Use the Start button after the tunnel has been created. Creation alone does not make it active. Wait until the selected client device and the tunnel show a connected or running state before testing the assigned address.
Open and validate the public HTTPS address
Visit the assigned public URL from a different network or browser session. Confirm that Numa requests the API token, log in with any username and the token as the password, and verify only the intended dashboard is reachable. Stop or delete the tunnel when remote access is no longer required.
For the current dashboard sequence and field names, consult our
Localtonet HTTP tunnel documentation.
The local target for this specific workflow is 127.0.0.1:5380 only when the Localtonet client and native Numa service share a host.
Account for container networking
The supplied Docker command publishes container port 5380 on the host's 127.0.0.1:5380. If the Localtonet client runs directly on that same host, it can use the published loopback target. If our client runs in a different container, 127.0.0.1 refers to the Localtonet client's own container rather than the Numa container. The correct address then depends on the container network you created.
This guide does not invent a container hostname or Docker Compose service name because none is established by the documented standalone command. Either run the Localtonet client on the host and use the published loopback port, or deliberately create and document a container network where the Numa dashboard is reachable by a known internal name.
Validate the exposure boundary
Test more than whether the page loads. Use a private browser window, a device that has never authenticated, or cleared credentials. Confirm that the public URL challenges for Numa's token. After login, confirm the page is actually your expected Numa instance and that administrative functions behave normally.
Also test the negative cases. Stop the Localtonet tunnel and confirm that its public endpoint no longer reaches the dashboard. Start it again and confirm access returns. Stop Numa and confirm the public endpoint cannot display a stale impression of a working control plane. Finally, restart the Linux host if persistent operation is required, then verify both Numa's service state and the Localtonet client connection.
A hard-to-guess URL is not authentication. Share neither value publicly, and never embed the Numa token in the URL. Anyone who has both working access to the endpoint and the dashboard credential may be able to change DNS behavior. Recheck authentication after Numa, reverse-proxy, or tunnel configuration changes.
Operate, update, stop, and remove the deployment safely
Routine operation should preserve the separation between the DNS service and remote dashboard access. Numa can remain the host's DNS resolver while the Localtonet HTTP tunnel is stopped. This is often the safer default when remote administration is only occasionally needed.
Starting and stopping remote access
Start the tunnel only when its selected Localtonet device is connected and Numa's dashboard responds locally. When maintenance is complete, use the Stop action. Delete the tunnel if the public endpoint is no longer part of the intended deployment. Remember that stopping or deleting a tunnel does not uninstall Numa and does not restore the host's previous DNS configuration.
Checking service and resolver health
Use the Numa service-status command after network changes, operating-system updates, or resolver configuration changes:
numa service statusThe current status output includes the nameserver the operating system actually uses. This helps distinguish two common states: Numa is running but normal applications are not querying it, or the host points to Numa but the service is unavailable. Also repeat direct and ordinary queries:
dig @127.0.0.1 example.com
dig example.comRecovering the dashboard token
For a native Linux service, print the token with:
sudo numa tokenFor the documented Docker container:
docker exec numa numa token
Numa also supports pinning a token through the [server] api_token setting or the NUMA_API_TOKEN environment variable. Do not switch token-management methods during an incident unless you understand which source takes precedence in your deployment. The numa token command reports where the active token was loaded from, which is useful when diagnosing unexpected credentials.
Uninstalling the system integration
To unregister the Linux service and reverse the DNS and trust-store changes made by installation, run:
sudo numa uninstall
This restores DNS configuration and removes the local certificate-authority trust installed by Numa, but it retains application data. On Linux, retained locations can include /var/lib/numa, /etc/numa, a user-created ~/.config/numa, and any custom [server] data_dir. The binary also remains after some installation paths.
If the installation script was used, its binary is documented at /usr/local/bin/numa. If Cargo was used, cargo uninstall numa removes the Cargo-managed binary, but a copy placed at /usr/local/bin/numa by service installation can remain. Arch users can remove the package with:
sudo pacman -R numaRemove retained data only after uninstalling and only if you intentionally want to delete the token, local certificate authority, and persistent Numa state. Before deleting anything, verify the path and preserve any configuration that may be needed for rollback or audit purposes.
Troubleshoot installation, DNS, dashboard, and tunnel failures
Numa cannot bind to port 53
Another resolver probably owns the port. Inspect listeners and identify the process. On Ubuntu or Mint, systemd-resolved is a common reason. During persistent installation, Numa configures systemd-resolved through a drop-in. Other holders, including dnsmasq, may need separate attention.
For an evaluation, Docker's host port 5553 mapping avoids the conflict. Numa also supports changing bind_addr in numa.toml, but the supplied evidence does not establish a universal configuration file path for every user-run scenario. Do not guess one. Use the active configuration location for the installation method and user account you selected.
Direct queries work, but ordinary applications do not use Numa
This is expected before sudo numa install. The foreground command starts Numa but leaves system DNS untouched. If service installation has already been completed, run numa service status and compare dig @127.0.0.1 example.com with dig example.com. A difference indicates that the system resolver path, rather than Numa's query engine, needs investigation.
The dashboard does not open on port 5380
First verify that the Numa process is still running. Then check whether another application owns port 5380. Technitium commonly uses the same port. Current Numa behavior keeps DNS serving if the API port is occupied and retries the API bind every five seconds, so working DNS does not necessarily mean that the dashboard is available.
Resolve the port conflict before creating a tunnel. The evidence supplied for this guide does not establish an approved alternative dashboard port configuration, so we do not provide a guessed setting. Consult the active Numa version's configuration guidance if a different API binding is required.
The local dashboard works, but the Localtonet URL fails
Confirm that the Localtonet client is connected, the intended device is selected, and the tunnel was started rather than merely created. Check that the target is 127.0.0.1 and port 5380 when both processes run natively on the same host. If either process runs in a container, reconsider what loopback means from the client's network namespace.
Also test the local target from the exact device or environment running our client. A browser on your laptop reaching a remote server through SSH does not prove that the Localtonet client process can reach the same address.
The public dashboard returns an authentication prompt
That is expected and desirable for a non-local hostname. Use any username and the token printed by sudo numa token as the password. If the credential fails, verify that you copied the token from the same Numa instance being exposed. Reinstallations that retain the data directory can retain the previous token.
The public dashboard opens without authentication
Stop the tunnel immediately and investigate. Confirm the running Numa version, ensure the tunnel is reaching the intended Numa instance, and check whether another reverse proxy rewrites the Host header to a local value. Numa's loopback exemption depends partly on host interpretation. A proxy that makes a remote request appear local can change the expected authentication behavior.
DNS fails after installing the system service
Keep the diagnosis local and reversible. Check numa service status, query Numa directly, and identify whether the service owns port 53. If the host cannot resolve names reliably and the cause is not immediately clear, use:
sudo numa uninstallThis is the documented reversal path for service registration, system DNS changes, and local certificate-authority trust. Avoid manually overwriting resolver configuration unless you have a distribution-specific recovery procedure and understand which service manages the file.
Local network search names fail
Current Numa behavior forwards search domains from resolv.conf, such as lan or fritz.box, to the system resolver. If these names fail, verify the Numa version, the underlying system resolver's ability to answer them, and whether the relevant search-domain configuration is present. On Linux systems without systemd-resolved, current versions keep the resolv.conf backup under /var/lib/numa so the unprivileged service can read it.
Remote access disappears after a reboot
Check each layer independently. Verify that Numa's system service started, that the dashboard responds on localhost:5380, that the Localtonet client is running and authenticated as the expected device, and that the tunnel is running. A persistent Numa service does not automatically guarantee that the Localtonet client or tunnel is active.
Frequently asked questions
Does running Numa automatically change Linux system DNS?
No. Running sudo numa starts Numa in the foreground, but the host continues using its existing resolver. Query Numa directly with dig @127.0.0.1 example.com. Running sudo numa install is the documented step that registers the system service, points system DNS at Numa, and installs trust for its local certificate authority.
Which Numa port should an HTTP tunnel use?
Use the dashboard's HTTP port, 5380. When Numa and the Localtonet client run natively on the same host, the target is 127.0.0.1:5380. Do not use DNS port 53 or DNS-over-TLS port 853 as the target of an HTTP tunnel.
Why does the remote dashboard ask for credentials when localhost does not?
Numa exempts recognized local access from login, but non-loopback access and requests using a foreign hostname require its API token. This protects the administrative interface from remote and DNS-rebinding access. Use any username and the output of sudo numa token as the password.
Can I expose Numa's DNS resolver publicly with the same HTTP tunnel?
No. DNS is not HTTP, and conventional DNS uses both UDP and TCP on port 53. More importantly, publishing a recursive resolver creates abuse and access-control risks that this dashboard guide does not address. Keep the DNS listeners private and expose only the authenticated web dashboard for this workflow.
Does creating a Localtonet tunnel make it immediately available?
No. Tunnel creation and tunnel startup are separate lifecycle actions. After creating the HTTP tunnel, use the Start button. The selected Localtonet client device must remain connected, the tunnel must remain running, and Numa must continue serving its local dashboard.
Why does the Docker example use port 5553 for DNS?
The container still listens on port 53, but the documented command maps it to host loopback port 5553. This avoids a collision with an existing host resolver on port 53. Test it with dig @127.0.0.1 -p 5553 example.com. The dashboard remains mapped to 127.0.0.1:5380.
Does uninstalling Numa delete its token and data?
No. sudo numa uninstall reverses the service, DNS, and trust-store integration but keeps the data directory. A reinstall can therefore retain the same token and certificate authority. Complete removal requires a deliberate review of retained Linux paths, user configuration, custom data directories, and any binary left by the chosen installation method.
Do I need router port forwarding or a public IP address?
Not for the Localtonet dashboard tunnel. Our client establishes an outbound connection to a Localtonet relay server, so the workflow does not require inbound router port forwarding, inbound firewall changes, VPN setup, or a public IP address. Normal organizational authorization and security policy still apply.
Connect your verified Numa dashboard with Localtonet
Install and test Numa locally first, protect its dashboard token, then create an HTTP tunnel to 127.0.0.1:5380. Keep DNS ports private and stop the tunnel whenever remote administration is not required.
