devns

Domain lokal https://<nama>.test tanpa port untuk macOS.

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

Satu CLI yang menyiapkan semuanya: dnsmasq (wildcard *.test → 127.0.0.1), Caddy (satu-satunya pemegang port 80/443, HTTPS otomatis via internal CA), dan opsional bridge DoH lokal agar browser dengan Secure DNS tetap bisa membuka domain .test.

Kenapa dibutuhkan?

Tanpa devns	Dengan devns
http://localhost:7337	https://pueue.test
Port bentrok antar project	Nama unik per project, tanpa port di URL
HTTP polos	HTTPS trusted (cookie Secure, service worker, clipboard API jalan)
Secure DNS browser mematikan domain lokal	Bridge DoH: .test lokal, sisanya tetap terenkripsi ke cloud

Install

Butuh: 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 menyiapkan:

1. brew install dnsmasq caddy bila belum ada
2. /etc/resolver/test → macOS me-routing TLD .test ke 127.0.0.1
3. Blok address=/.test/127.0.0.1 di dnsmasq.conf + service root di :53
4. Caddyfile utama (import ~/.config/devns/sites/*.caddy) + service root 80/443
5. CA internal Caddy ke system trust store (sudo caddy trust)
6. Bridge DoH (dnsproxy dari AdGuard — binary auto-download sesuai OS/arch)

Sehari-hari tanpa sudo sama sekali: add/rm/ls/open/doctor/doh/log.

Pakai

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 dengan Secure DNS

Setelah devns doh install, setel Secure DNS ke Custom: https://dns.test:8443/dns-query. Query .test dijawab lokal, semua query lain diteruskan terenkripsi ke upstream DoH pilihanmu (default OpenDNS).

Arsitektur

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 = satu-satunya sumber kebenaran
• Site files: ~/.config/devns/sites/<nama>.caddy (artefak generate; template pakai flush_interval -1 agar SSE tidak ter-buffer)
• Reload harian: admin endpoint Caddy localhost:2019 dengan header Content-Type: text/caddyfile

MCP server

devns menyertakan server MCP stdio tanpa dependency tambahan:

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 untuk AI agent

Repo ini menyertakan skill portabel di skills/devns/SKILL.md (format agentskills.io / Claude skills). Salin atau symlink ke direktori skills agent-mu.

Catatan desain (pelajaran nyata)

• Wildcard *.test ditolak verifier modern — Chrome & curl menolak cert wildcard yang menempel langsung ke TLD walau SAN valid secara RFC. Karena itu cert dibuat per-hostname on-demand oleh CA internal Caddy.
• Port 5353 sudah dipakai mDNSResponder (Bonjour) → bridge DoH memakai 5335.
• /etc/resolver/test membuat resolve menggantung (bukan gagal cepat) saat dnsmasq mati — itu tanda resolver aktif, bukan bug.

License

MIT