> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# dns

> Point a development TLD or one private Route name at an IP address from a macOS operator machine, or remove that override.

The `dns` family changes resolver configuration on the operator machine only. It sends nothing to the Gateway and changes no Route, Route scope, or private DNS record. Use it when a Mac must reach Route domains at a chosen address instead of through Orbit VPN DNS.

[Private DNS](/docs/reference/private-dns) describes resolver selection on managed Nodes and the Router addresses that Orbit VPN DNS returns.

## Commands

| Command | Result |
| - | - |
| [`dns:resolve`](#orbit-dnsresolve) | Set or remove a local resolver override for one TLD or one Route name. |

## orbit dns:resolve

Send every name under a development TLD, or one Route name, to an IP address. `--reset` removes the override.

```bash theme={"dark"}
orbit dns:resolve <name> [target] [--reset] [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `name` | yes | One lowercase DNS label, such as `test`, for a TLD override. A lowercase name with several labels, such as `shop.app.beast`, for a Route name override. No leading dot. |
| `target` | to set | The IPv4 or IPv6 address that the name resolves to. Not accepted with `--reset`. |

| Option | Meaning |
| - | - |
| `--reset` | Remove the local override for the name. |
| `--json` | Return one JSON object. |

```bash theme={"dark"}
orbit dns:resolve beast 192.168.6.20
orbit dns:resolve shop.app.beast 192.168.1.40
orbit dns:resolve shop.app.beast --reset
orbit dns:resolve beast --reset
```

The command runs only on macOS with Homebrew `dnsmasq` installed. It writes `address=/<name>/<target>` to `~/.config/orbit/dnsmasq.d/<name>.conf` and includes that directory from the Homebrew `dnsmasq.conf`. It installs `/etc/resolver/<name>` with `nameserver 127.0.0.1` and restarts the Homebrew `dnsmasq` service. Then it checks that a lookup under the name returns the target, and flushes the macOS resolver cache. Writing the resolver file and restarting the service use `sudo`, so the command can ask for your administrator password.

An override covers the name and every name under it. When a TLD override and a Route name override both exist, the Route name override answers its name, and the TLD override answers the other names under the TLD. Resetting one override leaves the other in place.

Point a Route name at the Cluster Router address to keep the Router path for that Route. Point it at the workload Node's address to reach the Route there directly.

Repeating an identical set or reset changes nothing. A failure never overwrites unrelated resolver configuration.

| Kind | Identity field | Other fields |
| - | - | - |
| TLD | `tld` | `target`, `status`, `changed`, `restart_browser` |
| Route name | `hostname` | `target`, `status`, `changed`, `restart_browser` |

`status` is `resolved`, `already_resolved`, `reset`, or `already_absent`. `restart_browser` is true when the command changed the mapping.

<Note>
  Restart open browsers after a change. A browser reuses an open connection and keeps sending traffic to the old address until it reconnects.
</Note>

| Error code | Meaning |
| - | - |
| `dns.tld_required` | No name was given. |
| `dns.tld_invalid` | The TLD is not one lowercase DNS label. |
| `dns.hostname_invalid` | The Route name is not a lowercase DNS name with several labels. |
| `dns.target_invalid` | The target is not an IP address, or a target was given with `--reset`. |
| `dns.unsupported_platform` | The operator machine is not macOS. Nothing changes. |
| `dns.dnsmasq_missing` | Homebrew `dnsmasq` is not installed. Only a set checks this, and nothing changes. A `--reset` without `dnsmasq` removes the files and then fails with `dns.refresh_failed`. |
| `dns.write_failed` | The configuration or resolver file could not be written. |
| `dns.refresh_failed` | The files changed, but `dnsmasq` could not be restarted or does not answer with the target. |

## Related

* [`node`](/docs/cli/node) sets a Node TLD with `node:add --tld`. Generated Route domains use it when no active Cluster TLD applies.
* [`route`](/docs/cli/route) lists the Route domains.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.