devns

本地域名 https://<名称>.test，macOS 上无需端口。

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

一个 CLI 搞定一切：dnsmasq（通配符 *.test → 127.0.0.1）、Caddy（唯一占用 80/443 端口的进程，通过内部 CA 自动启用 HTTPS），以及可选的本地 DoH 桥接，让启用了 Secure DNS 的浏览器也能打开 .test 域名。

为什么需要它？

Related MCP server: DDEV MCP Server

安装

需要：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 会配置：

1. 若尚未安装，则 brew install dnsmasq caddy

2. /etc/resolver/test → 让 macOS 将 .test TLD 路由到 127.0.0.1

3. 在 dnsmasq.conf 中添加 address=/.test/127.0.0.1 块，并将服务以 root 身份运行在 :53 端口

4. 主 Caddyfile（import ~/.config/devns/sites/*.caddy），服务以 root 身份运行在 80/443 端口

5. 将 Caddy 内部 CA 加入系统信任库（sudo caddy trust）

6. DoH 桥接（AdGuard 的 dnsproxy —— 根据 OS/arch 自动下载二进制文件）

日常使用完全不需要 sudo：add/rm/ls/open/doctor/doh/log。

使用方法

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

使用 Secure DNS 的浏览器

执行 devns doh install 后，将 Secure DNS 设置为 Custom：https://dns.test:8443/dns-query。 .test 查询在本地应答，所有其他查询则加密转发到你选择的 DoH 上游（默认为 OpenDNS）。

架构

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

• 注册表：~/.config/devns/registry.yaml = 唯一的事实来源

• 站点文件：~/.config/devns/sites/<名称>.caddy（生成的产物；模板使用 flush_interval -1 以避免 SSE 被缓冲）

• 每日重载：通过 Caddy 管理端点 localhost:2019，请求头带 Content-Type: text/caddyfile

MCP 服务器

devns 附带一个 stdio MCP 服务器，无额外依赖：

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

工具：list_domains、add_domain、remove_domain、check_health、doh_status。

面向 AI agent 的技能

本仓库在 skills/devns/SKILL.md 中附带了一个可移植技能（agentskills.io / Claude skills 格式）。将其复制或符号链接到你的 agent 技能目录中。

设计说明（实战经验）

• 通配符 *.test 会被现代验证器拒绝 —— 即使 SAN 在 RFC 层面有效，Chrome 和 curl 也会拒绝直接挂在 TLD 上的通配符证书。因此证书由 Caddy 内部 CA 按主机名按需签发。

• 5353 端口已被 mDNSResponder（Bonjour）占用 → DoH 桥接改用 5335 端口。

• /etc/resolver/test 会在 dnsmasq 停止时导致解析挂起（而非快速失败）—— 这是解析器处于活动状态的标志，不是 bug。

许可证

MIT