<p align="center">
<img src="https://img.shields.io/badge/rust-2021-orange?style=flat-square&logo=rust" alt="Rust 2021" />
<img src="https://img.shields.io/badge/version-0.3.7-blue?style=flat-square" alt="Version" />
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform" />
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
<img src="https://img.shields.io/badge/AI-Claude%20powered-blueviolet?style=flat-square" alt="AI Powered" />
</p>
<h1 align="center">run.dev</h1>
<h3 align="center">AI 네이티브 로컬 개발 환경</h3>
<p align="center">
<em>하나의 대시보드. 모든 서비스. 관리할 설정 파일 제로.</em>
</p>
문제점 (The Problem)
당신은 아키텍트일 수도 있고, 장인(artisan)일 수도 있습니다. 혹은 둘 다일 수도 있죠. 4개의 마이크로서비스(microservices), 2개의 프론트엔드(frontends), 웹소켓 서버(websocket server), 그리고 퇴사하기 전에 Steve가 작성했던 그 Go 바이너리까지 가지고 있습니다. 매일 아침 6개의 터미널 탭을 열고, 같은 명령어를 입력하며, 어떤 포트가 무엇인지 잊어버리고, 첫 커피를 마시기 전에 "주소 이미 사용 중(address already in use)" 오류로 15분을 허비합니다.
MAMP? Nginx 설정 파일(configs)? 임대 계약서보다 긴 Docker Compose YAML 파일들요?
아닙니다.
Run.dev가 하는 일 (What Run.dev Does)
Run.dev는 이 모든 것을 대체하는 단일 Rust 바이너리입니다. 이것은 다음을 제공합니다:
- 멋진 대시보드(dashboard) — 모든 프로젝트와 서비스를 한눈에 확인하고 키 스트로크(keystroke)로 시작/중지할 수 있습니다.
- 자동 로컬 도메인(Automatic local domains) —
api.myapp.local, frontend.myapp.local 등 실제 HTTPS를 갖춘 주소를 자동으로 생성합니다.
- 제로 설정(Zero-config) SSL — mkcert 신뢰 인증서와 rcgen 폴백(fallback)을 지원하여 수동으로 인증서를 관리할 필요가 없습니다.
- 리버스 프록시(Reverse proxy) — WebSocket 지원을 포함한 SNI 기반 라우팅이 가능하며, 예쁜 URL부터
localhost:whatever까지 처리합니다.
- 프로세스 관리(Process management) — 실행(spawn), 모니터링, 재시작 기능을 제공합니다. 서비스별 CPU 및 RAM 통계를 실시간으로 확인할 수 있습니다.
- 스마트 프로젝트 스캐닝(Smart project scanning) — 폴더를 지정하기만 하면
npm run dev, cargo run, go run . 등을 자동으로 감지하여 실행합니다.
- AI 충돌 진단(AI crash diagnosis) — 무언가 멈추면, Claude가 stderr(표준 에러 스트림)를 읽어 무엇이 잘못되었는지 알려줍니다.
- 개성(Personality) — run.dev는 분위기가 있습니다. 모든 것이 작동할 때: 😎 vibing. 충돌하면: 💀 flatlined.
██████╗ ██╗ ██╗███╗ ██╗ ██████╗ ███████╗██╗ ██╗
██╔══██╗██║ ██║████╗ ██║ ██╔══██╗██╔════╝██║ ██║ 3/4 services vibing
██████╔╝██║ ██║██╔██╗ ██║ ██║ ██║█████╗ ██║ ██║
...
설치 (Install)
한 줄 명령어:
curl -fsSL https://getrun.dev/install.sh | bash
설치 프로그램은 진행하기 전에 무엇을 변경할지 정확하게 보여줍니다.
설치되는 항목 (What gets installed):
rundev 바이너리 → /usr/local/bin/rundev (+ run.dev 심볼릭 링크)- 신뢰할 수 있는 로컬 HTTPS 인증서용
mkcert
- 빌드 도구(gcc, pkg-config, libssl-dev) — 소스에서 빌드하는 경우에만 필요
시스템 변경 사항 (What changes on your system):
/etc/hosts — 로컬 개발 도메인 항목을 추가합니다./etc/sudoers.d/rundev — 호스트 헬퍼 전용 비밀번호 없는 sudo 설정을 합니다.- macOS:
/etc/pf.anchors/rundev 및 /etc/pf.conf — pfctl 방화벽 규칙 (포트 80→1111, 443→1112).
- Linux: 포트 포워딩을 위한
iptables NAT 규칙 (80→1111, 443→1112, 로컬호스트 전용)을 추가합니다.
- 셸 PATH에
/usr/local/bin을 추가합니다 (이미 존재하는 경우 제외).
모든 변경 사항은 rundev uninstall 명령어로 되돌릴 수 있습니다. 설치 프로그램이 중간에 실패하면, 변경된 모든 내용을 자동으로 롤백(roll back)합니다.
대화형으로 실행할 경우(bash install.sh)에는 확인 메시지가 표시됩니다. 파이프를 통해 전달될 경우(curl | bash)에는 요약 정보를 보여준 후 진행됩니다.
또는 직접 빌드하기:
git clone https://github.com/danieltamas/run.dev.git
cd run.dev
make install
요구 사항: Rust 툴체인 (설치 프로그램이 자동으로 처리합니다). Node는 필요 없습니다. Python도, Docker도 필요 없습니다.
빠른 시작 (Quick Start)
작동 방식 (How It Works)
브라우저 Run.dev 사용자 서비스
│ │ │
│ https://api.myapp.local │ │
...
도커 네트워크가 필요 없습니다. Traefik이 필요 없습니다. nginx.conf 파일도 필요 없습니다. 단순히 프로세스를 관리하고 트래픽을 라우팅하는 바이너리 하나만 있으면 됩니다.
CLI (Command Line Interface)
rundev와 run.dev 모두 명령어 이름으로 사용됩니다.
rundev
rundev up [프로젝트]
rundev down [프로젝트]
...
플래그(Flags):
| 플래그 | 기능 |
|---|
--no-proxy | 리버스 프록시를 건너뜁니다 |
| ... | |
키보드 단축키 (Keyboard Shortcuts)
| 키 | 동작 |
|---|
j / k | 위/아래 이동 |
| ... | |
| 마우스도 작동합니다. 요소를 클릭하고, 스크롤하세요. 로그 패널 내부에서 드래그하여 로그 텍스트를 선택하면 — 이는 배포 시 클립보드에 복사됩니다. 이제는 2026년입니다. | |
프로젝트 감지 (Project Detection)
run.dev를 폴더에 지정하면 무엇을 해야 할지 자동으로 파악합니다:
| 감지하는 파일 | 제안하는 동작 |
|---|
package.json | npm run dev, npm start 등 |
| ... | |
포트는 명령어 플래그, .env 파일, package.json의 프록시 필드 또는 프레임워크 기본값을 통해 자동 감지됩니다. | |
무드 시스템 (The Mood System)
Run.dev는 모든 서비스를 모니터링하고 현재 상황을 표현합니다:
| Mood | Emoji | 의미 |
|---|
| Vibing | 😎 | 모든 것이 실행되고 문제 없음 |
| ... | | |
무언가 충돌(crash)할 때, run.dev는 단순히 종료 코드만 보여주지 않습니다. stderr를 읽고, 오류를 분류하며, 제안된 수정 사항과 함께 개성이 담긴 메시지를 제공합니다:
✗ api 친구야, api가 죽었어. 포트 4000은 이미 사용 중이야.
내가 뭘 잘못했는지 알아. [f]를 눌러서 내가 고치게 해줘
[f]를 누르면 해당 포트를 점유하고 있는 프로세스를 종료합니다. /를 누르고 Claude에게 무엇이 문제인지 물어보세요.
AI 통합 (선택 사항)
Run.dev는 Anthropic의 로컬 CLI 에이전트인 Claude Code와 함께 작동하도록 구축되었습니다. 서비스가 충돌할 때, run.dev는 단순히 종료 코드만 보여주는 것이 아니라 stderr를 Claude에게 보내 실제 진단을 받습니다. Claude는 로그를 읽고 컨텍스트를 이해하여 실제로 무엇이 잘못되었는지 알려줍니다.
얻을 수 있는 것:
- 충돌 진단(Crash diagnosis) — 서비스가 죽으면, Claude가 stderr를 읽어 무슨 일이 일어났고 어떻게 고쳐야 하는지 설명합니다.
- 실시간 디버깅 세션(Live debug sessions) — 대시보드에서
/를 누르고 실행 중인 서비스에 대해 Claude에게 무엇이든 물어보세요. 프로젝트 구조, 라우트, 포트를 알고 있으므로 컨텍스트에 맞춰 답변해 줍니다.
- 자동 수정 제안(Auto-fix suggestions) — 일반적인 오류(포트 충돌, 누락된 모듈, 연결 실패)의 경우, run.dev가 수정 사항을 제안합니다.
[f]를 누르면 이를 처리합니다.
Run.dev는 Claude Code와 통신하며 — 사용자의 코드와 로그는 절대 기기를 벗어나지 않습니다.
~/.config/rundev/config.yaml에서 설정할 수 있습니다:
claude_proxy: http://localhost:3456/v1
AI 기능은 완전히 선택 사항입니다. 이 기능 없이도 앱은 완벽하게 작동합니다. --no-ai를 사용하거나 프록시를 구성하지 않으면 언제든지 비활성화할 수 있습니다.
아키텍처(Architecture)
전체 기술 심층 분석 — 모듈 구조, 데이터 흐름 다이어그램, 핵심 타입 및 설계 결정 사항은 src/docs/ARCHITECTURE.md를 참조하세요.
서비스별 Node 버전
서비스가 다른 Node.js 버전을 필요로 하는 경우, 서비스 설정에 node_version을 추가하세요. run.dev는 시작 명령(start command)을 자동으로 nvm use <버전>으로 감싸주므로 수동 전환이 필요 없습니다.
services:
backend:
path: /Users/dan/code/myapp/backend
...
$NVM_DIR에 nvm이 설치되어 있어야 합니다 (기본값은 ~/.nvm). node_version을 생략하면, 해당 명령어는 환경 변수 PATH에 설정된 어떤 Node로도 실행됩니다.
설정 파일 (Config Files)
모든 것은 ~/.config/rundev/ (또는 macOS의 경우 ~/Library/Application Support/rundev/)에 저장됩니다:
~/.config/rundev/
├── projects/ # 프로젝트당 하나의 YAML 파일
│ ├── myapp.yaml
...
자주 묻는 질문 (FAQ)
run.dev를 닫으면 서비스가 중지되나요?
아닙니다. q를 누르면 백그라운드에서 계속 실행됩니다. 다음에 run.dev를 열면 다시 연결됩니다. 모든 것을 종료하려면 Q (대문자)를 누르세요.
Docker 서비스와도 작동하나요?
run.dev는 프로세스를 직접 관리하며 컨테이너를 오케스트레이션(orchestrate)하지 않습니다. 서비스가 셸 명령어(shell command)로 실행되는 경우, run.dev가 이를 관리할 수 있습니다. 만약 Docker에서만 실행된다면, 서비스 명령으로 docker compose up을 실행해야 합니다.
셀프 서명 인증서(self-signed certs)를 신뢰해야 하나요?
run.dev는 mkcert를 사용하여 로컬에서 신뢰하는 인증서를 생성합니다. 별도의 수동 신뢰 설정 없이 바로 녹색 자물쇠가 표시됩니다. mkcert를 사용할 수 없는 경우, rcgen 셀프 서명 인증서로 대체(fallback)됩니다 (브라우저에서는 한 번 클릭하여 건너뛸 수 있는 경고가 표시됩니다).
Chrome의 DNS-over-HTTPS와 작동하나요?
"보안 DNS 사용(Use secure DNS)"이 활성화된 Chrome은 /etc/hosts를 완전히 우회합니다. 로컬 도메인이 해결되지 않는 경우, chrome://settings/security로 이동하여 "보안 DNS 사용"을 비활성화하세요. Safari, Firefox, curl 및 모든 다른 도구는 별도의 설정 없이 작동하며 — run.dev는 Happy Eyeballs가 프로덕션 주소로 폴백(fallback)하는 것을 방지하기 위해 IPv4와 IPv6 항목을 모두 작성합니다.
도메인 연결이 시간이 지나자 작동을 멈추지만, 대시보드에는 프록시가 실행 중이라고 표시되는 경우
이전에 발생하던 문제는 OS가 run.dev의 포트 포워딩(port-forwarding) 규칙을 삭제할 때였습니다. macOS는 절전 모드/깨우기 과정에서 이를 플러시(flush)하고, Linux에서는 Docker나 방화벽 재로드가 이 규칙들을 지울 수 있습니다. 리스너(listeners) 자체는 살아있었기 때문에 (대시보드는 정상으로 보였지만), 브라우저 트래픽이 더 이상 도달하지 못했습니다. run.dev는 이제 몇 초마다 리디렉트(redirect)를 재확인하고 자동으로 다시 적용하므로, 재시작 없이 복구됩니다. 복구되는 동안 잠시 "포트 포워딩 비활성 — 재적용 중 (port forwarding inactive — re-applying)" 알림이 표시될 것입니다. rundev doctor를 실행하여 리디렉트가 라우팅(routing)되고 있는지 확인하십시오.
Windows는요?
아직 안 됩니다. macOS와 Linux에서만 지원됩니다. WSL은 작동할 수도 있지만 테스트되지 않았습니다.
<!-- registry:apps:begin (generated by registry/scripts/render-readme.py, do not edit) -->
더 많은 앱
또한 동일 제작자가 만든 앱들로, 모두 MIT 라이선스이며 무료입니다:
<table>
<tr
><td align="center" width="33%"><a href="https://github.com/danieltamas/macmax"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/macmax.png" width="64" alt="MacMax"></a><br><b><a href="https://github.com/danieltamas/macmax">MacMax</a></b><br><sub
>왜 제 Mac이 느릴까요?</caption>
</table>
One answer, from the menu bar.</sub></td>
<td align="center" width="33%"><a href="https://github.com/danieltamas/bton"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/bton.png" width="64" alt="Bton"></a><br><b><a href="https://github.com/danieltamas/bton">Bton</a></b><br><sub>스스로 이동하는 풀 리퀘스트(Pull requests that move themselves).</sub></td>
<td align="center" width="33%"><a href="https://github.com/danieltamas/runmyjob"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/rmj.png" width="64" alt="RMJ"></a><br><b><a href="https://github.com/danieltamas/runmyjob">RMJ</a></b><br><sub>나의 작업 실행(Run My Job): 사용자의 빌드 및 테스트를 로컬 환경에서 수행합니다.</sub></td>
</tr>
<tr>
<td align="center" width="33%"><a href="https://github.com/danieltamas/agencil"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/agencil.png" width="64" alt="Agencil"></a><br><b><a href="https://github.com/danieltamas/agencil">Agencil</a></b><br><sub>자체 구독을 사용하는 코딩 에이전트들의 협의체(A council of coding agents, on your own subscriptions).</sub></td>
<td align="center" width="33%"><a href="https://github.com/danieltamas/axon"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/axon.png" width="64" alt="Axon"></a><br><b><a href="https://github.com/danieltamas/axon">Axon</a></b><br><sub>하나의 버스에서 작동하는 사용자의 코딩 에이전트들(Your coding agents, on one bus).</sub></td>
<td align="center" width="33%"><a href="https://github.com/danieltamas/cloak"><img src="https://raw.githubusercontent.com/danieltamas/registry/main/thumbs/cloak.png" width="64" alt="Cloak"></a><br><b><a href="https://github.com/danieltamas/cloak">Cloak</a></b><br><sub>환경 변수(env) 시크릿을 AI 에이전트로부터 보호합니다(Keep .env secrets away from AI agents).</sub></td>
</tr>
</table>
registry와 동기화되었습니다. 메뉴 바 앱 목록은 설정(Settings)의 '더 많은 앱(More apps)' 섹션에 동일한 앱들을 나열합니다.
<!-- registry:apps:end -->
라이선스 (License)
MIT 라이선스 — 자세한 내용은 [LICENSE]를 참조하십시오.
Copyright (c) 2026 Daniel Tamas [email protected]
<p align="center">
<strong>제작자: <a href="mailto:
[email protected]">Daniel Tamas</a></strong>
<br />
<em>인생은 너무 짧아서 nginx.conf를 다루기엔 아깝다</em>
</p>
<p align="center">
<a href="https://getrun.dev">getrun.dev</a>
</p>
