DNS Override

DNS Override lets you control where specific domain names resolve, without modifying /etc/hosts or any other system file. Overrides apply only to traffic flowing through HTTPeep, so there are no system-wide side effects and no risk of leaving stale entries that break other applications. You can switch between environments in seconds and revert just as quickly.

Why DNS Override instead of /etc/hosts

Editing /etc/hosts is a common workaround for redirecting a domain to a different IP, but it has several practical problems:

• It requires elevated privileges (sudo/admin) to edit
• It applies globally to every process on the machine, including processes you don't intend to affect
• Stale entries persist silently and can cause confusing failures later
• You must manually undo changes when you're done

HTTPeep's DNS Override is scoped to the proxy. It applies only to requests that pass through HTTPeep, requires no system permissions, and can be toggled or changed at any time from the UI or by editing dns_override.yaml.

Configuration

DNS overrides are stored in ~/.httpeep/rules/dns_override.yaml. You can edit this file directly or manage overrides through the DNS Override panel in the UI.

The file uses four top-level keys:

• enabled: global on/off switch for DNS Override
• activeEnv: selected environment name
• environments.<name>.hosts: environment-scoped host mappings
• globalHosts: host mappings that apply to all environments

Basic override

Map a single domain to a specific IP address:

# dns_override.yaml
enabled: true
activeEnv: prod
environments:
  prod:
    hosts:
      api.example.com:
        ip: 127.0.0.1
        enabled: true
      payments.example.com:
        ip: 192.168.1.42
        enabled: true

Wildcard domains

Use * to match all subdomains of a domain:

enabled: true
activeEnv: prod
globalHosts:
  "*.example.com":
    ip: 127.0.0.1
    enabled: true
environments:
  prod:
    hosts: {}

This redirects api.example.com, auth.example.com, www.example.com, and any other subdomain to 127.0.0.1.

Environment groups

A common workflow is switching between dev, staging, and production environments. DNS Override supports named environment groups that let you define multiple sets of overrides and activate the one you need:

# dns_override.yaml
enabled: true
activeEnv: dev
environments:
  dev:
    hosts:
      api.example.com:
        ip: 127.0.0.1
        enabled: true
      "*.example.com":
        ip: 127.0.0.1
        enabled: true
  staging:
    hosts:
      api.example.com:
        ip: 10.0.1.50
        enabled: true
      "*.example.com":
        ip: 10.0.1.50
        enabled: true
  prod:
    hosts: {}
globalHosts: {}

Switch the default environment in the UI's DNS Override panel or by editing the activeEnv field in the YAML file. All overrides for the selected environment take effect immediately.

Switching environments

Global overrides vs environment overrides

You can combine a set of global overrides that always apply with environment-specific overrides that vary:

# dns_override.yaml
enabled: true
activeEnv: dev
globalHosts:
  internal-tool.corp.example.com:
    ip: 10.0.0.5
    enabled: true
environments:
  dev:
    hosts:
      api.example.com:
        ip: 127.0.0.1
        enabled: true
  staging:
    hosts:
      api.example.com:
        ip: 10.0.1.50
        enabled: true

globalHosts applies regardless of the selected environment. Environment hosts are layered on top. If the same domain appears in both, the environment host override takes precedence.

Common use cases