lemoncloud-io/doki / projects/local-nginx-proxy/config/skills/local-nginx-proxy
local-nginx-proxy
Unverified"로컬 이름 셋업"·"이름으로 접속하게 해줘"·"3d.local 처럼"·"<이름>.local 추가해줘"·"로컬 nginx 이름"· "로컬 이름 점검"·"nginx 프록시"·"local-nginx-proxy"·"옛 local-name-proxy 옮기기" 같은 요청에 이 기기의 로컬 서비스를 `http://<이름>.local`로 열리게 한다. nginx 전용 인스턴스(루트 LaunchDaemon, 127.0.0.1·::1 의 80)가 `127.0.0.1:<포트>`로 넘기고, `/etc/hosts` 관리 블록이 이름을 루프백에 묶는다. 설정 파일은 생성기(projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs)가 만들고, sudo 가 필요한 적용(apply.sh)은 오너가 읽고 직접 돌린다. 다른 기기에서 여는 이름(테일넷)은 이 스킬 밖이다.
local-nginx-proxy — 로컬 서비스를 이름으로
http://<이름>.<접미사>(기본 local) → nginx(루프백 80) → 127.0.0.1:<포트>. 이 기기 안에서만 열린다.
언제 쓰나
- 로컬 서비스를 포트 없이
http://<이름>.local로 열고 싶을 때(처음 셋업 · 이름 추가 · 점검). - 옛 이름(
local-name-proxy)으로 설치한 기기를 새 이름으로 옮길 때 — § 옛 이름에서 옮기기. - 다른 스킬이 화면 주소를 그 사람의 이름으로 찾을 때 — § 화면 붙이기.
| 무엇 | 어디 | Git |
|---|---|---|
| 이름 → 포트 목록 | ~/.config/local-nginx-proxy/services.json | 밖(기기 전용) |
| 생성물(nginx.conf · hosts 블록 · LaunchDaemon plist · apply.sh) | ~/.local/state/local-nginx-proxy/ | 밖 |
| 생성기 · 시험 · 예시 | projects/local-nginx-proxy/config/local-nginx-proxy/ | 안 |
경계 — 하지 않는 것
생성기는 파일만 만든다. 서비스 설치·/etc/hosts 수정·재시작은 apply.sh가 한다. apply.sh는 sudo 로만 돌고 오너가 돌린다.
에이전트는 sudo 를 돌리지 않는다. 비밀번호를 받지 않는다. 기기 이름·계정·절대 경로를 볼트 문서·PR·커밋에 적지 않는다.
처음 셋업
- 확인.
command -v nginx가 없으면brew install nginx를 오너 승인 뒤 돌린다. brew 서비스(brew services start nginx)는 켜지 않는다. 이 스킬의 데몬만 쓴다.lsof -nP -iTCP:80 -sTCP:LISTEN으로 80 을 쓰는 다른 프로세스가 없는지 본다. 있으면 멈추고 오너에게 묻는다. - 목록.
~/.config/local-nginx-proxy/services.json이 없으면services.example.json을 복사해 고친다. 이름은 소문자 DNS 라벨 하나(3d,docs)다. 포트는 1024~65535 의 루프백 서비스다. 이름은 각자 고른다. 선택 칸:app(그 화면을 여는 스킬의viewer.id— 에이전트 작업 뷰어agent-task-viewer, 볼트 뷰어knowledge-viewer),title(안내 페이지에 보일 이름),open(안내 페이지 링크의 경로, 기본/),health(2xx 면 "응답함"으로 보는 경로, 기본/). - 생성.
node projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs. 결과의nginx_test가syntax ok · port 80 needs root …면 정상이다(오너 권한으로는 80 을 못 묶는다). 다른 오류면 멈춘다. - 앱 쪽 허용. Host·Origin 을 검사하는 앱은 새 이름을 알아야 한다.
- 에이전트 작업 뷰어(serve.mjs, 그 앱이 있는 볼트에서만): LaunchAgent 환경
CLAUDE_DASHBOARD_PUBLIC_ORIGINS=http://<이름>.local(쉼표로 여럿). plist 사전 키는plutil -replace EnvironmentVariables.<키> -string <값>으로 쓴다. 그 뒤launchctl bootout+bootstrap. - 볼트 뷰어(knowledge-viewer): 실행 환경
KNOWLEDGE_VIEWER_PUBLIC_HOSTS=<이름>.local. 그 앱의projects/knowledge-viewer/config/README.md§ 이름으로 열기가 정본이다(그 설정을 아는 판부터. 모르는 판은 그 이름을 127.0.0.1 로 넘겨 버린다 —health가 2xx 가 아니라 "응답 없음"으로 보인다). - Vite 앱은
server.allowedHosts에 이름을 넣는다(*.localhost와 달리.local은 기본 허용이 아니다). - 확인:
curl -s -o /dev/null -w '%{http_code}' -H 'Host: <이름>.local' http://127.0.0.1:<포트>/가 200, 다른 이름은 403/거부.
- 에이전트 작업 뷰어(serve.mjs, 그 앱이 있는 볼트에서만): LaunchAgent 환경
- 적용(오너).
~/.local/state/local-nginx-proxy/apply.sh를 보여 주고 오너에게 돌려 달라고 한다:sudo sh ~/.local/state/local-nginx-proxy/apply.sh. 하는 일:nginx -t(루트) → 옛 이름 데몬이 있으면 내림 → LaunchDaemonlocal.nginx-proxy.nginx설치 →/etc/hosts관리 블록 교체(옆에 백업) → DNS 캐시 비움 → nginx (재)기동. - 점검.
node …/render.mjs check— 데몬 상태, hosts 블록, 이름마다 해석·HTTP 코드·걸린 시간. 이어서 브라우저 패널로http://<이름>.local/을 연다. 에이전트 작업 뷰어면(그 앱이 있는 볼트에서만)/viewer·/dashboard·/__monitor/events(스트림)도 본다.
옛 이름에서 옮기기
이 도구의 옛 이름은 local-name-proxy다. 옛 이름으로 설치한 기기는 한 번 옮긴다. 옛 설치가 없는 기기는 이 절을 건너뛴다.
- 목록 파일. 오너 권한으로 옮긴다. 새 목록이 없고 옛 목록만 있으면 생성기가 멈추고 이 명령을 한 줄로 알린다.
mkdir -p ~/.config/local-nginx-proxy && cp ~/.config/local-name-proxy/services.json ~/.config/local-nginx-proxy/services.json - 생성.
node …/render.mjs. 새 상태 폴더~/.local/state/local-nginx-proxy/에 생성물이 생긴다. - 적용(오너).
sudo sh ~/.local/state/local-nginx-proxy/apply.sh. 옛 데몬(local.name-proxy.nginx)을 내리고 그 plist 를 지운다./etc/hosts의 옛 표시 블록을 지우고 새 블록을 넣는다(백업은 옆에). 그 뒤 새 데몬을 올린다. 옛 데몬을 먼저 내리므로 80 이 겹치지 않는다. - 점검.
node …/render.mjs check.daemon: running이어야 한다.legacy줄이 무엇이 남았는지 알린다. 데몬·plist·hosts 블록이 남았다고 하면 3번을 다시 돌린다. "지워도 된다"만 말하면 적용은 끝났다. - 정리. 옛 상태 폴더
~/.local/state/local-name-proxy/와 옛 목록 폴더~/.config/local-name-proxy/는 스크립트가 지우지 않는다. 새 데몬이 뜬 뒤 지운다. 그 뒤check에legacy줄이 없다.
이름 추가 · 빼기
services.json을 고친다 → 생성 → 앱 쪽 허용 → 오너가 sudo sh …/apply.sh → 점검. 바뀐 것이 없으면 생성이 nothing changed를 낸다.
화면 붙이기 — 각자 설정을 따른다
화면을 여는 스킬은 이름을 직접 적지 않는다. 그 사람의 services.json에서 찾는다. 셋업이 없는 사람에게는 지금까지처럼 연다.
node projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs url --app <viewer.id> --path '<경로?질의#앵커>' --fallback <스킬의 기본 주소>
# → {"url":"…","via":"name"|"fallback","reason":"…"} — 그 앱의 이름이 여럿이면 "candidates":["…"] 가 더 붙는다
via: name— 그 사람의 이름이health에서 2xx 로 답했다.url을 브라우저 패널에서navigate한다. 서버를 따로 띄우지 않는다. 같은app의 이름이 여럿이면candidates가 응답한 이름의 주소를 목록 순서로 준다(url은 그 첫째). 어느 것을 열지는 그 화면의 스킬이 정한다.via: fallback— 셋업이 없거나, 그 앱의 이름이 없거나, 이름이 답하지 않는다.url은 기본 주소다. 스킬의 원래 절차(launch.json ·preview_start)를 따른다.- 생성기 파일이 볼트에 없으면 이 단계를 건너뛴다.
| 화면 | --app | --path 예 | --fallback | 더 볼 것 |
|---|---|---|---|---|
| 에이전트 작업 뷰어(그 앱이 있는 볼트에서만) | agent-task-viewer | /viewer#mode=sessions · /dashboard · /debug | http://127.0.0.1:4318 | 상시 서버는 하나다. 세션마다 다른 데이터가 아니다 |
| 볼트 뷰어 | knowledge-viewer | /v/wiki/INDEX.md?agent=claude&src=local | http://127.0.0.1:<그 볼트의 포트>(기본 8778) | 상시 서버는 볼트마다 하나이고 볼트 루트 하나(그 볼트의 주 체크아웃)를 낸다. 스킬은 candidates를 차례로 견줘 세션의 볼트 루트를 내는 이름만 쓴다. 없으면(워크트리 등) 이름을 쓰지 않는다 — knowledge-viewer-open 스킬 |
상시 서비스 — 이름이 답하려면
이름은 서비스가 늘 떠 있을 때만 쓸모 있다. 상시 실행은 각 앱의 몫이다. 규칙:
- 서비스는 이 볼트의 주 체크아웃에서 띄운다. 따로 서빙 폴더를 만들지 않는다. 올리기 전에 주 체크아웃을 기본 브랜치의 최신으로 맞춘다.
- 에이전트 작업 뷰어:
projects/agent-task-monitor/README.md§ 상시 실행(LaunchAgent, 4318) — 해당 문서가 있는 볼트에서만. - 볼트 뷰어: 볼트마다 LaunchAgent 하나(그 볼트의 포트, 기본 8778). 볼트가 여럿이면 포트·이름·라벨·로그가 볼트마다 다르다. 설치 → plist → 이름 → 점검 → 갱신 → AI 키 → 문제 해결의 처음부터 끝까지는 references/vault-viewer.md가 정본이다.
- 상시 서버가 포트를 잡고 있으면 세션 워크트리의 개발 서버는 다른 포트로 띄운다.
안내 페이지
http://localhost/ — 이름마다 링크(open)와 응답 여부(/_up/<이름> → health, 15초마다)를 보인다. 목록은 services.json에서 생성된다(포트는 싣지 않는다).
다른 Host 는 여전히 404 다.
재부팅 뒤 확인
- nginx 데몬은 부팅 때 뜬다(LaunchDaemon). 화면 서버들은 로그인 때 뜬다(LaunchAgent). 로그인 전에는 이름이 502 를 낸다.
- 로그인 뒤
node …/render.mjs check—daemon: running,landing: 200, 이름마다http. 안내 페이지에서 모두 "응답함"인지 본다.
되돌리기
오너가 돌린다:
sudo launchctl bootout system/local.nginx-proxy.nginx
sudo rm /Library/LaunchDaemons/local.nginx-proxy.nginx.plist
# /etc/hosts 에서 '# >>> local-nginx-proxy >>>' ~ '# <<< local-nginx-proxy <<<' 블록을 지운다(백업: /etc/hosts.bak-local-nginx-proxy-*)
알아 둘 것
- 왜 루트 데몬인가. macOS 에서 루트가 아닌 프로세스는 80 을 모든 주소(
0.0.0.0)에만 묶을 수 있다. 그러면 같은 망에 열린다. 데몬은 루트로127.0.0.1:80·[::1]:80만 묶고, 작업자 프로세스는 오너 계정으로 돈다. - 왜 /etc/hosts 인가.
.local은 mDNS 접미사라 OS 가*.localhost처럼 루프백으로 풀지 않는다. 관리 블록은127.0.0.1과::1을 함께 적는다.::1이 없으면 IPv6 조회가 시간 초과를 기다릴 수 있다. - 같은 이름의 기기. 같은 망에
<이름>.local을 광고하는 기기가 있어도 이 기기에서는 hosts 블록이 먼저다. - 설정 바꿈은 sudo 가 든다. nginx 주 프로세스가 루트라 다시 읽기(
kickstart)도 루트다. 그래서 이름을 바꿀 때마다apply.sh를 다시 돌린다. - 스트림. 사이트마다
proxy_buffering off,proxy_read_timeout 1h,Host그대로. SSE·긴 응답이 끊기지 않는다. - 느린 스트림은 앱 쪽인지 먼저 본다. 프록시 뒤 스트림이 안 열리면 같은 요청을
127.0.0.1:<포트>로 직접 보내 첫 바이트 시간을 잰다(curl -N -w %{time_starttransfer}). 앱에 따라 직접 연결에서도 첫 바이트가 수 초 걸린다(예: 에이전트 작업 뷰어 대시보드의 이벤트 스트림). nginx 로그499는 클라이언트가 먼저 끊었다는 뜻이다. - 로그:
~/.local/state/local-nginx-proxy/nginx/logs/(error.log·access.log·launchd.log).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |