> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 클라우드 배포 (RunPod)
> 에이전트 패널을 떠나지 않고 ComfyUI용 클라우드 GPU 파드를 배포, 연결, 감시, 정지하세요 — 원탭 배포, 정직한 로컬⇄파드 호스트 전환, 실시간 비용/GPU 상태, 유휴 자동 정지. 또는 명령 하나로 기존 파드를 제어하세요.
로컬 GPU가 없거나 — 더 큰 것을 필요할 때 원하나요? ComfyUI를
**클라우드 GPU 파드**에 배포하고, **자신의** 머신에서 실행되는 에이전트로
자신의 Claude 또는 ChatGPT 구독으로 자연어로 제어하세요.
파드는 **ComfyUI + Manager + 에이전트 패널 UI**만 제공합니다. 에이전트의 뇌
([패널 오케스트레이터](/docs/docs/ko/panel))는 **자신의 머신에서 로컬로** 자신의
구독으로 실행됩니다 — 그래서 클라우드 파드가 LLM에 GPU 시간을 태우지 않고,
API 키나 에이전트 로그인이 상자에 닿지 않습니다. [토폴로지](#토폴로지-에이전트가-실행되는-곳)를
참고하세요.
## 원클릭 템플릿 (가장 빠른 경로)
미리 빌드된 이미지는 **에이전트 패널이 바로 구동할 수 있게** 부팅됩니다 — ComfyUI +
[에이전트 패널](https://github.com/artokun/comfyui-mcp-panel) +
ComfyUI-Manager v2가 구워져 있고, 설정이 없습니다:
[](https://console.runpod.io/deploy?template=bnqtkvcer3\&ref=dkx71w9b)
1. **Deploy on RunPod**를 클릭하고 GPU를 고르세요 (RTX 5090 / 어떤 Blackwell 또는 Ada
카드든 동작합니다 — 이미지가 cu128 torch를 싣습니다).
2. 템플릿 기본값을 유지하세요: HTTP 포트 **3000**이 노출되고 네트워크 볼륨이
\*\*`/workspace`\*\*에 마운트됩니다.
3. 파드가 올라올 때까지 기다리세요. 자동 새로고침되는 "ComfyUI is starting…" 페이지가
준비될 때까지 제공됩니다 (\~30–60초 ComfyUI 초기화).
그런 다음 [자신의 컴퓨터에서 연결하기](#자신의-컴퓨터에서-연결하기)로 건너뛰세요.
## 에이전트 패널에서 배포하고 제어하기 (v0.44+)
**comfyui-mcp 0.44**부터, RunPod 콘솔을 건드리거나 CLI
명령을 실행할 필요가 전혀 없습니다 — [에이전트 패널](/docs/docs/ko/panel)에 파드를
배포, 연결, 감시, 정지하는 **RunPod 제어판**이 있고, 같은 제어 시트가
[모바일 앱](/docs/docs/ko/mobile)에도 실립니다.
1. **키를 한 번 설정하세요.** 패널의 **API 키** 카드에
`RUNPOD_API_KEY`를 붙여넣으세요. `~/.comfyui-mcp/.env`에 서버 측으로 저장됩니다 — 브라우저에는
절대 없습니다.
2. 패널 툴바의 호스트 표시에서 **RunPod 제어판을 여세요** (처음에는
**🟢 로컬 · 사용자의 장비**로 읽힙니다).
3. **배포하거나 연결하세요.** 원탭 파드를 위해 **배포**를 누르세요 (템플릿의
배포 링크를 거치며 GPU 타입 / COMMUNITY→SECURE를 용량이 빠듯할 때
폴백합니다). 또는 드롭다운에서 기존 파드를 **이름으로** 고르고
**연결**하세요.
4. **실시간으로 보세요.** 상태 카드가 GPU / VRAM / 가동 시간 / **$·hr**과 **유휴 자동 정지** 카운트다운을 보여 주고, 호스트 표시가 **🔵 RunPod · `` ·
GPU · $/hr**로 뒤집힙니다 — 그래서 렌더가 어디서 실행되는지 모호하지 않습니다. 에이전트가
커스텀 노드 + LoRA를 설치하고 모델을 파드에 다운로드하므로,
로컬 장비와 **정확한 캔버스 패리티**를 얻습니다.
5. **다시 전환하고 정지하세요.** **로컬 사용**이 렌더를 즉시 자신의 장비로
다시 겨냥합니다. **정지**가 파드를 끕니다. 유휴 자동 정지
(`RUNPOD_IDLE_STOP_MINUTES`, 기본값 15. 파드에서 실제로
렌더하는 동안에만 셉니다)가 잊었을 때의 비용 안전장치입니다.
**데드맨 스위치 (v0.47+).** 유휴 자동 정지는 comfyui-mcp 프로세스 안에
있습니다 — 그 프로세스가 죽으면 (충돌, 닫힌 노트북), 안전장치가 함께 죽어
파드가 영원히 청구되곤 했습니다. **커넥터를 통해 만든** 파드는 이제
파드 측 워치독을 싣습니다: comfyui-mcp가 파드를 돌보는 동안 몇 초마다
하트비트합니다. 비트가 멈추면 파드가 **스스로 정지합니다** (종료하지 않음 —
`/workspace`는 살아남음) 유예 기간 후 (부팅 후 하트비트 없이 45분,
그다음 비트 사이 20분. `RUNPOD_DEADMAN_BOOT_GRACE_S` /
`RUNPOD_DEADMAN_BEAT_GRACE_S`). "돌봄"은 **로컬 사용**과
**감시 해제**를 견딥니다 — 그것들은 UI가 보여 주는 것만 바꿉니다. 워치독은
comfyui-mcp 자체가 사라졌을 때만 발동합니다 (또는 파드가 종료). 워치독은
**RunPod가 모든 파드에 자동 주입하는 파드 범위 API 키**로 파드를
정지합니다 — 계정 전체 키는 머신을 떠나지 않으며, 자격 증명
면에서 옵트아웃할 것이 없습니다. `runpod` / `action: "create"`에
`deadman:false`로 무장 해제하거나 (또는 `RUNPOD_DEADMAN=0`), 파드
환경으로 `DEADMAN_DISABLE=1`. 콘솔에서 배포한 파드는 하트비트 토큰을
싣지 않으며, 커스텀 템플릿 배포(`RUNPOD_TEMPLATE_ID`)는 기본이
**꺼짐**입니다 — 그 이미지가 우리 워치독을 싣는 경우에만
`deadman:true`를 넘기세요.
ComfyUI용 GPU 임대가 처음이신가요? 블로그가 전체 흐름을 처음부터 끝까지 걷습니다:
[임대한 클라우드 GPU에서 ComfyUI 실행하기](/docs/docs/blog/runpod-comfyui).
이 페이지의 나머지는 **수동 / CLI 경로**입니다 — 여전히 완전히 지원되며,
제어판이 아래에서 구동하는 것입니다.
## 자신의 컴퓨터에서 연결하기
파드가 올라오면, 공개 프록시 URL을 집어 (RunPod → 파드 → **:3000**
HTTP 엔드포인트, 예: `https://-3000.proxy.runpod.net`) 노트북에서
**명령 하나**를 실행하세요:
```bash theme={null}
npx -y comfyui-mcp@latest connect https://-3000.proxy.runpod.net
```
**원격 HTTPS 파드**에서, `connect`는 자동으로 **보안 암호화된
`wss://` 터널**(Cloudflare를 통해)을 머신의 에이전트 브리지로 열고
파드의 패널에 그 URL을 건넵니다 — 그래서 파드의 HTTPS 페이지가
**브라우저 프롬프트 없이, 복사할 것 없이, 어떤 브라우저에서든** 에이전트에 닿습니다. **로컬**
ComfyUI에서는 평범한 `ws://127.0.0.1:9180` 루프백 브리지를 씁니다. 어느 쪽이든 에이전트 — 그리고
Claude/ChatGPT 로그인 — 는 **자신의** 머신에서만 실행됩니다. 파드에는 아무것도
설치되지 않습니다.
마치려면, 자신의 머신에서 `connect`가 계속 실행 중인 채로, 브라우저에서 파드의
ComfyUI를 열고 **에이전트 패널** 사이드바를 연 뒤 **연결**을 클릭하세요.
이제 자연어로 그래프를 제어하세요.
**왜 터널인가요?** 파드 페이지는 `https://`로 제공되고, 브라우저는 보안
페이지가 머신으로 비보안 `ws://` 소켓을 여는 것을 차단합니다 (혼합 콘텐츠 /
Private Network Access). 터널이 브리지에 유효 TLS `wss://` URL을 줍니다 —
세션별 임의 토큰으로 게이트됩니다 — 그래서 프롬프트 없이 어디서든 그냥 동작합니다.
파드가 인증 뒤에 있으면, 로컬 `connect` 명령에 `COMFYUI_AUTH_TOKEN`을
설정하세요 (선택적으로 `COMFYUI_AUTH_HEADER` / `COMFYUI_AUTH_SCHEME`).
**Cloudflare Access**가 앞선 파드에는 Access **서비스 토큰**을 만들고
`CF_ACCESS_CLIENT_ID` + `CF_ACCESS_CLIENT_SECRET`을 설정하세요 — 둘 다 모든
ComfyUI 요청(HTTP + 대기열 감시자 WebSocket)을 타므로, 커넥터가 게이트를
통과하는 동안 사람 로그인 페이지는 브라우저용으로 그대로 있습니다.
### 모든 것을 자신의 컴퓨터에 두기 (Cloudflare 없이)
브리지를 Cloudflare를 통해 라우팅하고 싶지 않나요? 자체 **SSH 포트 포워드**로
파드에 닿아 페이지가 루프백 오리진이 되게 하세요 (평범한 `ws://`가 동작하고, 터널
없음):
```bash theme={null}
ssh -L 3000:localhost:3000 # grab the SSH command from RunPod → Connect
npx -y comfyui-mcp@latest connect http://localhost:3000
```
그런 다음 \*\*[http://localhost:3000\*\*을](http://localhost:3000**을) 여세요. 또는 파드의 직접 https URL로
연결하되 \*\*`--insecure-bridge`\*\*로 평범한 루프백 브리지를 강제하세요 (그다음
파드 페이지가 `ws://127.0.0.1:9180`에 닿는 경로를 직접 마련합니다).
위의 어느 쪽 대신, 기본 Cloudflare 퀵 터널에 대한 **안정적인, 셀프호스팅
대안** — 자체 도메인, 일시적 호스트명 없음, 그 홉의 완전한 소유 — 을
원하나요? [셀프호스팅 릴레이](/docs/docs/ko/self-hosted-relay)를 참고하세요.
## 토폴로지: 에이전트가 실행되는 곳
```
YOUR LAPTOP CLOUD GPU POD (RunPod)
┌───────────────────────────┐ ┌───────────────────────────────────┐
│ npx comfyui-mcp connect … │ HTTP/WS ───▶ │ nginx :3000 ─▶ ComfyUI :3001 │
│ └─ panel orchestrator │ │ ├─ Manager v2 (--enable-manager) │
│ (Claude/ChatGPT Agent │ ◀─── events │ └─ Agent Panel (sidebar) │
│ SDK on YOUR sub) │ │ │
└───────────────────────────┘ └───────────────────────────────────┘
```
파드는 의도적으로 **Node.js 에이전트, Agent SDK, LLM 클라이언트를 싣지 않습니다** —
GPU 시간을 아무것도 아닌 데 태울 것입니다. 추론 루프는 머신에 살고,
파드는 순수한 ComfyUI 백엔드입니다. 이것이 로컬 에이전트 패널이 쓰는 같은
[원격 구동 모델](/docs/docs/ko/panel)이며, ComfyUI가 localhost 대신 클라우드 GPU에
있을 뿐입니다.
## 남는 것과 남지 않는 것
이미지는 **빠른 정지/시작**에 최적화되어 있습니다. 무거운 소프트웨어 — ComfyUI, 그
venv, Manager v2 — 는 불변 이미지에 구워져 `/opt/ComfyUI`에서 실행되고,
`custom_nodes`는 `/workspace` 볼륨에 있습니다 (심볼릭 링크). 설치가
남습니다. 따뜻한 재시작은 전체 설치/동기화/시드를 하지 않고 ComfyUI만
다시 띄웁니다.
| 무엇 | 사는 곳 | 재시작을 견디나? |
| ------------------------------- | ------------------------------------- | -------------- |
| 모델 (Manager 다운로드 포함) | 볼륨 `/workspace/models` | **예** |
| 워크플로우 + ComfyUI 설정 + Manager 설정 | 볼륨 `/workspace/user` | **예** |
| 입력 / 출력 | 볼륨 `/workspace/input`, `/output` | **예** |
| **커스텀 노드** (에이전트/Manager 설치) | 볼륨 `/workspace/custom_nodes` (심볼릭 링크) | **예** |
| ComfyUI 설치 + venv + Manager | 이미지 `/opt/ComfyUI` | 이미지와 함께 다시 받아짐 |
**런타임에 설치한 커스텀 노드는 재시작을 견딥니다.** `custom_nodes`는
`/workspace/custom_nodes`로 심볼릭 링크됩니다. 부팅할 때마다 이미지에 구운 노드 (에이전트
패널 + 내장)가 그 안으로 시드/새로고침됩니다 (이미지 업그레이드가 현재
패널을 싣는 동안 자신의 노드는 유지됩니다). 각 노드의 Python 의존성은
볼륨의 **지속 pip 캐시**에서 venv로 다시 설치됩니다 — 첫 번 이후
빠릅니다. 모델도 남습니다. 부팅 작업이 전혀 필요 없게 노드를 굽으려면,
`Dockerfile`에 추가하고 이미지를 다시 빌드하세요 (아래).
## 직접 이미지를 빌드하고 배포하기
원클릭 템플릿이 미리 빌드된 이미지입니다. **마른, 미리 빌드된 이미지** — 같은
ComfyUI + 에이전트 패널 + Manager이지만, 선택적 도너 엑스트라
(`runpod-uploader`/`croc`/`app-manager`)나 구운 SDXL 스팟체크 체크포인트 없이,
CI에서 계속 빌드됩니다 — 도 공개되어 있습니다:
[`ghcr.io/artokun/comfyui-mcp-runpod:cu128-lean`](https://github.com/artokun/comfyui-mcp/pkgs/container/comfyui-mcp-runpod)
직접 아무것도 빌드하지 않고 RunPod 템플릿을 가리키고 싶을 때.
커스터마이즈하려면 — 버전을 고정하고, 추가 커스텀 노드를 굽고, 모델
레이아웃을 바꾸려면 — [`docker/runpod/`](https://github.com/artokun/comfyui-mcp/tree/main/docker/runpod)에서
직접 빌드하고 푸시하세요:
```bash theme={null}
cd docker/runpod
docker build -t /comfyui-mcp-runpod:cu128 .
docker push /comfyui-mcp-runpod:cu128
```
빌드 시점에는 GPU가 필요 없습니다. 그런 다음 **HTTP 포트 3000**이 노출되고
**`/workspace`에 네트워크 볼륨**이 있는, 이미지를 가리키는 RunPod **파드 템플릿**을
만드세요.
[`docker/runpod/README.md`](https://github.com/artokun/comfyui-mcp/blob/main/docker/runpod/README.md)가
전체 빌드 레퍼런스입니다 — 멀티스테이지 Dockerfile, 정확한 ComfyUI 실행
플래그, `extra_model_paths.yaml` 볼륨 매핑, Manager 원격 설치
게이트, 환경 변수, 크기/핀 트레이드오프.
## 다른 클라우드 대상
`connect` 흐름은 RunPod 전용이 아닙니다 — 에이전트 패널을 제공하는 **어떤**
도달 가능한 ComfyUI든 동작합니다 (다른 클라우드 호스트, VPS, LAN의 상자).
`connect`를 그 URL로 향하게 하고 외부 오케스트레이터 토글을 뒤집으세요:
```bash theme={null}
npx -y comfyui-mcp@latest connect https://your-comfyui.example.com
```
ComfyUI를 배포하는 것이 아니라 **comfyui-mcp 자체**를 호스팅되고 인증된
MCP 서버로 노출하려면, [원격 / 호스팅 커넥터](/docs/docs/ko/remote-connector)를
참고하세요.