devns

포트 없이 macOS용 로컬 도메인 https://<nama>.test.

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), 그리고 Secure DNS를 사용하는 브라우저에서도 .test 도메인을 열 수 있게 해주는 선택적 로컬 DoH 브리지.

왜 필요한가?

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가 TLD .test를 127.0.0.1로 라우팅

3. dnsmasq.conf의 address=/.test/127.0.0.1 블록 + :53의 service root

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

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

• Registry: ~/.config/devns/registry.yaml = 유일한 진실의 원천

• Site files: ~/.config/devns/sites/<nama>.caddy(생성된 산출물; 템플릿은 SSE 버퍼링을 방지하기 위해 flush_interval -1 사용)

• 일일 리로드: Caddy admin 엔드포인트 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 에이전트용 스킬

이 저장소는 skills/devns/SKILL.md에 이식 가능한 스킬을 포함합니다(agentskills.io / Claude skills 형식). 에이전트의 skills 디렉터리에 복사하거나 symlink하세요.

설계 노트(실제 교훈)

• 와일드카드 *.test는 최신 검증기에서 거부됨 — Chrome과 curl은 SAN이 RFC상 유효하더라도 TLD에 직접 붙은 와일드카드 인증서를 거부합니다. 따라서 인증서는 Caddy 내부 CA가 호스트 이름별로 온디맨드 생성합니다.

• 포트 5353은 mDNSResponder(Bonjour)가 이미 사용 중 → DoH 브리지는 5335를 사용합니다.

• /etc/resolver/test는 dnsmasq가 꺼져 있을 때 resolve를 중단시킵니다(빠른 실패가 아님) — 이는 버그가 아니라 resolver가 활성 상태라는 신호입니다.

라이선스

MIT