devns

Local domain https://<name>.test without a port for macOS.

devns add webui 8080
# ✓ https://webui.test → 127.0.0.1:8080 (caddy admin load HTTP 200)

One CLI that sets everything up: dnsmasq (wildcard *.test → 127.0.0.1), Caddy (the sole holder of ports 80/443, automatic HTTPS via internal CA), and an optional local DoH bridge so browsers with Secure DNS can still open .test domains.

Why is it needed?

Related MCP server: DDEV MCP Server

Install

Requirements: macOS + uv + Homebrew.

git clone https://github.com/apiep/devns && cd devns
uv tool install --editable .
devns init          # sekali saja — minta sudo interaktif 2-3x
devns doh install   # opsional: bridge DoH utk browser secure-DNS

devns init sets up:

1. brew install dnsmasq caddy if not already installed

2. /etc/resolver/test → macOS routes the .test TLD to 127.0.0.1

3. address=/.test/127.0.0.1 block in dnsmasq.conf + root service on :53

4. Main Caddyfile (import ~/.config/devns/sites/*.caddy) + root service on 80/443

5. Caddy's internal CA added to the system trust store (sudo caddy trust)

6. DoH bridge (dnsproxy from AdGuard — binary auto-downloaded based on OS/arch)

Day-to-day no sudo at all: add/rm/ls/open/doctor/doh/log.

Usage

devns add pueue 7337          # daftarkan domain + reload Caddy + cek port
devns add api 3000 --open     # sekalian buka browser
devns ls                      # ● https://pueue.test → 127.0.0.1:7337
devns open pueue              # buka di browser default
devns rm pueue                # hapus (konfirmasi; -y skip)
devns doctor                  # kesehatan: resolver/DNS/Caddy/HTTPS/DoH

devns doh install             # bridge DoH (LaunchAgent user-level)
devns doh status
devns doh log -f              # ikuti log dnsproxy live

Browsers with Secure DNS

After devns doh install, set Secure DNS to Custom: https://dns.test:8443/dns-query. .test queries are answered locally, all other queries are forwarded encrypted to your chosen DoH upstream (default OpenDNS).

Architecture

Browser ──DoH──> dns.test:8443 (dnsproxy, launchd io.devns.doh)
                   ├─ [/test/] ──> dnsmasq :53 ──> 127.0.0.1
                   └─ lainnya  ──> https://doh.opendns.com/dns-query

Browser ──HTTPS──> Caddy :443 ──reverse_proxy──> 127.0.0.1:<port-app>
        ──HTTP───> Caddy :80  ──308──> HTTPS
                     cert: Caddy Local Authority (tls internal), per-hostname on-demand

• Registry: ~/.config/devns/registry.yaml = the single source of truth

• Site files: ~/.config/devns/sites/<name>.caddy (generated artifacts; the template uses flush_interval -1 so SSE is not buffered)

• Daily reload: Caddy admin endpoint localhost:2019 with the Content-Type: text/caddyfile header

MCP server

devns ships with a stdio MCP server with no extra dependencies:

hermes mcp add devns --command devns-mcp    # Hermes Agent
# atau konfigurasi MCP client lain (Claude Desktop dsb) dengan command "devns-mcp"

Tools: list_domains, add_domain, remove_domain, check_health, doh_status.

Skill for AI agents

This repo includes a portable skill at skills/devns/SKILL.md (agentskills.io / Claude skills format). Copy or symlink it into your agent's skills directory.

Design notes (real-world lessons)

• Wildcard *.test is rejected by modern verifiers — Chrome and curl reject a wildcard cert that attaches directly to a TLD even if the SAN is RFC-valid. That's why certs are generated per-hostname on demand by Caddy's internal CA.

• Port 5353 is already used by mDNSResponder (Bonjour) → the DoH bridge uses 5335.

• /etc/resolver/test makes resolution hang (not fail fast) when dnsmasq is down — that's a sign the resolver is active, not a bug.

License

MIT