mkdev

로컬 개발을 위한 실제 HTTPS — TUI 및 LAN 공유 지원.

mkdev는 *.local에서 신뢰할 수 있는 HTTPS를 실행합니다. 단일 Go 바이너리: 인증 기관 + 리버스 프록시 + /etc/hosts + mDNS 브로드캐스트 + 완전한 TUI.

차별점:

• LAN 공유 — 경로를 공유로 표시하면 같은 Wi-Fi의 휴대폰이나 다른 기기에서 https://app.local에 접속할 수 있습니다.
• CLI만이 아닌 TUI. 실시간 경로 테이블, 요청 로그, 인증서 검사, 상태 진단. 인자 없이 mkdev를 실행하면 바로 TUI가 열립니다.
• 강화된 권한 경계. 모든 권한 상승 호출 전에 sudo 헬퍼 바이너리에 대한 소유자, 쓰기 가능 여부, 심볼릭 링크 검사를 수행합니다 (internal/safeexec). PATH 기반 섀도잉이나 그룹 쓰기 가능 단축 경로가 없습니다.
• SNI별 인증서 발급. 리프 인증서는 요청 시 발급되며 명시적인 knownHost 허용 목록으로 제어됩니다. 와일드카드도, 미리 생성된 것도 아닙니다.

기능

mkdev install                    # CA + trust + daemon service + menu bar autostart
mkdev add myapp localhost:3000   # routes https://myapp.local → localhost:3000
curl https://myapp.local         # 200 from your local app

install은 일회성입니다: CA를 생성하고, 시스템 저장소에 신뢰를 등록하고, 데몬 사용자 서비스(launchd / systemd)를 설치하고 활성화하며, 메뉴 바가 로그인 시 실행되도록 등록하고, GUI 세션이 있으면 즉시 바를 실행합니다. 데몬이 프록시를 소유합니다. TUI(mkdev 인자 없음)와 mkdev add | remove | list는 ~/.mkdev/daemon.sock을 통해 데몬과 통신합니다.

LAN 공유

mkdev의 핵심 기능입니다. 실제 TLS로 같은 Wi-Fi의 모든 기기에 경로를 공유합니다 — 경고도, 터널 서비스도 없습니다.

1. TUI 도메인 탭에서 경로를 선택하고 s를 눌러 SHARE 열을 LAN으로 전환합니다.
2. 경로는 mDNS를 통해 <name>.local → 이 머신의 LAN IP로 광고됩니다.
3. 휴대폰/두 번째 노트북에서 https://<name>.local로 접속하세요. 기기가 mkdev CA를 신뢰하면(일회성) 경고가 표시되지 않습니다.

주의 사항

• mDNS로 브로드캐스트되는 것은 .local 경로뿐입니다. 다른 TLD도 프록시는 되지만 이름으로 LAN에서 접근할 수는 없습니다.
• 회사/클라우드 Wi-Fi는 멀티캐스트를 차단하는 경우가 많습니다. 집이나 사무실 Wi-Fi에서는 작동합니다.
• s 토글은 즉시 적용됩니다 — mDNS 광고와 LAN 측 ACL은 다음 요청 시 업데이트됩니다. 재시작이 필요 없습니다.
• 공유되지 않은 경로는 심층 방어 차원에서 루프백이 아닌 요청에 403을 반환합니다.
• LAN에 있는 누구나 공유된 경로에 접근할 수 있습니다. 신뢰할 수 없는 Wi-Fi에서는 활성화하지 마세요.

설치

Homebrew (macOS, Linux)

brew install venkatkrishna07/tap/mkdev

나중에 업그레이드:

brew update
brew upgrade mkdev

Go

go install github.com/venkatkrishna07/mkdev/cmd/mkdev@latest

특정 버전으로 업그레이드:

go install github.com/venkatkrishna07/mkdev/cmd/[email protected]

직접 다운로드

macOS(Intel + Apple Silicon), Linux(amd64 + arm64), Windows(amd64)용 사전 빌드 바이너리가 Releases 페이지에 게시됩니다. 각 릴리스에는 checksums.txt와 cosign 키리스 서명(checksums.txt.sig + .pem)이 포함되어 있습니다. 검증 명령은 SECURITY.md#verifying-releases를 참조하세요.

macOS에서 Gatekeeper가 직접 다운로드한 바이너리를 차단하는 경우:

xattr -d com.apple.quarantine ./mkdev

소스에서 빌드

git clone https://github.com/venkatkrishna07/mkdev.git
cd mkdev
task build
cp bin/mkdev ~/bin/        # or /usr/local/bin

**Go 1.25+**가 필요합니다.

첫 실행

mkdev install   # CA, trust, daemon service, bar autostart — one command
mkdev           # launch TUI

install 후 데몬은 백그라운드에서 실행되고 메뉴 바가 나타납니다(macOS, Linux GNOME/KDE, Windows). 바에는 데몬 상태, 경로 목록, 경로별 활성화/LAN 공유 토글이 표시됩니다. Quit는 데몬을 중지하지 않고 바만 종료합니다.

메뉴 바

메뉴 바는 상시 UI입니다. 시스템 트레이에 있으며 ~/.mkdev/daemon.sock을 통해 데몬과 통신합니다. 로그인 시 실행되며(install이 자동 시작을 등록), mkdev bar로 포그라운드에서도 실행할 수 있습니다.

표시 정보:

• 상태 점 — 녹색이면 정상, 빨간색이면 중지, 노란색이면 프로빙 중, 회색이면 꺼짐. 데몬 상태를 반영합니다.
• 헤더 — mkdev v0.4.0 + 데몬 PID + 가동 시간 + 수신 중인 프록시 포트.
• 경로 — 저장소의 모든 경로를 위에서 아래로 표시. 각 항목은 name.tld → target과 접미사 배지( · disabled, · LAN)를 보여줍니다.

동작 (경로 클릭):

• 브라우저에서 열기 — 시스템 기본 처리기로 https://name.tld를 엽니다.
• URL 복사 — 프록시 URL을 클립보드에 복사합니다 (pbcopy / wl-copy / xclip / clip.exe).
• 활성화 / 비활성화 — 경로의 Enabled 플래그를 전환합니다. 비활성화된 경로는 저장소에 남지만 프록시되지 않습니다.
• LAN 공유 — mDNS 광고 + LAN 측 ACL을 전환합니다.

바 수준 동작:

• 데몬 중지 — launchd / systemd KeepAlive가 즉시 다시 시작하지 않도록 먼저 DisableUnit을 호출한 다음 소켓으로 종료를 보냅니다.
• 종료 — 바 프로세스만 종료합니다. 데몬과 프록시는 계속 실행됩니다.

참고:

• 바 인스턴스 두 개를 동시에 실행할 수 없습니다(PID 파일 잠금; 두 번째는 즉시 종료).
• 데몬이 다시 시작되면 바가 자동으로 다시 연결됩니다. 수동으로 새로고침하지 않아도 상태 점이 업데이트됩니다.
• 감독되는 데몬을 정상적으로 중지할 수 있는 것은 바(및 mkdev daemon stop)뿐입니다. 데몬 프로세스를 직접 종료하면 launchd / systemd가 다시 시작시킵니다.

업그레이드

바이너리를 교체하세요(brew upgrade / go install ...@latest / 새 다운로드). 다음에 mkdev 하위 명령을 실행하면 바이너리가 외부에 있는 부분들을 조정합니다: 데몬 plist / systemd 유닛과 바 자동 시작 항목을 새 바이너리를 가리키도록 다시 쓰고, 활성화된 경로에 대해 /etc/hosts를 다시 적용하며, CA가 삭제된 경우 다시 신뢰합니다. sudo 프롬프트는 인라인으로 실행됩니다. 데몬만 실행 중이고 CLI를 건드리지 않는 경우, 데몬은 자체 시작 시 안전한(sudo 없는) 작업을 수행하고 나머지는 다음 CLI 명령까지 대기시킵니다.

mkdev install을 다시 실행하면 동일한 작업을 명시적으로 수행하며 항상 안전합니다 — 모든 단계가 멱등적입니다.

플랫폼 지원

감지되는 Linux 배포판: Debian/Ubuntu (/usr/local/share/ca-certificates), RHEL/Fedora (/etc/pki/ca-trust/source/anchors), Arch (/etc/ca-certificates/trust-source/anchors), openSUSE (/usr/share/pki/trust/anchors).

Firefox는 자체 NSS 저장소를 사용하며 아직 지원되지 않습니다 — 시스템 Chrome/Safari/Edge/curl/wget은 모두 작동합니다.

명령어

플래그 및 환경 변수

대상 형식

<target>은 다음 중 하나를 허용합니다:

host:port                  e.g. localhost:3000
http://host[:port]/path    e.g. http://localhost:3000/api
https://host[:port]/path   e.g. https://gitlab.example.com

HTTPS 업스트림(예: 회사 VPN의 사설 GitLab)의 경우 업스트림 TLS 인증서가 시스템 신뢰 저장소에 대해 검증되어야 합니다. 사설 CA는 해당 루트를 OS 키체인에 추가해야 합니다.

hosts-helper는 직접 호출용이 아닙니다. add / remove는 권한이 필요한 /etc/hosts 쓰기를 수행하기 위해 동일한 바이너리를 sudo로 다시 호출합니다.

구성

TLD 참고. .local 경로에는 mDNS 응답기가 필요합니다(macOS에서는 항상 켜져 있고, Linux에서는 nss-mdns가 설치된 경우 사용 가능). .test / .dev / .localhost는 /etc/hosts만으로 모든 곳에서 작동합니다. 이에 맞게 config의 tld를 설정하세요.

구성은 ~/.mkdev/config.toml에 있습니다. 기본값:

tld           = ".local"   # appended to bare names in `add`
proxy_port    = 443        # binding :443 requires sudo on serve
theme         = "auto"     # reserved for future TUI
log_retention = "7d"       # reserved
log_max_size  = "100MB"    # reserved

구성 디렉터리는 --home <path> 또는 MKDEV_HOME=...으로 재정의할 수 있습니다.

동작 방식

• ~/.mkdev/ca/에 ECDSA P-256 루트 CA를 생성합니다. 개인 키 권한은 0o400입니다.
• CA를 OS 네이티브 신뢰 저장소에 설치합니다: macOS 키체인(security), Linux CA 번들 디렉터리 + update-ca-*, Windows ROOT 저장소(crypt32.dll 경유). 신뢰 저장소 통합은 mkcert(BSD-3)에서 가져왔습니다 — LICENSE-MKCERT를 참조하세요.
• add 시 데몬은 ~/.mkdev/state.db의 bbolt KV에 경로를 쓰고, sudo로 호출되는 헬퍼 하위 명령을 통해 /etc/hosts에 127.0.0.1 <name>.<tld> 줄을 추가합니다.
• 데몬은 0.0.0.0:<proxy_port>에서 TLS를 수신하고, 루트 CA를 사용하여 요청 시 하며, 구성된 업스트림으로 리버스 프록시합니다.

보안

이 도구는 시스템 신뢰 저장소에 개인 CA를 설치합니다. ~/.mkdev/ca/rootCA-key.pem에 읽기 권한이 있는 사람은 누구나 여러분의 시스템이 신뢰하는 TLS 인증서를 발급할 수 있습니다. 키는 0o400(소유자 읽기 전용)으로 생성됩니다.

• 프록시는 0.0.0.0에 바인딩하지만, 연결 소스 ACL이 명시적으로 공유로 표시되지 않은 경로에 대한 LAN 요청에 403을 반환합니다. 루프백은 항상 통과합니다.
• 텔레메트리 없음. 원격 호출 없음. 업데이트 확인 없음.
• add / remove는 /etc/hosts를 변경하기 위해 sudo를 호출합니다. 위협 모델과 os.Executable()로 확인되는 헬퍼 경로 관련 알려진 제한 사항은 SECURITY.md를 참조하세요.

제거

mkdev uninstall   # stops + disables daemon, untrusts CA, clears /etc/hosts,
                  # removes daemon service + bar autostart, wipes ~/.mkdev/

문제가 생기면 Keychain Access.app을 열어 mkdev를 검색한 후 수동으로 삭제하세요. 그런 다음 grep mkdev /etc/hosts로 남은 항목을 정리하세요.

데몬 및 API

데몬은 프록시와 경로 저장소를 소유합니다. ~/.mkdev/daemon.sock(소유자 전용 0600)에서 로컬 HTTP API를 제공합니다. TUI, CLI 하위 명령, 메뉴 바는 모두 데몬의 클라이언트입니다 — bbolt 잠금을 보유하는 것은 데몬뿐입니다.

mkdev install은 데몬을 사용자 서비스(macOS의 launchd LaunchAgent, Linux의 systemd --user)로 설치하고 활성화합니다. 데몬은 백그라운드에서 실행되며 로그아웃/로그인 후에도 유지됩니다.

mkdev daemon status                # installed / enabled / running
mkdev daemon stop                  # stop + disable (prevents respawn)
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/status
curl --unix-socket ~/.mkdev/daemon.sock http://x/v1/routes
curl --unix-socket ~/.mkdev/daemon.sock -X POST http://x/v1/routes \
     -H 'Content-Type: application/json' \
     -d '{"name":"foo","target":"localhost:3000"}'
curl --unix-socket ~/.mkdev/daemon.sock -X DELETE http://x/v1/routes/foo

로드맵

다음:

• Firefox / NSS 신뢰 저장소 통합.
• 경로별 라우팅 (단일 도메인에서 /api → 8080, /ws → 9000).

문제 해결

• Firefox에 빨간색 경고 막대가 표시됩니다. Firefox는 자체 NSS 저장소를 사용하므로 시스템 신뢰가 적용되지 않습니다. NSS 통합은 로드맵에 있습니다. 당분간 ~/.mkdev/ca/rootCA.pem을 설정 → 개인 정보 및 보안 → 인증서 → 인증서 보기 → 기관 → 가져오기에서 수동으로 가져오세요.
• 데몬이 :443에 바인딩하지 못합니다. macOS/Linux에서는 launchd / systemd 기능을 통해 루트가 아닌 사용자 서비스가 :443에 바인딩할 수 있습니다. 배포판에서 이를 제한하는 경우 ~/.mkdev/config.toml에서 proxy_port = 8443을 설정하고 https://name.local:8443을 사용하세요.
• mkdev add가 계속 sudo를 요구합니다. sudo의 세션별 캐시는 만료됩니다(기본 5분). 대신 TUI 도메인 탭을 사용하세요 — osascript(macOS GUI 프롬프트) 또는 pkexec(Linux Polkit)로 권한을 상승시킵니다.
• /etc/hosts에 해당 이름의 항목이 이미 있습니다. mkdev add는 멱등적이며 mkdev가 관리하는 항목이 없을 때만 추가합니다. 이전 항목을 수동으로 제거하거나 다른 이름을 사용하세요.

기여

CONTRIBUTING.md를 참조하세요.

감사의 말

mkdev의 신뢰 저장소 통합 — macOS의 키체인/security, Linux의 CA 번들 + update-ca-*, Windows의 crypt32.dll ROOT 저장소, 그리고 NSS 인접 경로 — 은 Filippo Valsorda의 mkcert에서 BSD-3로 각색되었습니다. 그 선행 작업이 없었다면 이 프로젝트는 훨씬 어려웠을 것입니다. 업스트림 라이선스는 LICENSE-MKCERT를 참조하세요.

TUI는 Charmbracelet의 Bubble Tea / Bubbles / Lipgloss로 구축되었습니다. mDNS는 hashicorp/mdns를 통합니다. 로컬 KV는 bbolt를 사용합니다.

라이선스

MIT LICENSE.