코드 대신 실행 중인 앱을 돌려주려면: v0의 chat 상태·미리보기·배포 구분

고객 지원팀이 “문의 분류 앱을 만들어 줘”라고 요청했다고 해 보자. 코드 블록만 반환하는 도구라면 사용자가 파일을 옮기고 실행 환경을 준비해야 한다. 반대로 실행 화면을 결과로 보여 주는 도구라면, 다음 요청인 “우선순위 필터와 담당자 열도 넣어 줘”가 같은 앱의 수정으로 이어져야 한다. 이 차이는 응답 포맷보다 상태 보존과 접근 경계의 설계 문제에 가깝다.

Vercel의 v0 API 발표는 프롬프트로 앱을 생성하고 Vercel Sandbox에서 개발 서버를 시작한 뒤, 자체 UI에 넣을 수 있는 미리보기를 제공한다고 설명한다. 다만 미리보기가 보인다는 사실을 요구사항 충족이나 공개 배포 완료로 읽으면 안 된다. 실무에서 먼저 나눌 것은 앱의 작업 공간인 chat, 실행 화면을 전달하는 미리보기, 그리고 명시적인 배포다.

발표 원문의 날짜는 2026년 8월 5일이다. 이 글은 2026년 10월 26일 수집한 발표 본문과 API v2 공식 문서를 함께 읽은 분석이다. 문서의 현재 세부사항을 모두 발표 당일 기능이었다고 소급하지 않는다. 이 글은 공식 문서에 근거한 통합 설계 분석이며, 유료 API 호출·앱 생성·미리보기 보안 시험·Vercel 배포를 직접 수행한 결과가 아니다.

1. 결과를 코드 문자열에서 이어서 수정할 작업으로 바꾸기

공식 발표에서 chat은 한 앱의 상태를 담는 작업 공간이다. 후속 메시지는 현재 상태에서 계속된다. 따라서 앱 생성 요청으로 받은 chat ID를 보관하고, 같은 앱의 변경 요청은 같은 chat으로 보내는 것이 통합의 출발점이다. 아래 전후 비교는 이해를 돕는 가상 요청이며 실제 생성 화면이나 실행 로그가 아니다.

사용자 요청	코드 문자열만 반환할 때의 과제	상태 있는 앱 도구로 설계할 때
문의 분류 앱 만들기	반환 파일을 저장하고 실행 환경 마련	새 chat 생성 후 앱 작업과 chatId 연결
우선순위 필터 추가	이전 코드와 변경본의 관계를 별도 관리	저장한 chatId로 후속 메시지 전달
같은 앱 다시 열기	저장 파일과 실행 환경을 다시 찾기	작업 식별자로 chat 조회 후 미리보기 접근

이 표의 오른쪽 열은 문서의 상태 모델에서 도출한 설계 제안이다. 고객 ID, 앱 ID 같은 metadata로 chat을 묶을 수 있지만, metadata가 접근 권한을 보장하는 것은 아니다. “이 고객의 chat 목록에 나온다”와 “현재 요청자가 그 chat을 열 권한이 있다”는 별개의 판단이다. 앱 서버에는 사용자·내부 작업 ID·chatId의 연결을 관리하고 권한을 검사하는 지점이 필요하다.

같은 앱의 후속 변경은 보관한 chatId를 사용한다. 요청 예시는 설명용이며 실제 생성 화면이 아니다. 출처: vercel.com/blog/introducing-the-new-v0-api.

같은 앱을 계속 수정하려는데 매번 새 chat을 만들면, 제품 쪽에서 의도한 연속 작업과 API 작업 공간이 어긋날 수 있다. 반대로 별개의 앱을 같은 chat으로 보내는 것도 피해야 한다. 한 저장소나 Vercel 프로젝트에 여러 chat이 존재할 수 있으므로, 프로젝트 ID만으로 현재 앱 작업을 추정하지 않는 편이 명확하다. 이는 문서 기반 운영 해석이지 데이터 공유 여부를 직접 시험한 결과는 아니다.

출처: 공식 발표의 Start with a chat, 이전 가이드의 Replacing projects with metadata.

2. iframe에 주소를 꽂기 전에 프록시의 책임부터 정하기

미리보기는 브라우저가 공급자 주소를 아무 조건 없이 여는 형태가 아니다. 공식 가이드는 서버에서 chats.getPreview로 미리보기 URL과 짧은 수명의 토큰을 가져오고, 제어 가능한 프록시를 통해 iframe 요청을 전달하도록 설명한다. v0 API 키는 서버에 남겨야 하며 브라우저 코드에 포함시키면 안 된다.

여기서 fetchPreview는 사용자 인증을 대신하지 않는다. 해당 사용자가 그 chat에 접근할 수 있는지 알지도 못한다. 따라서 문서·정적 자산·앱 내부 요청을 전달하는 각 프록시 요청에서 자체 인증과 chat 접근 권한 확인을 수행해야 한다. 다른 사람이 chatId를 알아냈다는 이유만으로 열 수 있는 구조라면, 토큰이 짧게 유지된다는 설명으로 그 문제를 해결할 수 없다.

API 키는 서버에 두고 프록시 요청마다 접근권한을 확인한다. fetchPreview는 사용자 인증이나 chat 권한을 판정하지 않는다. 출처: v0.app/docs/api/v2/guides/accessing-previews.

토큰 캐시는 응답의 expiresAt을 기준으로 다룬다. 문서 예제의 60_000밀리초는 만료 직전 캐시 재사용을 피하기 위한 비교 여유이지, 토큰의 고정 수명을 뜻하지 않는다. 이 수치만 보고 “토큰은 60초 동안 유효하다”고 구현해서는 안 된다. 문서는 getPreview가 null을 반환하거나 오래된 정보가 감지되면 loading 경로로 전환하고 재시도하는 흐름도 설명한다. 시작 중인 상태와 실패 상태를 구별해야 하지만, 여기서 준비 시간이나 재시도 성공률은 확인되지 않았다.

또 하나 놓치기 쉬운 지점은 루트 상대경로다. 생성된 HTML의 /_next/static/... 같은 요청은 iframe의 origin을 기준으로 해석된다. catch-all 경로만 만든 것으로 끝내지 않고, 문서의 프레임워크 수준 라우팅까지 함께 읽어야 한다. 가이드의 Referer 확인은 이 요청을 프록시 경로로 보내기 위한 라우팅 로직이지 사용자 권한 경계가 아니다.

출처: Accessing Previews의 프록시·캐시·loading·루트 상대경로 설명.

3. 다른 서브도메인과 다른 site를 혼동하지 않기

생성된 미리보기는 신뢰할 수 없는 코드를 실행할 수 있다. 공식 가이드는 호스트 앱과 registrable domain이 다른 preview-only origin을 사용하라고 명시한다. 예컨대 app.example.com과 preview.example.com은 origin은 다르지만 같은 site에 속하며, 부모 도메인 범위의 쿠키를 공유할 수 있다. 아래 주소는 모두 설명용 예시이며 실제 서비스나 이 글의 배포 주소가 아니다.

도메인은 모두 설명용이다. 호스트 앱과 다른 registrable domain의 preview-only site가 문서의 격리 경계다. 출처: v0.app/docs/api/v2/guides/accessing-previews.

가이드의 allow-scripts allow-same-origin을 “부모 앱과 같은 origin을 허용한다”로 해석하면 방향이 반대가 된다. 여기서 allow-same-origin은 문서가 격리된 프록시의 origin을 유지하게 하는 설정이다. 그 격리 origin은 호스트 앱과 다른 site에 있어야 한다. preview-only 호스트에는 민감한 앱 엔드포인트를 함께 두지 않으며, 해당 호스트를 trusted preview hosts에도 등록해야 한다.

쿠키 기반 로그인 앱은 추가 검토가 필요하다. 문서에 따르면 fetchPreview는 들어오는 Cookie·Authorization·프록시 인증 헤더를 upstream에 전달하지 않고, upstream의 Set-Cookie도 제거한다. 따라서 호스트 앱의 로그인 쿠키를 생성 앱에 그대로 넘기겠다는 가정은 맞지 않는다. 서버 쿠키에 의존하는 미리보기 앱에는 대체 인증 흐름이 필요하다는 문서의 제한까지 설계에 포함해야 한다. 이 설명은 문서의 보안 경계이며, 본문에서 침투 시험이나 계정 간 격리 검증을 했다는 뜻은 아니다.

출처: Accessing Previews의 Configure the iframe와 Use an isolated preview origin.

4. 응답 완료와 미리보기 준비와 배포 완료를 분리하기

채팅 응답 완료, 미리보기 준비, 공개 배포 완료를 하나의 성공 상태로 합치지 않는다. 이 원칙을 제품의 상태 표기로 바꾸면 다음과 같은 진단표가 된다. 표의 상태 이름은 독자에게 제안하는 제품 설계 용어이며 v0의 공식 상태 enum을 복제한 것이 아니다.

지금 얻은 근거	UI가 말해도 되는 범위	아직 말하면 안 되는 것	다음 확인
비동기 요청의 식별자	작업이 접수되어 후속 조회 가능	앱 생성 완료	해당 chat/message의 결과 조회
스트림의 진행 parts	도구 작업과 변경 진행을 표시	요구사항 검증 완료	완료 응답과 실제 동작 확인
프록시로 접근 가능한 미리보기	현재 개발 서버 화면을 확인 가능	운영 배포 완료	앱 요구사항·데이터·권한 검증
명시적 deploy 호출의 반환 정보	배포 작업을 추적할 식별 정보 확보	배포 성공과 공개 접근 자동 확정	배포 상태·로그·공개 접근 확인

상태 이름은 이 글의 설계 제안이다. 접수나 실행 화면을 배포 성공으로 확대하지 않고 각 단계의 근거를 확인한다. 출처: v0.app/docs/api/v2/guides/migrating-from-v1-to-v2.

API v2는 동기·비동기·스트리밍을 별도 endpoint 변형으로 나눈다. 동기는 결과가 끝날 때까지 기다리고, 비동기는 즉시 반환한 뒤 조회하며, 스트리밍은 진행 과정을 UI에 표시하는 데 쓰인다. 세 방식은 응답 전달 방식의 선택이지 서로 다른 품질 등급이 아니다. 응답에 포함되는 usage도 사용량 정보이지 이 글에서 확인한 최종 청구 금액이나 비용 절감률이 아니다.

미리보기 뒤에는 별도의 배포 결정이 있다. 공식 발표와 이전 가이드는 Vercel 프로젝트 연결 및 chat 배포 호출을 따로 설명한다. 따라서 도구 결과를 설계한다면 코드 본문 하나 대신 내부 작업 식별자, chatId, 인증된 미리보기 진입점, 배포 여부를 구별한 정보를 반환하는 구성이 유용하다. 여기의 항목은 필드 설계 제안이며 실제 API 응답 스키마나 이 글에서 호출해 받은 JSON이 아니다.

출처: 이전 가이드의 Sync, async, and streaming 및 Replacing deployment workflows, 공식 발표의 Connect a Vercel project.

5. 기존 v1 작업이 있다면 새 v2 작업으로 연결을 다시 잡기

기존 연동을 고칠 때는 endpoint 문자열만 바꾸는 것으로 끝나지 않는다. 문서는 API v2가 v1 chat을 직접 실행하지 않는다고 설명한다. 보존할 v1 버전을 골라 ZIP으로 내려받고, 그 ZIP으로 새 v2 chat을 만든 뒤 이후 메시지와 미리보기·배포를 새 chat으로 옮기는 흐름이다. 과거 ID는 추적용 metadata에 남길 수 있지만 새 작업의 식별자를 대체하지 않는다.

ZIP import는 URL 방식이다. 큰 archive는 HTTPS URL, 작은 archive는 data URL을 사용하는 설명이 있으며 multipart 파일 업로드를 받는다는 뜻은 아니다. 이관 대상 파일 상태를 옮기는 것과 이전 대화 기록 전체가 그대로 이어진다는 주장을 구별해야 한다. 사용자가 예전 작업을 다시 열었을 때 앱 서버의 연결표가 새 v2 chat을 가리키는지도 함께 검토할 지점이다.

출처: Migrating existing v1 chats.

도입 판단: 실행 화면을 주되 완료의 의미는 좁게 유지하기

v0를 붙이는 목적이 자체 서비스 안에서 앱을 만들고 계속 수정하게 하는 것이라면, 핵심은 코드 생성 버튼이 아니라 작업 수명주기를 소유하는 일이다. 같은 앱의 chat을 이어 쓰고, 미리보기는 인증된 격리 프록시로 전달하며, 배포는 별도의 명시적 단계로 다루는 구성이 서로 맞물려야 한다.

반대로 이번 목적이 정적인 코드 조각 하나를 검토하는 일뿐이라면 이 전체 구조가 언제나 필요한 것은 아니다. 실행 앱을 결과로 제공하려는 순간에는 미리보기의 유효기간·접근권한·도메인·배포 상태를 함께 책임져야 한다. 문서에 실행 가능한 환경이 있다는 설명과, 우리 요구사항을 충족한 운영 앱이 검증되었다는 주장은 다르다. 계정별 API 접근 조건과 가격, 실제 생성 품질·지연·보안 적합성은 이 글에서 확인하지 않았으며 도입 전 별도 검증 대상이다.

함께 읽으면 구분이 선명해지는 글

• Vercel Sandbox 생성이 느려졌다면: 첫 작업까지 재고 오류 경계를 옮기자 — 준비된 실행 환경과 실제 작업 성공을 나누는 관점이다. 이 글의 미리보기·배포 구분과 연결되지만 v0 생성 속도를 대신 측정한 자료는 아니다.
• Cursor 클라우드 Canvas: 팀에 보내기 전 확인할 공유 조건 — 결과 화면 공유와 작업 환경 관리를 구분한다. v0의 실행 앱 미리보기와 같은 기능이라고 보지 않으면서, 수신자가 어떤 결과에 접근하는지 비교해 읽을 수 있다.

읽은 공식 자료

• Vercel: Introducing the new v0 API — chat 상태와 미리보기·배포의 기본 흐름.
• v0 API v2: Accessing Previews — 프록시, 토큰, 인증, 다른 site 격리의 구체적 경계.
• v0 API v2: Migrating from v1 to v2 — 응답 방식과 기존 작업의 이관 의미.
• v0 API v2: Quickstart — API 키를 서버에 두는 시작 구조. 명령을 이 글에서 실행한 것은 아니다.