e2b-dev/fragments 딥다이브
— "AI가 코드를 짜는 걸 눈으로 본다" 오픈소스 Claude Artifacts

1한 줄 정체

Fragments는 "채팅으로 앱을 만들고 그 자리에서 실행까지 보는" 웹앱이다. 사용자가 "할 일 목록 앱 만들어줘" 같은 문장을 입력하면, 선택된 LLM(Claude·GPT·Gemini 등)이 자유로운 텍스트가 아니라 미리 정해진 필드를 가진 JSON(제목·설명·코드·실행 포트 등)을 스트리밍으로 채워 넣는다. 그 JSON이 완성되는 즉시 서버가 E2B 샌드박스라는 진짜 리눅스 컴퓨터를 하나 만들어, 거기에 코드를 파일로 써넣고 실행해 화면(웹앱이면 접속 URL, 데이터분석 코드면 실행 결과)을 사용자에게 돌려준다.

README가 스스로 밝히듯 이 프로젝트는 Anthropic Claude Artifacts, Vercel v0, GPT Engineer의 오픈소스 버전을 표방한다. 다만 이들과 달리 소스 전체가 공개돼 있어 구조를 그대로 읽을 수 있고, Apache-2.0 라이선스라 조건 없이 포크·수정·재배포가 가능하다.

2왜 지금 뜨는가

2022~2023년 챗봇들은 코드를 텍스트로만 뱉었다. 그런데 v0·Claude Artifacts·bolt.new·Lovable 같은 제품들이 잇달아 "프롬프트 → 구조화 출력 → 즉시 실행/미리보기"라는 3단 패턴으로 옮겨가면서, 이 패턴 자체가 AI 코딩 도구의 표준 UX가 됐다. Fragments가 주목받는 이유는 이 표준 패턴을 상용 서비스 수준으로 완결된 형태로, 그것도 통째로 오픈소스로 공개한 몇 안 되는 참고 구현이기 때문이다.

① "구조화 출력"이 핵심 인프라가 된 시점과 맞물림

Vercel AI SDK의 streamObject처럼 LLM 출력을 zod 스키마로 강제 스트리밍하는 기법이 실무 표준으로 자리잡으면서, 그 실전 예제를 찾는 개발자에게 Fragments의 lib/schema.ts·app/api/chat/route.ts는 그대로 베껴 쓸 수 있는 살아있는 교과서가 됐다.

② "코드 실행을 안전하게" 문제를 정면으로 푼 사례

AI가 생성한 임의의 코드를 서버에서 그냥 실행하면 보안 사고로 직결된다. Fragments는 E2B의 격리된 마이크로VM 샌드박스에서만 실행해 이 문제를 원천 차단한다. "AI 생성 코드를 안전하게 실행하려면 무엇을 써야 하나"라는 질문에 실물 답을 준다.

③ 벤더 자유 — 10개 넘는 LLM 제공자, 5개 스택

OpenAI·Anthropic·Google(AI Studio/Vertex)·Mistral·Groq·Fireworks·Together AI·xAI·DeepSeek·Ollama(로컬)까지 골라 쓸 수 있고, 생성 대상도 Python 데이터분석·Next.js·Vue·Streamlit·Gradio 다섯 스택 중에서 고를 수 있다. 특정 회사에 종속되지 않고 내 API 키, 내 서버로 똑같은 경험을 재현할 수 있다는 점이 셀프호스팅 수요를 끌어당긴다.

3무엇을 해결하나

Fragments가 실제로 없애주는 마찰은 크게 세 가지다.

문제 ① — "코드를 받았는데 돌려볼 방법이 없다"

일반 챗봇에서 코드를 받으면 사용자가 직접 파일을 만들고, 의존성을 설치하고, 실행해야 결과를 알 수 있다. Fragments는 /api/sandbox가 그 전 과정(패키지 설치 → 파일 작성 → 실행/URL 발급)을 자동으로 처리해, LLM 응답이 끝나는 순간 바로 눈으로 보이는 결과를 내놓는다.

문제 ② — "AI가 짠 임의 코드를 실행하면 위험하다"

서버가 직접 사용자 프롬프트로 생성된 코드를 실행하면 서버 자체가 뚫릴 수 있다. Fragments는 매 요청마다 E2B의 격리된 샌드박스(마이크로VM)를 새로 만들어 그 안에서만 실행하고, 10분 타임아웃까지 걸어둔다(sandboxTimeout = 10 * 60 * 1000). 메인 서버와 실행 환경이 물리적으로 분리된다.

문제 ③ — "특정 모델·스택에 갇힌다"

lib/models.ts의 providerConfigs가 제공자별 클라이언트 생성 로직을 한곳에 모아두고, lib/templates.ts가 생성 대상 스택을 한곳에 모아둔다. 새 모델이나 새 스택을 추가하는 지점이 코드베이스 안에서 명확히 하나로 정해져 있어, 포크해서 회사 내부 모델이나 내부 전용 스택으로 바꿔 끼우기 쉽다.

4전체 구조

Fragments의 심장은 "LLM 호출과 코드 실행을 완전히 분리된 두 개의 API 라우트로 나눈다"는 설계다. 채팅 UI는 자신이 지금 스트리밍 중인 JSON이 아직 완성되지 않았다는 것도, 완성되자마자 실행 요청이 나간다는 것도 모두 하나의 리액트 훅(useObject) 하나로 처리한다.

이 흐름에서 중요한 건 "/api/chat은 코드를 만들기만 하고, /api/sandbox는 실행만 한다"는 역할 분리다. LLM 호출 비용(시간이 오래 걸릴 수 있음, maxDuration = 300)과 샌드박스 실행 비용(maxDuration = 60)이 서로 다른 타임아웃 정책을 갖는 것도 이 분리 때문에 가능하다. 코드 편집을 위한 /api/morph-chat 라우트가 별도로 하나 더 있는데, 이는 5번 섹션에서 자세히 다룬다.

5핵심 설계 · 동작 원리

① 스키마가 진실원 — lib/schema.ts의 fragmentSchema

모든 것의 출발점은 zod로 정의된 fragmentSchema다. LLM은 이 스키마의 필드를 순서대로 채우도록 강제된다. 실제 필드는 이렇다.

export const fragmentSchema = z.object({
  commentary: z.string(),              // 지금 뭘, 왜 만드는지 설명(사용자에게 실시간으로 보임)
  template: z.string(),                // 어떤 스택 템플릿을 쓸지(예: "nextjs-developer")
  title: z.string(),                   // 프래그먼트 짧은 제목(최대 3단어)
  description: z.string(),             // 한 문장 설명
  additional_dependencies: z.array(z.string()),  // 템플릿에 없는 추가 패키지
  has_additional_dependencies: z.boolean(),
  install_dependencies_command: z.string(),      // 예: "npm i axios"
  port: z.number().nullable(),         // 열려야 할 포트, 없으면 null
  file_path: z.string(),               // 코드를 쓸 파일 경로
  code: z.string(),                  // 실제 코드 — 이 필드가 실행될 원본
})

이 스키마 하나가 system 프롬프트 · 스트리밍 파싱 · 프론트엔드 상태 · 샌드박스 실행 네 곳 전부에서 재사용된다. zod 스키마 하나를 서버 검증과 타입 정의 양쪽에 쓰는 전형적인 "스키마가 곧 진실원(source of truth)" 패턴이다.

② 프롬프트 조립 — lib/prompt.ts · lib/templates.ts

lib/prompt.ts의 toPrompt(template) 함수가 system 프롬프트를 만든다. 이 함수는 짧다 — "너는 실수하지 않는 숙련된 엔지니어다, 프래그먼트를 생성해라, 의존성 파일은 건드리지 마라"는 몇 줄의 규칙 뒤에, templatesToPrompt(template)가 만들어낸 사용 가능한 템플릿 목록을 붙인다. lib/templates.ts는 각 템플릿의 이름·설치된 라이브러리·기본 파일·포트를 하드코딩된 JS 객체로 갖고 있고, 이 함수는 그걸 번호 매긴 텍스트 목록으로 바꿔 LLM에게 "이 중에서 골라 쓰라"고 알려준다.

③ 구조화 스트리밍 — app/api/chat/route.ts

실제 라우트 핸들러는 streamObject({ model, schema, system: toPrompt(template), messages, maxRetries: 0 })를 호출하고 stream.toTextStreamResponse()로 응답한다. maxRetries: 0이 눈에 띄는데, LLM 호출이 실패해도 서버가 자동 재시도하지 않는다 — 실패는 그대로 lib/api-errors.ts의 handleAPIError()로 넘어가 사용자에게 "레이트리밋"·"과부하"·"인증 실패" 중 어떤 상황인지 구분된 메시지로 전달된다.

④ 프론트엔드의 부분 렌더 — app/page.tsx의 useObject

브라우저 쪽은 Vercel AI SDK의 experimental_useObject as useObject 훅을 쓴다. fragment 상태의 타입은 DeepPartial<FragmentSchema> — 스트리밍 도중에는 필드 일부만 채워진 "불완전한" 객체라는 뜻이다. 그래서 코드가 화면에 타이핑되듯 한 줄씩 채워지는 것처럼 보이는데, 사실은 이미 도착한 JSON 조각을 그때그때 리렌더하는 것뿐이다. 스트림이 끝나면 onFinish 콜백이 완성된 fragment를 들고 /api/sandbox로 새 요청을 쏜다.

⑤ 실행 — app/api/sandbox/route.ts

가장 핵심적인 부분이다. Sandbox.create(fragment.template, { metadata, timeoutMs: 10 * 60 * 1000 })로 10분짜리 격리 샌드박스를 하나 만든 뒤:

1. fragment.has_additional_dependencies가 참이면 sbx.commands.run(fragment.install_dependencies_command)로 패키지를 설치한다.
2. sbx.files.write(fragment.file_path, fragment.code)로 생성된 코드를 샌드박스 파일시스템에 그대로 써넣는다.
3. 템플릿이 code-interpreter-v1(순수 Python 실행)이면 sbx.runCode(fragment.code)로 즉시 실행해 stdout/stderr/그래프 결과를 반환한다.
4. 그 외(Next.js·Vue·Streamlit·Gradio 같은 웹 서버형 템플릿)면 sbx.getHost(fragment.port || 80)로 https://…e2b.app 형태의 접속 URL을 만들어 반환한다. 이미 그 스택의 개발 서버가 템플릿 안에서 자동 실행 중이라, URL만 넘겨주면 된다.

⑥ 템플릿 자체는 "빌드타임 자산" — sandbox-templates/

sandbox-templates/nextjs-developer/template.ts 같은 파일은 앱이 실행되는 동안 쓰이는 코드가 아니라, E2B CLI로 미리 빌드해 E2B 클라우드에 올려두는 도커 이미지 정의다. 예를 들어 Next.js 템플릿은:

export const template = Template()
  .fromNodeImage('24-slim')
  .aptInstall('curl')
  .setWorkdir('/home/user/nextjs-app')
  .runCmd('npx create-next-app@14.2.33 . --ts --tailwind …')
  .runCmd('npx shadcn@2.1.7 init -d')
  .runCmd('npx shadcn@2.1.7 add --all')
  .setWorkdir('/home/user')
  .setStartCmd('npx next --turbo', waitForPort(3000))

즉 Next.js·shadcn/ui가 미리 깔린 이미지를 만들고, setStartCmd로 "이 명령을 실행하고 3000번 포트가 열릴 때까지 기다려라"고 정의해둔다. 이렇게 만든 템플릿의 id가 lib/templates.ts의 키(nextjs-developer 등)와 정확히 일치해야 Sandbox.create(fragment.template, …)가 올바른 이미지를 찾아낸다 — 두 파일이 서로 다른 저장소 위치에 있으면서도 문자열 하나로 묶여 있는 셈이다.

⑦ 코드 편집은 재생성이 아니라 diff — Morph Apply (/api/morph-chat, lib/morph.ts)

프래그먼트가 이미 만들어진 뒤 "버튼 색을 파란색으로 바꿔줘"라고 후속 요청을 하면, 매번 전체 코드를 처음부터 다시 생성하는 건 느리고 비싸다. Fragments는 Morph Apply 모델(morph-v3-large, OpenAI 호환 엔드포인트)을 토글로 켤 수 있게 해뒀다. 흐름은:

1. app/api/morph-chat/route.ts가 generateObject로 morphEditSchema(변경 설명 + // ... existing code ... 표기가 섞인 부분 diff)를 먼저 뽑는다.
2. lib/morph.ts의 applyPatch()가 그 diff와 원본 코드를 Morph의 morph-v3-large 모델에 함께 넘겨 병합된 전체 코드를 받아온다.
3. 결과를 기존 FragmentSchema 모양 그대로 감싸 반환해, /api/sandbox 실행 흐름과 그대로 이어진다.

MORPH_API_KEY가 없으면 이 기능은 "설정에서 키를 넣거나 환경변수를 설정하라"는 에러를 던지고 끝난다 — 기본 채팅/생성 흐름과는 완전히 독립된 선택적 부가 기능이다.

⑧ 레이트리밋 — lib/ratelimit.ts

사용자가 자기 API 키를 넣지 않은 경우에만(!config.apiKey) 레이트리밋이 걸린다. @upstash/ratelimit의 슬라이딩 윈도(기본 1일 10회, RATE_LIMIT_MAX_REQUESTS/RATE_LIMIT_WINDOW 환경변수로 조정)를 @vercel/kv 저장소에 얹어 IP(x-forwarded-for) 단위로 센다. KV_REST_API_URL·KV_REST_API_TOKEN 환경변수가 없으면 이 함수는 그냥 아무것도 하지 않고 통과시킨다 — 로컬 개발 환경에서는 사실상 무제한이라는 뜻이다.

⑨ 인증과 팀 — lib/auth.ts · Supabase

Supabase 인증으로 로그인하면 getUserTeam()이 users_teams 테이블에서 기본 팀을 조회한다. 팀에 속한 사용자가 샌드박스를 만들면 X-Supabase-Team·X-Supabase-Token 헤더가 Sandbox.create 호출에 실려 E2B 쪽에 팀 단위 과금·접근 제어 정보를 전달한다. Supabase 환경변수가 없으면 useAuth()는 demo@e2b.dev라는 가짜 세션 객체를 만들어 로그인 없이도 데모가 굴러가게 한다.

⑩ 짧은 공유 URL — app/actions/publish.ts · middleware.ts

실행 중인 샌드박스 URL은 그 자체로는 길고 임시적이다. publish() 서버 액션은 URL이 *.e2b.app 도메인인지 검증하고, Sandbox.setTimeout()으로 만료 시간을 최대 24시간까지 늘린 뒤, nanoid로 짧은 id를 만들어 KV에 fragment:{id} → 실제 URL로 저장한다. 이후 /s/{id}로 접속하면 middleware.ts가 KV를 조회해 실제 샌드박스 URL로 302 리다이렉트한다. KV 환경변수가 없으면 짧은 URL 기능 자체가 조용히 꺼지고 원본 긴 URL이 그대로 반환된다.

6기술 스택 · 의존성

lib/models.json에는 11개 제공자, 50개 넘는 모델 항목이 등록돼 있다(OpenAI GPT-5 계열, Anthropic Claude Opus/Sonnet/Haiku, Google Gemini(AI Studio + Vertex 이중 경로), Mistral/Magistral, Groq, Fireworks, Together AI, xAI Grok, DeepSeek, Ollama 로컬 모델). 각 항목은 id·provider·providerId·multiModal 필드를 가지며, providerId가 lib/models.ts의 providerConfigs 키와 매칭돼 실제 클라이언트가 만들어진다.

7설치 · 요구사항

Fragments 자체(웹앱)를 로컬에서 띄우는 것과, 새 스택 템플릿을 만드는 것은 완전히 다른 두 개의 설치 절차다. 대부분은 전자만 하면 된다.

① 웹앱 로컬 실행

1. git clone https://github.com/e2b-dev/fragments.git
2. cd fragments && npm i — Node.js(최신 LTS 권장)와 npm이 필요하다.
3. .env.local 파일을 만들고 최소 두 개 값을 채운다: E2B_API_KEY(e2b.dev에서 발급)와, 쓰고 싶은 LLM 제공자 중 최소 하나의 API 키(예: ANTHROPIC_API_KEY 또는 OPENAI_API_KEY).
4. npm run dev(개발 서버, Turbo 모드) 또는 npm run build && npm run start(프로덕션 빌드).

② 선택적 환경변수 — 없어도 앱은 뜬다

③ 새 스택 템플릿 추가 — E2B CLI가 별도로 필요

sandbox-templates/ 아래 새 폴더를 만들고 E2B CLI(e2b template init → Dockerfile 수정 → e2b template build --name …)로 E2B 클라우드에 이미지를 미리 올린 다음, 그 템플릿 id를 lib/templates.ts에 손으로 추가해야 한다. 이건 npm 의존성 설치와 무관한 별도의 빌드타임 작업이다.

8실제 사용 흐름

9함정 · 오해 방지

이 저장소는 문서(README)와 실제 코드 사이에 실제로 대조 확인한 불일치가 여러 군데 있다. 문서만 보고 작업하면 헤매기 쉬운 지점들이다.

10대안 비교

11정리 · 누가 쓰면 좋은가

Fragments는 "프롬프트 한 줄이 눈에 보이는 실행 결과로 바뀌는" 경험을 어떻게 만드는지를 처음부터 끝까지 실제 소스로 보여주는 프로젝트다. 핵심은 세 겹이다 — ① zod 스키마로 LLM 출력을 강제하는 구조화 스트리밍(streamObject), ② 그 결과를 격리된 클라우드 샌드박스(E2B)에서 안전하게 실행하는 오케스트레이션, ③ 레이트리밋·인증·짧은 URL 같은 부가 기능을 환경변수 하나로 켜고 끄는 선택적 설계.

이런 사람에게 특히 도움이 된다.

• Vercel AI SDK의 구조화 출력(streamObject/generateObject)을 실전 코드로 배우고 싶은 개발자 — lib/schema.ts·app/api/chat/route.ts가 그대로 참고 예제가 된다.
• "AI가 생성한 코드를 안전하게 실행"하는 인프라가 필요한 팀 — E2B 샌드박스를 어떻게 생성·타임아웃·파일주입하는지 실물로 확인할 수 있다.
• 사내 전용 AI 코드 빌더를 셀프호스팅하고 싶은 회사 — 모델·템플릿·인증을 자기 것으로 바꿔 끼우기 좋은 구조로 나뉘어 있고, Apache-2.0라 법적 부담이 적다.
• Claude Artifacts·v0류 제품의 내부 구조가 궁금한 학습자 — 폐쇄형 제품에서는 볼 수 없는 "완성된 파이프라인"을 통째로 열람할 수 있다.

반대로, 이미 완성된 제품을 안정적으로 그냥 쓰고 싶다면 공식 데모(fragments.e2b.dev)나 v0·Claude Artifacts 같은 관리형 서비스가 더 맞을 수 있다. 이 레포는 구조를 이해하고 직접 운영할 사람을 위한 참고 구현이다.