CommonForge로 고객의 AI 에이전트가 코드 변경을 안전하게 제안한다

고객이 변경 작업을 요청하고 코딩 에이전트가 코드를 수정하면, 에이전시가 검토·승인한 뒤 운영 환경에 반영할 수 있는 셀프 호스팅 작업 공간 CommonForge가 공개됐다. 각 작업은 코드의 격리된 사본에서 진행되며, 변경 사항은 검증과 스테이징을 거친 뒤 승인된다. 승인된 버전은 복원할 수 있다.

CommonForge는 Cloudflare Workers와 Cloudflare Artifacts에서 실행된다. 사용자는 스크립트 하나로 자신의 Cloudflare 계정에 배포하고, 에이전트는 cforge 명령줄 인터페이스(CLI)를 통해 작업한다. 8분 데모 영상에서 고객과 에이전시의 에이전트가 같은 기능을 병렬로 만들고, 충돌을 배포 전에 잡아내는 과정을 볼 수 있다.

작업 흐름과 권한

처음 배포한 운영자는 이메일 매직 링크로 로그인한다. 배포 설정의 관리자 목록(COMMONFORGE_ADMIN_EMAILS)에 등록된 주소만 조직을 만들 수 있다. 고객마다 조직을 하나씩 만들고, 프로젝트는 고객 사이트 하나에 대응한다. 프로젝트의 개요 화면에는 실제 프로젝트 상태를 바탕으로 진행 상황을 보여주는 시작 체크리스트가 있다.

프로젝트에 코드를 가져올 때는 Files → Add에서 공개 Git 저장소를 첫 버전으로 가져온다. 운영 환경에 배포하려면 Settings → Policy의 Release 항목에서 사이트 빌드 방법과 운영 환경을 실행하는 Cloudflare Worker를 지정한다. 준비된 예시도 제공된다. 이후 Versions → Publish this version에서 준비, 게시 승인, 게시 절차를 거친다.

Policy의 Staging 항목을 켜면 상시 스테이징 환경을 사용할 수 있다. 스테이징은 운영 환경에 현재 배포된 버전에서 시작하므로, 먼저 첫 버전을 게시해야 한다. 고객은 Members → Invite에서 Client 역할로 프로젝트에 초대한다. 고객은 자신에게 지정된 프로젝트만 볼 수 있다.

운영자는 Settings → Access에서 각 폴더의 고객 권한을 정한다. Can change는 고객의 에이전트가 폴더를 변경하고 그 변경을 검토용 스테이징에 보내도록 한다. Read only는 읽기만 허용하고, No access는 접근을 막는다. 새 고객은 운영자가 권한을 바꾸기 전까지 읽기 전용이다. 작업을 만들 때 에이전트가 변경·열람하거나 접근하지 못할 폴더는 고객이 아니라 운영자가 설정한 이 권한을 따른다.

고객은 Tasks 보드에서 제목과 원하는 변경 내용만 적어 작업을 만든다. Give to agent 화면의 Copy prompt for your agent 버튼은 에이전트가 설치, 로그인, 작업 가져오기, 제출까지 수행하도록 안내하는 프롬프트를 복사한다. 사용자는 명령을 실행할 수 있는 코딩 에이전트에 이를 붙여 넣는다. 예를 들어 Claude Desktop의 Code 탭, Codex, Claude Code, Cursor를 이용할 수 있다. 에이전트는 cforge가 없으면 설치하고, 프롬프트에 포함된 일회용 코드로 로그인한 뒤 작업 폴더의 사본을 받아 변경하고 cforge submit으로 제출한다. 버튼 아래에는 같은 절차를 수동으로 실행하는 방법도 접혀 있다.

제출된 변경은 공유 스테이징 사이트로 보내지고 작업 상태는 In staging으로 바뀐다. 고객은 스테이징에서 변경을 확인한다. 요청한 고객이나 개발자가 보드에서 변경을 운영 환경으로 승격할 수 있지만, 운영 반영에는 승인과 게시가 필요하다. 게시 단계는 별도로 진행하며, 기본적으로 운영자에게 권한이 있다.

스테이징을 쓰지 않는 프로젝트에서는 변경 사항이 Changes를 거친다. 새 작업을 만든 뒤 에이전트에 전달하고, 제출이 끝나면 Make proposal을 선택한다. 제안은 변경 과정을 보여주는 Change storyboard로 열린다. 프로젝트 검증 항목을 실행한 다음 승인, 새 버전으로 수락, 게시가 서로 분리된 기록으로 남는다. 이런 프로젝트의 고객은 필터링된 에디션 사본을 수정해 제안으로 보낸다.

화면에는 작업 상태가 Working, In staging, Waiting for approval, Live로 진행되는 보드, 에이전트에 전달할 프롬프트, 요청·변경·검증 결과와 다음 결정을 보여주는 변경 스토리보드, 승인된 버전과 운영 버전 및 복원 기능이 표시된다. 시작 안내는 빈 조직에서 첫 고객 작업을 실제로 게시하기까지의 절차를 안내한다. 스크린샷은 예시 데이터가 아니라 아래의 로컬 스택에서 가져왔다. 다시 생성하려면 다음 명령을 실행한다: pnpm --filter @commonforge-org/web run screenshots. 관련 테스트는 apps/web/e2e/readme-screenshots.spec.ts에 있다.

구현 구조와 저장소 구성

각 작업은 별도의 격리된 Artifacts 저장소에서 처리되며, 자격 증명은 해당 저장소에만 접근할 수 있고 수명이 짧다. 고객의 에디션은 운영 저장소에 접근할 수 없다. SQLite를 사용하는 Durable Object 원장이 어떤 변경을 승인 버전으로 만들지 원자적으로 결정한다. 기준 버전이 오래된 제안은 거부하고, 승인은 정확한 제안 해시에 연결한다. 복원도 과거 버전으로 되돌리는 대신 새 버전을 앞으로 추가하는 방식이다.

Cloudflare Sandbox 컨테이너의 통합 실행기가 Git 병합, 검사, 미리보기 빌드와 푸시를 맡는다. Artifacts API에는 쓰기 권한이 없으므로 모든 쓰기는 실행기에서 git push로 처리한다. 저장소에는 다른 제품에서도 사용할 수 있는 버전 관리 작업 공간 엔진(@commonforge-org/*)도 포함된다. 구성 요소로는 core, ledger, providers, runner protocol, conformance suites가 있다.

아키텍처에서는 웹 앱·cforge CLI·에이전트가 세션 쿠키 또는 bearer 자격 증명을 사용해 HTTPS로 Worker에 접속한다. Worker는 Hono API, 인증과 브로커, SQLite 기반 OrgLedger Durable Object, D1 디렉터리, outbox와 cron을 담당한다. 서명된 작업은 Queue를 통해 Runner로 전달되고, 결과와 자격 증명은 서비스 바인딩으로 돌아온다. Runner는 작업별 Sandbox 컨테이너에서 Git 병합·검사·푸시와 빌드를 수행한다. Artifacts에는 조직별 canonical·tasks·editions 저장소가 있고, R2는 자산·매니페스트·내보내기를 보관한다. commonforge-preview는 R2와 미리보기별 컨테이너를 사용해 토큰으로 접근을 제한한 미리보기를 제공한다.

Worker 이름은 데모 인스턴스의 이름이다. 초기 배포에서는 <name>-worker, <name>-runner, <name>-preview를 사용한다. HTTP API, 배포 전제 조건, 알려진 차이는 apps/worker/API.md에 정리돼 있다. 코드 주석과 문서의 “plan §…”, “PRD §…”, “AT-NN”(인수 테스트), “Task N”은 공개되지 않은 내부 계획 문서를 가리킨다. 저장소의 코드, 테스트와 문서가 기준 자료다.

로컬 실행과 Cloudflare 배포

자격 증명 없이 로컬에서 빠른 시작을 하려면 Node.js 22 이상, package.json에 고정된 버전의 pnpm(corepack enable), Git이 필요하다. Cloudflare 계정 없이 제품 전체를 실행하는 명령은 다음과 같다.

pnpm install
scripts/dev-local.sh # or: pnpm dev:local; PORT=8813 scripts/dev-local.sh for another port

http://127.0.0.1:8799을 열고 owner@agency.e2e.test로 로그인한다. 이 주소만 조직을 만들 수 있으며, ADMIN_EMAIL=you@example.test로 바꿀 수 있다. 이메일은 전송하지 않는다. 로그인 링크는 터미널에 [commonforge dev] magic link for <email>: <link> 형식으로 출력되고 apps/worker/.wrangler/dev-local.log에도 저장된다. 같은 브라우저에서 링크를 연다. CLI를 사용하려면 다음과 같이 빌드하고 로그인한다.

pnpm exec turbo run build --filter=@commonforge-org/cli # bundles apps/cli/dist/index.js
node apps/cli/dist/index.js login --api-url http://127.0.0.1:8799 --email owner@agency.e2e.test

CLI 로그인 링크(…/auth/cli?code=…)도 서버 터미널에 출력된다. cforge가 요청하면 붙여 넣거나 cforge login --code <code>를 실행한다.

이 환경은 로컬 스택 E2E 테스트가 사용하는 스택이다. 실제 웹 앱을 제공하는 제어 평면 Worker는 wrangler dev -c apps/worker/wrangler.e2e.jsonc로 실행하며, D1, Durable Objects, R2, Queue는 로컬에서 동작한다. 다만 Cloudflare Artifacts, 통합 실행기, Cloudflare API는 메모리 기반 가짜 구현이다. 따라서 Git 푸시, 병합, 검사와 배포는 시뮬레이션되고 미리보기는 실행되지 않으며, 실행할 때마다 모든 상태가 비어 있는 상태에서 시작한다. apps/worker/.dev.vars는 읽지 않는다.

Cloudflare 계정에 CommonForge 전체를 배포하는 스크립트는 scripts/bootstrap.sh다. 멱등적이므로 다시 실행하면 배포를 갱신한다. 계정에는 Workers Paid, Cloudflare Artifacts, Containers(Sandbox)가 필요하다. 실행하는 컴퓨터에는 이미지 빌드용 Docker, Node.js 22 이상, pnpm과 API 토큰이 필요하다. 토큰에는 Workers Scripts, Workers R2 Storage, D1, Queues, Workers KV Storage, Containers, Artifacts: Edit, Account Settings: Read 권한이 필요하다. Worker에는 Artifacts 전용 토큰을 따로 부여한다.

export CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=… # wrangler + account API (never echoed)
export CF_API_TOKEN=… # the Worker's Artifacts token (Artifacts: Edit)
export COMMONFORGE_DEPLOY_API_TOKEN=… # optional: release deploys (Workers Scripts + KV: Edit)

scripts/bootstrap.sh --name acme --email-mode log --admin-emails you@acme.com --smoke # a test deployment
scripts/bootstrap.sh --name acme --admin-emails you@acme.com,@acme.com \
 --email-from login@acme.com --app-domain forge.acme.com --preview-domain preview.acme.net
scripts/teardown.sh --name acme # list what it created
scripts/teardown.sh --name acme --yes # delete it and verify nothing is left

사용자 지정 도메인과 발신 이메일 도메인은 배포 계정과 같은 Cloudflare 계정의 zone이어야 한다. 앱 도메인과 미리보기 도메인은 달라야 한다. 미리보기는 사이트 코드를 실행하며 앱의 origin을 공유하지 않는다. 발신 도메인을 Cloudflare Email Service에 등록하는 과정은 수동이며, 스크립트가 필요한 단계를 출력한다.

전제 조건, 모든 플래그, 토큰 범위, 상태와 소유권 규칙, 해제 절차는 docs/SELF-HOSTING.md에 있다. 이 문서는 실제 Cloudflare 리소스를 사용하는 로컬 개발과 프로젝트 데모·CI 인스턴스용 유지관리 스크립트(scripts/deploy-live.sh, scripts/deploy-ci.sh, scripts/ci-live/)도 다룬다.

CLI는 다음 명령으로 설치할 수 있다. Node.js 22 이상과 Git이 필요하다.

npm install -g @commonforge-org/cli

직접 수정한 CLI를 실행하려면 Node.js 22 이상, Git, pnpm을 갖추고 소스에서 빌드한다.

git clone https://github.com/CommonForge-org/commonforge.git
cd commonforge
pnpm install
pnpm --filter "@commonforge-org/cli..." build
npm install -g ./apps/cli

그다음 cforge login --api-url <your app URL> --email <you>를 실행한다. 앱의 Give to agent 화면은 작업에 맞춰 나머지 절차를 보여주고, Copy prompt for your agent로 에이전트가 이를 수행하게 할 수 있다. 앱의 전달 패널에도 같은 명령이 표시된다. 공개하지 않은 CLI를 수정해 자체 호스팅하는 경우, apps/web/src/lib/handoff.ts의 CLI_PUBLISHED를 false로 설정하면 소스 빌드 방법을 표시한다.

Claude와 Codex 연동

cforge mcp는 AI 앱에 로그인, 프로젝트·작업 목록 조회, 작업 생성·가져오기·제출 도구를 제공한다. 앱의 Account 페이지에서 앱별 설정을 확인하고 일회용 로그인 코드를 만들 수 있다.

• Claude Desktop: 최신 릴리스의 commonforge.mcpb 확장 파일을 열고 Install을 누른다.
• Claude Code: /plugin install commonforge --marketplace CommonForge-org/commonforge를 실행한다.
• Codex: ~/.codex/config.toml에 [mcp_servers.commonforge] 항목을 추가한다. 자세한 내용은 apps/cli/README.md에 있다.

플러그인과 Codex 설정은 npx -y @commonforge-org/cli mcp로 서버를 실행한다. Node.js 22 이상이 필요하지만 별도 설치는 필요하지 않다. 도구는 로그인한 사용자가 할 수 있는 작업만 수행한다. 테스트 범위는 docs/LIMITATIONS.md에 설명돼 있다.

빌드와 테스트

pnpm install
pnpm build # turbo: every package, the web app, the Worker bundles
pnpm typecheck
pnpm test # unit and integration tests (miniflare, real git, fakes for Artifacts/runner)

pnpm --filter @commonforge-org/web exec playwright install chromium # once
pnpm test:e2e # Playwright: fixture-mode UI + the local stack (no credentials)
pnpm test:fault # fault injection via COMMONFORGE_CHAOS flags + provider fault conformance
pnpm test:security # the security acceptance tests across worker, runner, core, runner-protocol, conformance
pnpm test:live # live-provider tests; need CF_API_TOKEN (CI runs them only when the secret is set)

각 테스트 모음에서 실제 구성 요소와 가짜 구현을 무엇으로 쓰는지는 docs/LIMITATIONS.md §8에 정리돼 있다. 나머지 기여 지침은 CONTRIBUTING.md에 있다.

데모와 검증 결과

YouTube 데모는 8분 28초 분량이며 챕터와 자막을 제공한다. 고객 에이전트와 에이전시 에이전트가 하나의 기능을 병렬로 만들고, 배포 전 충돌을 발견한 뒤 변경 사항을 스테이징에서 운영 환경으로 보내는 과정을 보여준다. 이어 저장소에서 새 배포 환경을 설정하고 고객이 Claude Code에 작업을 맡기는 장면도 담겼다. 프로젝트는 Cloudflare 계정에서 자체 데모 인스턴스를 운영한다. 단계별 대본은 docs/DEMO-SCRIPT.md에 공개돼 있다.

Artifacts와 Sandbox의 동작에 의존하기 전에 설계의 전제 조건을 실제 Cloudflare 계정에서 측정했다. 증거는 spikes/*/RESULTS.md에 있다.

Cloudflare에 배포한 환경, 즉 사용자의 배포본이나 데모 인스턴스에서는 핵심 흐름을 시뮬레이션하지 않는다. 실제 Artifacts 저장소, 실제 Sandbox 컨테이너의 git push, 실제 Durable Object 원장, R2, Queue, Email Service, 실제 wrangler deploy 릴리스를 사용한다. 예외는 로컬 빠른 시작이다. 이 환경은 Artifacts, 실행기와 Cloudflare API를 가짜 구현으로 대체하며 이를 명시한다.

실제 서비스가 아닌 것으로 표시되는 기능도 있다. 웹 앱의 fixture 모드(VITE_COMMONFORGE_FIXTURE=1)는 메모리 기반 샘플 데이터로 UI를 실행하고 항상 “Fixture mode” 배너를 띄운다. 이 모드는 fixture-mode E2E 테스트에서만 사용한다. E2E, 장애 주입, 보안 테스트 모음도 Artifacts, 실행기와 Cloudflare API를 테스트 대역으로 교체하고 이를 표시한다.

현재 구현의 주요 제약은 다음과 같다.

• 미리보기는 단일 origin을 공유한다. 미리보기 Worker에서 경로별로 제공하며 토큰으로 접근을 제한하고 만료시킨다.
• 조직마다 원장 Durable Object가 하나씩 있다.
• 기준이 오래된 변경은 거부하며 자동 재기준은 하지 않는다.
• 로그인은 매직 링크만 지원한다.
• ArtifactFS는 없다. 내보내기는 일반 Git 번들과 자산 매니페스트를 사용한다.
• 비공개 Git 저장소는 가져올 수 없다. 확인된 ZIP 입력은 리소스를 비어 있는 상태로 만든다. 아카이브를 복사하는 실행기 단계는 아직 없다.

전체 제한 사항은 docs/LIMITATIONS.md에 있다. 기여 방법은 CONTRIBUTING.md와 행동 강령을 참고한다. 취약점은 공개 이슈가 아니라 SECURITY.md의 절차로 신고해야 한다.

코드는 CommonForge 기여자 저작권의 MIT 라이선스(© 2026)로 제공된다. 라이선스와 제3자 라이선스 고지를 확인할 수 있다. CommonForge 이름과 brand/의 로고는 MIT 라이선스에 포함되지 않는 상표이며, 자세한 내용은 brand/README.md에 있다.