devns

Lokale Domain https://<name>.test ohne Port für macOS.

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

Ein einziges CLI, das alles einrichtet: dnsmasq (Wildcard *.test → 127.0.0.1), Caddy (einziger Inhaber von Port 80/443, automatisches HTTPS über interne CA) und optional eine lokale DoH-Brücke, damit Browser mit Secure DNS weiterhin .test-Domains öffnen können.

Warum wird es benötigt?

Related MCP server: DDEV MCP Server

Installation

Erforderlich: 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 richtet Folgendes ein:

1. brew install dnsmasq caddy, falls noch nicht vorhanden

2. /etc/resolver/test → macOS leitet die TLD .test an 127.0.0.1 weiter

3. Block address=/.test/127.0.0.1 in dnsmasq.conf + Service-Root auf :53

4. Haupt-Caddyfile (import ~/.config/devns/sites/*.caddy) + Service-Root auf 80/443

5. Interne Caddy-CA im System-Trust-Store (sudo caddy trust)

6. DoH-Brücke (dnsproxy von AdGuard — Binary wird automatisch je nach OS/arch heruntergeladen)

Im Alltag ganz ohne sudo: add/rm/ls/open/doctor/doh/log.

Verwendung

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

Browser mit Secure DNS

Nach devns doh install Secure DNS auf Custom setzen: https://dns.test:8443/dns-query. .test-Anfragen werden lokal beantwortet, alle anderen Anfragen werden verschlüsselt an den gewählten DoH-Upstream weitergeleitet (Standard: OpenDNS).

Architektur

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 = einzige Quelle der Wahrheit

• Site-Dateien: ~/.config/devns/sites/<name>.caddy (generierte Artefakte; Vorlage verwendet flush_interval -1, damit SSE nicht gepuffert wird)

• Tägliches Reload: Caddy-Admin-Endpunkt localhost:2019 mit Header Content-Type: text/caddyfile

MCP-Server

devns enthält einen stdio-MCP-Server ohne zusätzliche Abhängigkeiten:

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 für KI-Agenten

Dieses Repository enthält einen portablen Skill unter skills/devns/SKILL.md (Format agentskills.io / Claude skills). Kopiere ihn oder verlinke ihn per Symlink in das Skill-Verzeichnis deines Agenten.

Design-Notizen (praktische Erkenntnisse)

• Wildcard *.test wird von modernen Verifiern abgelehnt — Chrome und curl lehnen Wildcard-Zertifikate ab, die direkt an der TLD hängen, selbst wenn die SANs RFC-konform sind. Deshalb werden Zertifikate pro Hostname on-demand von der internen Caddy-CA erstellt.

• Port 5353 ist bereits von mDNSResponder (Bonjour) belegt → die DoH-Brücke verwendet 5335.

• /etc/resolver/test lässt die Auflösung hängen (kein schneller Fehlschlag), wenn dnsmasq aus ist — das ist ein Zeichen für einen aktiven Resolver, kein Bug.

Lizenz

MIT