AI 튜토리얼

풀스택 AI 채팅 앱 Whirl 셀프 호스팅 방법

Whirl을 로컬에 설치하고 실행하는 방법, 필수 서비스를 연결하는 방법, 첫 AI 대화를 시작하는 방법과 선택 기능을 알아보세요. 이 튜토리얼에서는 저장소 구조, 개인정보 보호 기능, 구성 전략, 셀프 호스팅 배포를 준비하기 위한 실용적인 팁도 다룹니다.

2026년 10월 3일약 10분 소요

Whirl이란?

Whirl은 Next.js와 Convex로 구축된 오픈 소스 풀스택 AI 채팅 애플리케이션입니다. whirl.chat의 코드로 사용되며 MIT 라이선스로 제공되므로, 코드를 검토하거나 직접 인스턴스를 실행하고 개선 사항을 기여할 수 있습니다.

이 프로젝트는 여러 AI 모델, 영구 메모리, 편집 가능한 아티팩트, 웹 리서치, 사용자 지정 도구, 개인정보 보호 중심의 대화를 하나의 인터페이스로 제공합니다. 모델 라우팅에는 OpenRouter를 사용하고, Convex는 데이터베이스, 백엔드 함수, 스트리밍, 예약 작업을 제공합니다.

주요 기능

다양한 주요 모델: 하나의 대화에서 최고 수준의 AI 모델을 사용하고 사고 수준을 조정할 수 있습니다.
지속적으로 활용되는 아티팩트: 문서, 차트, 인터랙티브 페이지를 만들고 사이드 패널에서 계속 편집할 수 있으며 링크로 공유할 수 있습니다.
도구 및 스킬: OAuth 기반 통합을 포함한 외부 도구를 MCP로 연결하고, Whirl의 동작을 확장하는 스킬을 설치할 수 있습니다.
장기 메모리: 대화 전반에 걸쳐 선호 사항과 프로젝트 맥락을 유지합니다.
최신 웹 정보: 웹을 검색하고 페이지를 읽어 최근 출처에 근거한 답변을 생성할 수 있습니다.
비공개 대화: 잠긴 채팅은 서버가 절대 받지 않는 비밀번호를 사용해 사용자의 기기에서 암호화됩니다. 이러한 대화에는 데이터 보존이 없는 모델만 사용됩니다.
생산성 기능: 시크릿 모드, 메시지 대기열, 음성 입력, 이미지 생성, 파일 첨부, 폴더, 공유 기능을 제공합니다.
사용자 지정 가능한 인터페이스: 라이트 모드 또는 다크 모드를 선택하고 강조 색상을 설정하며 Whirl을 모바일 웹 앱으로 설치할 수 있습니다.

기술 스택

프로덕션 웹 애플리케이션은 Next.js 16, React 19, Tailwind CSS v4, Motion을 사용합니다. Convex는 백엔드를 제공하고, Clerk는 인증을 처리하며, OpenRouter는 AI SDK를 통해 모델 액세스를 제공합니다. 저장소는 Bun 워크스페이스로 구성되어 있으며 TypeScript로 작성되었습니다.

핵심 설정에는 Convex, Clerk, OpenRouter만 필요합니다. 그 외 서비스는 선택 사항입니다.

결제: Autumn
웹 검색: Exa
메모리: Supermemory
분석: PostHog 및 Axiom
트레이싱: Braintrust
이메일: Resend
지원 에이전트: Median

선택적 서비스가 구성되지 않은 경우, Whirl은 애플리케이션 실행을 위해 해당 서비스를 요구하는 대신 그 서비스가 제공하는 기능을 숨깁니다.

사전 요구 사항

Whirl을 설치하기 전에 다음을 준비하세요.

컴퓨터에 설치된 Bun
무료 Convex 계정
Clerk 애플리케이션
OpenRouter API 키
저장소를 복제하기 위한 Git

1단계: Whirl 복제 및 설치

저장소를 복제하고 해당 디렉터리로 이동한 다음 Bun으로 모든 워크스페이스 종속성을 설치합니다.

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

2단계: Convex 백엔드 생성

백엔드 패키지로 이동해 Convex 개발 프로세스를 시작합니다.

cd packages/backend
bunx convex dev

처음 실행하면 Convex가 프로젝트와 개발 배포를 생성하는 과정을 안내합니다. 개발 중 백엔드 변경 사항이 동기화될 수 있도록 이 프로세스를 계속 실행해 두세요.

3단계: 백엔드 시크릿 구성

packages/backend에서 다른 터미널을 엽니다. Clerk JWT 발급자 도메인과 OpenRouter API 키를 Convex 환경에 추가합니다.

bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

예시 값을 본인의 Clerk 및 OpenRouter 계정에서 발급한 자격 증명으로 바꾸세요. 자세한 셀프 호스팅 문서에서 Convex에 필요한 Clerk JWT 템플릿을 확인할 수 있습니다.

API 키나 인증 시크릿을 저장소에 커밋하지 마세요. Convex 환경 명령과 적절한 환경 파일의 로컬 웹 설정을 사용해 백엔드 시크릿을 저장하세요.

4단계: 웹 애플리케이션 구성

프로덕션 웹 애플리케이션으로 이동한 다음 제공된 예시에서 로컬 환경 파일을 만듭니다.

cd ../../apps/v2
cp .env.example .env.local

.env.local을 열고 Convex와 Clerk에 필요한 네 가지 값을 입력하세요. 새 이름을 만들지 말고 예시 파일에서 정확한 변수 이름을 확인하세요.

5단계: 개발 환경 시작

저장소 루트로 돌아가 개발 명령을 시작합니다.

cd ../..
bun run dev

서비스가 실행되면 localhost:3000을 엽니다. 구성한 Clerk 애플리케이션을 통해 로그인하고 대화를 시작하세요.

기본 사용법

대화 시작

채팅 입력창에 요청을 입력하고 구성된 모델로 전송하세요. 다음과 같은 간단한 첫 프롬프트로 웹 앱, 인증, Convex 백엔드, OpenRouter 연결이 함께 작동하는지 확인할 수 있습니다.

이 애플리케이션의 주요 구성 요소를 간결한 다섯 가지 항목으로 설명하세요.

모델 사용

Whirl은 대화 중 OpenRouter를 통해 다양한 주요 모델에 액세스할 수 있도록 설계되었습니다. 애플리케이션과 선택한 모델에서 지원하는 경우 조정 가능한 사고 수준도 사용할 수 있습니다.

아티팩트 생성 및 개선

Whirl에 문서, 차트 또는 인터랙티브 페이지를 만들도록 요청할 수 있습니다. 이러한 아티팩트는 사이드 패널에서 계속 편집할 수 있고 링크로 공유할 수 있으므로, 한 번의 채팅 응답보다 지속적인 수정이 필요한 결과물을 만드는 데 유용합니다.

파일, 음성 및 정리 기능 사용

Whirl은 입력한 메시지뿐만 아니라 파일 첨부와 음성 입력도 지원합니다. 대화를 폴더로 정리할 수 있으며, 공유 기능을 사용하면 선택한 작업을 다른 사람과 공유할 수 있습니다.

저장소 이해하기

모노레포에는 여러 애플리케이션과 공유 백엔드가 포함되어 있습니다.

apps/v2: Whirl에서 사용하는 프로덕션 Next.js 웹 애플리케이션입니다.
apps/console: 모델, 통합 및 스킬을 관리하는 Vite 기반 관리 콘솔입니다.
apps/mobile: Expo로 구축된 네이티브 애플리케이션입니다.
apps/waitlist: 독립적인 대기자 명단 페이지입니다.
apps/remotion: 프로모션 동영상 컴포지션입니다.
apps/legacy: 이전 웹 애플리케이션으로, 참고용으로 유지되지만 더 이상 관리되지 않습니다.
packages/backend: Convex 스키마, 함수 및 AI 파이프라인입니다.
docs: 셀프 호스팅, 구성 및 아키텍처 가이드입니다.
brand: 로고, 색상, 배너 및 애플리케이션 아이콘입니다.

현재 웹 개발에서는 apps/v2와 packages/backend에 집중하세요. apps/legacy는 관리되지 않으므로 새로운 작업을 이곳에서 개발하지 마세요.

고급 팁

선택적 서비스를 단계적으로 추가하기

필수 Convex, Clerk 및 OpenRouter 설정부터 시작하세요. 핵심 채팅 흐름이 작동한 후 선택적 공급자를 하나씩 추가하세요. Whirl은 필수 키가 없는 기능을 자동으로 숨기므로, 더 작은 규모의 설치 환경을 운영하는 데 적합합니다.

청구, 검색, 메모리, 분석, 추적, 이메일 및 지원에 사용되는 환경 변수는 저장소의 구성 가이드를 참조하세요.

적절한 개인정보 보호 모드 선택

일반적인 영구 대화 흐름을 사용하지 않으려면 시크릿 모드를 사용하세요. 더 강력한 보호가 필요하다면 잠금 채팅을 사용하세요. 잠금 채팅은 서버가 알 수 없는 비밀번호로 기기에서 암호화되며, 데이터 보존이 없는 모델만 사용해 응답합니다. 클라이언트에만 저장된 비밀번호를 잃어버리면 암호화된 콘텐츠에 접근하지 못할 수 있다는 점을 기억하세요.

메시지 파이프라인 확인

스트리밍, 도구 호출 또는 모델 동작을 디버깅할 때는 프로젝트의 아키텍처 가이드를 읽어보세요. 이 가이드는 메시지가 작성기에서 모델로 이동한 후 다시 돌아오는 과정을 설명합니다. 관련 구현은 주로 프로덕션 웹 애플리케이션과 Convex 백엔드로 나뉘어 있습니다.

신중하게 프로덕션 준비하기

빠른 시작은 개발 환경을 생성합니다. 공개 배포 전에 Clerk JWT 템플릿 및 프로덕션 배포 지침을 포함한 전체 셀프 호스팅 가이드를 따르세요.

안전하게 기여하기

풀 리퀘스트를 열기 전에 프로젝트의 규칙과 확인 절차를 확인하려면 기여 가이드를 검토하세요. 행동 강령을 준수하고, 보안 문제는 공개 이슈가 아니라 SECURITY.md에 설명된 절차를 사용해 신고하세요.

결론

Whirl은 Next.js 인터페이스, Convex 백엔드, Clerk 인증 및 OpenRouter 모델 액세스를 결합한 기능이 풍부한 셀프 호스팅 AI 채팅 워크스페이스의 출발점을 제공합니다. 세 가지 필수 서비스로 시작하고, localhost:3000에서 로컬 채팅을 확인한 다음, 배포 환경의 필요에 따라 선택적 검색, 메모리, 분석, 청구 및 기타 통합 기능을 활성화하세요.