wandb/openui · 제작 Chris Van Pelt(W&B 공동창업자) 외 · 라이선스 Apache-2.0 · 백엔드 버전 0.5.0(Python) · 프런트 package.json 버전 1.0.0(비공개 npm) · 백엔드=Python 3.9+/FastAPI · 프런트=React 18+Vite+Jotai · GitHub Releases 0건, Docker 이미지는 커밋 SHA 태그로 배포 · 실질 기능 커밋은 2025-09 "Add catnip"이 마지막, 이후 2026-06-30까지는 Renovate 봇의 의존성 자동 업데이트뿐 · 이 문서는 2026-07-29 기준 최신 커밋 42d7ab4을 클론해 분석)
OpenUI는 "UI 카피라이터"다. 사용자가 "가격표 카드 3개짜리 프라이싱 섹션 만들어줘" 같은 문장을 치면, 선택한 LLM(OpenAI·Groq·Ollama·LiteLLM 경유 Anthropic/Gemini 등)이 TailwindCSS 클래스로 채워진 HTML을 토큰 단위로 스트리밍 생성하고, 화면은 그 HTML을 <iframe>에 실시간으로 렌더링한다. 결과가 마음에 안 들면 채팅하듯 "버튼을 더 크게 해줘" 라고 이어서 요청(refine)하거나, 아예 다른 프레임워크 코드로 바꿔달라고 요청할 수 있다.
README가 스스로 밝히듯 "v0 같지만 오픈소스이고 덜 다듬어진 버전"이다. 실제로 Vercel v0가 널리 알려지기 전인 2024년 초에 공개되어, "자연어로 UI를 그리는" 이 카테고리의 초기 오픈소스 레퍼런스 역할을 했다.
당신이 "이런 느낌의 카드 UI"라고 말로 설명하면, 디자이너(LLM)가 그 자리에서 스케치(Tailwind HTML)를 그려 보여준다. 마음에 안 들면 "여기 좀 더 크게" 하고 옆에서 코멘트를 달듯 고칠 수 있다.
그리고 완성된 스케치를 들고 "이건 React 팀에, 이건 Vue 팀에 맞게 정리해줘"라고 부탁하면, 같은 디자이너가 다시 처음부터 그 언어로 손으로 옮겨 그려준다(자동 변환기가 아니라 "다시 그리기"라는 점이 핵심).
이 문서를 정직하게 쓰기 위해 먼저 밝혀둘 것이 있다. OpenUI는 지금 새롭게 뜨는 레포가 아니다. 커밋 로그를 직접 확인해 보면, 사람이 작성한 마지막 기능 커밋은 2025년 9월("Add port 6369", "Add catnip")이고, 그 이후 2026년 6월 30일까지 올라온 커밋은 전부 Renovate 봇의 의존성 자동 업데이트뿐이다. GitHub Releases는 0건이다. 그럼에도 이 레포를 딥다이브할 가치가 있는 이유는 셋이다.
Vercel v0, bolt.new, lovable, thesysdev/openui(동명이인 — 9번 섹션 참고) 같은 "설명하면 UI가 나온다" 제품들이 쏟아지기 전에, OpenUI는 2024년 초부터 같은 아이디어를 완전히 공개된 소스로 구현하고 있었다. 이 장르가 실제로 어떻게 동작하는지 상용 서비스의 블랙박스 없이 코드로 직접 확인할 수 있는 몇 안 되는 창구다.
README는 이 프로젝트를 "W&B가 차세대 LLM 애플리케이션 툴링을 테스트·프로토타이핑하기 위해 쓰는 도구"라고 설명한다. 실제로 평가 파이프라인(backend/openui/eval/)은 W&B의 실험 추적 도구인 Weave로 생성된 UI의 품질을 스크린샷 비교로 평가한다. 즉 OpenUI는 그 자체로 "우리 회사 도구를 우리 제품으로 검증한다"는 드문 사례를 보여주는 실물 자료다.
실무에서는 활발한 레포보다 이런 레포를 훨씬 많이 만난다: 한동안 잘 만들어졌고, 핵심 아이디어는 여전히 유효하지만, 메인테이너가 다른 일로 옮겨가며 봇 커밋만 남은 상태. "커밋 로그와 이슈를 보고 이 프로젝트가 살아있는지 판단하는 법"을 연습하기에 좋은 교재다.
이 문서는 스타 수를 인용하지 않는다. 대신 사실만 적는다: 주 기여자는 Chris Van Pelt(W&B 공동창업자 겸 CTO) 1인에 가깝고, 커뮤니티 PR은 가끔 머지된다(예: 2024-12 Ollama 모델명 버그 수정). 새 기능·모델 프로바이더 추가는 2025년 하반기 이후 멈췄다. 코드에 등장하는 gpt-4-vision-preview, claude-3-opus-20240229 같은 모델명도 그 시점에 멈춘 흔적이다.
따라서 "지금 바로 실무에 쓸 최신 도구"로 접근하기보다, "생성형 UI 파이프라인의 원리를 배우는 교재"로 접근하는 편이 정확하다.
UI를 처음부터 코딩하는 일은 의외로 오래 걸린다. 레이아웃 잡고, 색 맞추고, 반응형 처리하고, 다크모드까지 신경 쓰다 보면 "일단 뭔가 눈에 보이는 것"이 나오기까지 시간이 든다. OpenUI는 이 초안(prototype) 단계를 몇 초로 줄인다.
<!--FIX (1): ...-->)을 남기면 그 지점만 콕 집어 고치라고 지시할 수도 있다.OpenUI가 만드는 것은 바로 배포 가능한 프로덕션 코드가 아니다. 접근성, 실제 데이터 바인딩, 상태 관리 같은 것은 사람이 다시 손봐야 한다. 이 도구가 잘하는 것은 "빈 화면과 씨름하는 첫 30분을 없애는 것"이다.
OpenUI는 backend/(Python·FastAPI)와 frontend/(React·Vite) 두 폴더로 나뉘는 단일 저장소다. 빌드된 프런트 정적 자산은 backend/openui/dist에 복사되어 같은 서버가 API와 화면을 함께 서빙한다(CI가 npm run build 후 자동 커밋). 흥미로운 지점은 "누가 어떤 일을 하는가"의 분배다.
즉 "무엇을 만들지"에 대한 지시(시스템 프롬프트·프레임워크 변환 프롬프트)는 프런트엔드 TypeScript 코드 안에 있고, 백엔드는 그 지시를 실행할 LLM을 안전하게 골라 대신 호출해 주는 인증·쿼터·프록시 계층에 가깝다. 이 분업 구조는 5번 섹션에서 더 깊이 다룬다.
대부분의 "AI 코드 생성기"는 서버에서 시스템 프롬프트를 관리한다고 생각하기 쉽다. OpenUI는 다르다. 실제로 생성 품질을 좌우하는 시스템 프롬프트가 frontend/src/api/openai.ts의 systemPrompt 상수에 그대로 하드코딩되어 있다:
export const systemPrompt = `🎉 Greetings, TailwindCSS Virtuoso! 🌟
...
*Implementation Rules:*
- Only implement elements within the <body> tag, don't bother with <html> or <head> tags.
- Avoid using SVGs directly. Instead, use the <img> tag ...
`
이 프롬프트를 브라우저가 직접 OpenAI SDK 클라이언트로 감싸(MyOpenAI extends OpenAI) 호출하는데, 이때 baseURL을 외부 API가 아니라 같은 출처의 /v1으로 돌려놓는다. 그래서 브라우저에 실제 OpenAI API 키가 노출되지 않고, 서버가 그 키를 대신 들고 있다가 프록시해 준다. "프롬프트 로직은 프런트에, 비밀 키와 접근 통제는 백엔드에"라는 분업이다.
data: {...}\n\n 형식으로 토큰을 하나씩 흘려보내는 단방향 스트리밍 방식. OpenUI는 OpenAI·Groq·LiteLLM·Ollama 네 가지 서로 다른 응답 형식을 전부 OpenAI 청크 형식의 SSE로 통일해 프런트에 넘긴다.
초보자가 가장 많이 오해하는 지점이다. HTML을 React나 Vue로 "변환"한다고 하면 babel 같은 AST 기반 트랜스파일러를 떠올리기 쉽지만, OpenUI의 실제 구현(frontend/src/api/openai.ts의 convert())은 이렇다:
const systemPromptConvert = `You're a frontend web developer that specializes in $FRAMEWORK.
Given html and javascript, generate a $FRAMEWORK component. Factor the code into smaller
components if necessary. Keep all code in one file. Use hooks and put tailwind class strings
that are repeated atleast 3 times into a shared constant. Leave comments when necessary.`
const userPrompt = `Please turn this into a ${framework} component.`
즉 "$FRAMEWORK 전문 개발자인 척 하는 프롬프트" + "이 HTML을 그 프레임워크 컴포넌트로 바꿔줘"라는 일반 대화형 요청을 한 번 더 LLM에 던지는 것이 전부다. 문법적으로 유효한 React인지, 실제로 컴파일되는지 검증하는 단계는 없다. 결과가 그럴듯하지만 실행은 안 되는 코드일 수 있다는 뜻이다.
이건 "번역기"라기보다 "같은 사람에게 다른 언어로 다시 써 달라고 부탁하는 것"에 가깝다. 원문의 의미는 대체로 옮겨지지만, 문법 오류가 섞이거나 미묘하게 다른 표현이 나올 수 있다 — 자동 번역 소프트웨어의 결정론적 정확성과는 다르다.
백엔드의 POST /v1/chat/completions(backend/openui/server.py)는 요청 바디의 model 문자열 접두어만 보고 라우팅한다: gpt-*는 OpenAI로, groq/*는 Groq로, litellm/*는 사내 LiteLLM 프록시로, ollama/*는 로컬 Ollama로, dummy는 테스트용 고정 응답으로 보낸다. Ollama 응답은 형식이 다르기 때문에 ollama.py의 openai_to_ollama() / ollama_to_openai()가 양방향으로 변환해 프런트가 프로바이더 차이를 몰라도 되게 만든다.
LiteLLM 쪽은 더 흥미롭다. litellm.py의 generate_config()는 환경변수(ANTHROPIC_API_KEY, GEMINI_API_KEY, COHERE_API_KEY, MISTRAL_API_KEY, OPENAI_COMPATIBLE_ENDPOINT 등)가 있는지 검사해 런타임에 LiteLLM 설정 YAML을 즉석에서 생성하고, __main__.py가 그 설정으로 LiteLLM 프록시 프로세스를 자식 프로세스로 띄운다. "환경변수만 넣으면 알아서 여러 LLM이 모델 목록에 나타난다"는 체감의 실제 구현이다.
프로덕션 환경에서는 사용자당 최근 24시간 토큰 사용량(Usage.tokens_since, peewee+SQLite)이 OPENUI_MAX_TOKENS(기본 70만 토큰)를 넘으면 429를 반환해 비용을 제어한다. 동시에 dummy라는 가짜 모델(backend/openui/dummy.py)을 두어, Playwright E2E 테스트(?dummy=good 쿼리)가 실제 LLM 과금 없이 고정된 HTML 응답으로 렌더링·다크모드·테마 변경·HTML 편집까지 검증하게 한다 — "LLM 호출 코드를 결정론적으로 테스트하는 법"의 좋은 예다.
backend/openui/db/models.py에는 Credential 테이블(공개키·서명 카운트·AAGUID)이 정의돼 있고 프런트에도 frontend/src/lib/webauthn.ts가 있지만, 서버 라우트 어디에도 이를 사용하는 코드가 없다. 심지어 webauthn.ts 파일 최상단 주석에 "This is from an earlier experiment and is not currently being used"라고 스스로 적혀 있다. 실제 로그인은 GitHub OAuth(fastapi-sso) 또는 로컬 환경에서의 자동 익명 세션(get_session에서 OS 사용자명으로 자동 가입)뿐이다.
| 계층 | 구성 |
|---|---|
| 백엔드 프레임워크 | FastAPI + uvicorn. Python ≥3.9, 패키징은 hatchling, 의존성 관리는 uv |
| LLM 클라이언트 | openai SDK(OpenAI·Groq·Ollama·LiteLLM 모두 OpenAI 호환 엔드포인트로 통일), ollama 파이썬 클라이언트, tiktoken(입력 토큰 카운트, cl100k_base 고정) |
| 인증 · 세션 | fastapi-sso(GitHub OAuth), itsdangerous 서명 쿠키 기반 SessionMiddleware, 커스텀 DBSessionStore |
| 저장소 | peewee ORM + SQLite(WAL 모드, ~/.openui/db.sqlite). 공유(share) 기능은 boto3로 S3 호환 스토리지(gzip 압축 JSON)에 업로드 |
| 관측 · 평가 | Weave(W&B 자체 LLM 관측 도구) — 서버 실행 시 자동 계측, backend/openui/eval/은 생성 UI를 스크린샷 비교로 채점하는 별도 평가 파이프라인 |
| 프런트 프레임워크 | React 18 + Vite + Jotai(전역 상태, jotai-minidb로 IndexedDB 영속화) + TanStack Query |
| UI/스타일 | TailwindCSS + Radix UI 프리미티브(shadcn 계열) + Monaco Editor(HTML 직접 편집) + i18next(다국어) |
| 테스트 | Vitest(단위) + MSW(API 목킹) + Playwright(E2E, dummy 모델 이용) · 백엔드는 pytest |
| 배포 | Docker(ghcr.io/wandb/openui, GH Actions로 amd64/arm64 멀티아치 빌드+provenance attestation), Fly.io(backend/fly.toml, 라이브 데모용) |
| 방법 | 내용 |
|---|---|
| Docker(권장) | docker run --rm -p 7878:7878 -e OPENAI_API_KEY -e ANTHROPIC_API_KEY ghcr.io/wandb/openui 후 localhost:7878 접속. API 키가 없어도 뜨긴 하지만 해당 프로바이더 모델은 목록에 안 나온다 |
| Docker Compose | docker-compose up -d — ollama 컨테이너 + openui 컨테이너를 함께 띄운다. docker exec -it openui-ollama-1 ollama pull llava로 비전 모델 준비 필요 |
| 소스(Python) | uv sync --frozen --extra litellm → source .venv/bin/activate → python -m openui. Python 3.9+ 필요. 프런트를 직접 개발하려면 frontend/에서 pnpm install && npm run dev(별도 5173 포트, 프록시로 백엔드 연결) |
| LLM 키(전부 선택) | OPENAI_API_KEY / GROQ_API_KEY / GEMINI_API_KEY / ANTHROPIC_API_KEY / COHERE_API_KEY / MISTRAL_API_KEY / OPENAI_COMPATIBLE_ENDPOINT+_API_KEY. 아무것도 없어도 Ollama만으로 로컬 실행 가능 |
| Ollama | 기본 http://127.0.0.1:11434. Docker에서는 OLLAMA_HOST=http://host.docker.internal:11434로 지정. 이미지 입력을 지원하는 모델은 llava, moondream 정도로 제한적 |
| 개발 환경 | Dev Container / GitHub Codespaces(devcontainer.json 제공) / Gitpod 원클릭 설정 지원 |
README가 안내하는 openui.fly.dev 데모와 ghcr.io/wandb/openui 이미지는 CI가 자동 빌드하지만, 정식 세맨틱 버전 릴리스 태그가 하나도 없다(GitHub Releases 0건). 이미지 태그는 브랜치명 또는 커밋 SHA 기준이라, "안정된 버전"이라는 개념 자체가 약하다. 프로덕션에 쓸 생각이라면 반드시 커밋을 직접 확인하고 포크해서 관리하는 편이 안전하다.
/ai/new모델을 고르고(상단 설정 톱니바퀴), 프롬프트를 입력하거나 이미지를 붙여넣는다. action: 'create'로 createOrRefine()이 호출되고, 응답 맨 앞에는 항상 ---\nname: ...\nemoji: ...\n--- 형태의 프론트매터가 먼저 오도록 시스템 프롬프트가 지시한다 — 이걸로 각 버전에 이름·이모지를 붙인다.
스트리밍되는 마크다운에서 HTML 코드 블록만 파싱(lib/html.ts의 parseHTML)해, Tailwind CDN 스크립트와 shadcn 스타일 CSS 변수를 감싼(wrappedCode) 완전한 HTML 문서를 만들고 <iframe id="version-0">에 주입한다. 다크/라이트 토글, 테마(색상 팔레트) 변경이 즉시 반영된다.
결과가 마음에 안 들면 채팅창에 후속 요청을 치거나, Monaco 에디터로 HTML을 직접 고칠 수 있다. 스크린샷을 다시 첨부해 "이 부분처럼 고쳐줘"라고 하면 action: 'refine'이 기존 HTML + 새 지시사항을 함께 LLM에 넘긴다.
완성된 HTML 옆의 프레임워크 탭(React/Svelte/Vue/Angular/Preact/Web Component/Streamlit)을 누르면 convert()가 별도 LLM 호출을 한 번 더 실행해 그 프레임워크 코드를 생성한다. 결과를 실제로 실행·컴파일해 검증하지는 않는다(5번 섹션 참고) — 항상 눈으로 확인할 것.
완성된 컴포넌트는 /v1/share/{id}로 S3 호환 스토리지에 업로드해 고유 링크로 공유할 수 있고, /v1/vote로 좋아요/싫어요를 남기면 Component·Vote 테이블에 기록된다(팀 내부 프롬프트/모델 품질 비교용으로 보인다).
이 문서가 다루는 것은 wandb/openui다 — Weights & Biases가 만든 Apache-2.0 오픈소스, Python FastAPI 백엔드 + React 프런트, LLM에게 매번 새로 Tailwind HTML을 생성시키는 프로토타이핑 도구다.
이것과 전혀 다른 thesysdev/openui가 있다 — Thesys라는 회사가 만든 "Generative UI" 상용 제품/SDK로, React·Next.js 애플리케이션에 C1 API를 붙여 실시간으로 UI를 생성하는 것을 목표로 한다. 깃허브에서 "openui"로 검색하면 둘 다 뜨고, 블로그·튜토리얼 글에서도 종종 섞여 인용된다. 제작사(W&B vs Thesys), 라이선스, 대상(로컬 프로토타입 도구 vs SDK 제품), 코드 구조가 전부 다르니 링크를 클릭해 저장소 소유자를 반드시 확인하라.
저장소 루트, frontend/LICENSE, backend/LICENSE 세 곳 모두 실제 라이선스 전문은 Apache License 2.0이다. 그런데 frontend/package.json의 "license" 필드는 "MIT"라고 적혀 있다. npm 패키지 메타데이터만 보고 "MIT라서 자유롭다"고 판단하면 안 된다 — 실제 법적 효력이 있는 것은 LICENSE 파일이고, Apache-2.0에는 특허 조항 등 MIT에 없는 조건이 있다.
5번 섹션에서 다뤘듯, React·Vue·Svelte 변환 버튼은 babel/SWC 같은 결정론적 트랜스파일러가 아니라 매번 다른 결과가 나올 수 있는 LLM 호출이다. 같은 HTML을 두 번 "React로 변환"해도 완전히 동일한 코드가 나온다는 보장이 없고, 문법 오류가 섞여 나올 수도 있다. 변환 결과는 항상 직접 실행해서 확인해야 한다.
Credential 테이블과 webauthn.ts는 "이전 실험의 잔재"라고 코드 자체에 주석으로 적혀 있다. 실서비스 인증은 GitHub OAuth 또는(로컬 실행 시) 자동 익명 세션뿐이다. 스키마에 있다고 해서 실제로 그 인증 방식을 쓸 수 있다고 오해하지 말 것.
프로덕션 모드에서 사용자별 24시간 토큰 쿼터(MAX_TOKENS)를 서버가 강제하고, E2E 테스트는 dummy 모델로 완전히 격리돼 있어 CI에서 실수로 실제 LLM API에 과금이 발생하지 않는다. "AI 기능을 안전하게 테스트하는 법"을 참고하기엔 충분히 좋은 예다.
| 도구 | 차이점 |
|---|---|
| Vercel v0 | 상용 SaaS, 소스 비공개. Next.js/React 생태계에 최적화되어 있고 완성도·디자인 품질이 높다. OpenUI가 스스로 "v0 같지만 오픈소스이고 덜 다듬어졌다"고 인정하는 비교 대상 |
| abi/screenshot-to-code | 오픈소스, 스크린샷 → 코드에 특화(HTML/React/Vue/Bootstrap/Ionic 등). OpenUI보다 활발히 유지보수되는 편이며 이미지 입력 중심 워크플로에 더 특화됨 |
| e2b-dev/fragments | 오픈소스, LLM이 만든 코드를 샌드박스(E2B)에서 실제로 실행까지 시켜준다는 점이 다르다. OpenUI는 iframe 렌더링에 그치지만 fragments류는 "실행 가능한 결과물"을 목표로 한다 |
| thesysdev/openui (C1) | 동명이인, 상용 SDK 성격. 기존 React 앱에 API로 통합하는 제품형 접근 — OpenUI(W&B)의 "독립 실행 프로토타입 웹앱"과는 목적 자체가 다르다 |
| bolt.new / lovable | UI 조각이 아니라 "전체 애플리케이션(백엔드 포함)"을 생성하는 더 큰 범위의 상용 제품. OpenUI는 의도적으로 범위를 "UI 컴포넌트 하나"로 좁게 유지한다 |
백엔드 약 1,100줄, 핵심 프런트 로직 몇백 줄 수준이라 하루 이틀이면 전체 파이프라인을 다 읽을 수 있다. 또한 Ollama만으로 완전 오프라인 구동이 가능해, "생성형 UI가 내부적으로 어떻게 동작하는지" API 키 없이 실습하기에 가장 접근성이 좋다.
OpenUI는 지금 가장 빠르게 성장하는 프로젝트는 아니지만, "LLM으로 UI를 생성한다"는 아이디어가 실제로 어떤 코드로 구현되는지 — 프롬프트를 어디에 두고, 여러 프로바이더를 어떻게 하나의 인터페이스로 흡수하고, 스트리밍을 어떻게 안전하게 프록시하는지 — 를 부담 없는 크기의 실제 코드로 볼 수 있는 몇 안 되는 저장소다.