cocofhu/grasp

지난 2년 동안 대규모 모델(large models)이 강력해지면서, 저는 광범위하게 탐색하고 150개 이상의 개인 프로젝트를 출시했습니다. 하지만 두 가지 문제가 계속 방해가 되었습니다:

다중 프로젝트 전환 비용이 높음— IDE 간을 오가며 실행 상태와 컨텍스트(context)를 정리하기 어려움; 병렬 에이전트 작업은 읽기 어려움— 모델들이 긴 텍스트 벽을 쏟아내어 실제로 중요한 내용을 묻어버리기 때문에, 이해하는 데 시간이 많이 소요됨.

그래서 저는 Grasp를 만들었습니다. 모든 프로젝트를 위한 하나의 플랫폼이자, 에이전트의 장황함을 한눈에 파악할 수 있는 시각적 요구사항 명확화(visual requirement clarification) 기능을 제공하여 인간의 처리량(human throughput)을 높입니다. 또한 Cursor, CodeBuddy, Claude Code와 같은 여러 에이전트 백엔드에도 연결됩니다.

웹사이트 · 빠른 시작 · 기여하기 · 설정 · 게이트웨이

English | 简体中文

grasp-demo.mp4

하나의 캔버스에서 다중 프로젝트, 다중 에이전트 개발을 오케스트레이션(orchestrate)합니다.

에이전트 출력을 검토하기 쉬운 구조화된 아티팩트(structured artifacts)로 변환합니다.

프로젝트, 에이전트 백엔드, 실행 구성을 하나의 플랫폼에서 관리합니다.

프로젝트 및 모델 전반에 걸친 토큰 사용량과 비용 배분을 추적합니다.

간단한 사전 개발 루프 (Short pre-dev loop):

One sentence → Grasp (clarify / plan / page.html) → Human gate → build

더 완전한 배포 머신 (Fuller delivery machine):

Clarify → Research → Human gate
→ Plan → Implement → Test → Review
→ Human confirm → PR / MR

같은 캔버스에 실패(fail) 및 롤백(rollback) 에지를 그릴 수 있습니다. 다음 실패는 이미 설계한 경로를 따르도록 해야 합니다.

• Linux 호스트
• Git
• Docker 및 Docker Compose

기본 경로는 게시된 GHCR 이미지(GHCR images)를 가져오며 로컬에서 빌드하지 않습니다:

git clone https://github.com/cocofhu/grasp.git
cd grasp
./start.sh -d

열기:

• UI / API: http://localhost:8080
• API health: http://localhost:8080/api/health
• Gateway health: http://localhost:8899/healthz
• Local demo login:
  admin

/demo1234`

The sandbox runtime은 처음 샌드박스를 생성할 때(Inbox / run 페이지에서 pull 로딩 표시) 요청에 따라 가져옵니다. pull로 워밍업하려면

./start.sh pull

을 사용하세요.

유용한 명령어:

./start.sh logs # 로그 추적
./start.sh down # 스택 중지
./start.sh pull # GHCR 이미지 새로고침
...

.env에서 이미지 태그 또는 다이제스트를 재정의하세요

; .env.example 참조

로컬 데모 계정으로 로그인합니다. 새 설치는 빈 프로젝트로 시작하며 샘플 워크플로우를 생성하지 않습니다.

• 프로젝트 자격 증명 설정(project credential settings)을 열고 cursor, claude_code, codebuddy, trae, opencode 또는 codex를 선택하고 일치하는 API 키를 저장합니다. Codex는 API 키가 아닌 ChatGPT 로그인 파일(~/.codex/auth.json)을 사용합니다. 에이전트 환경 변수 값은 폴백(fallback)으로 계속 사용할 수 있습니다. - 캔버스 열기: 기본 템플릿(Clarify → Implement → Test & review)에서 시작하거나 팔레트에서 Agents와 gates를 드래그하세요. 성공, 실패 및 롤백을 그리세요 — 재시도 시 다시 진입해야 하는 체크포인트를 표시합니다.
• 게시하고 실행을 시작하거나 (또는 Home에서 시작하여 한 문장으로 실행). 상태 추적(state trace), page.html 미리보기, 그리고 gates에 대기 중인 inbox 항목들을 확인하세요.

백엔드 인증, 프로젝트 자격 증명 설정 및 환경 변수 폴백에 대해서는 server/README.md를 참조하세요.

┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Vue 3 + Vue Flow │────▶│ Go Backend │────▶│ sandbox-gateway │
│ FSM canvas │◀────│ engine + API+MCP │◀────│ control plane │
...

web/
— Vue 3 + Vue Flow 캔버스, Home clarify, 실행 상세 정보, inbox 및 Agent Studio.
server/
— Go FSM 엔진, API, SQLite, artifact MCP, 스케줄링 및 감사(audit).
sandbox-gateway/gateway/
— 샌드박스 라이프사이클 제어 평면(control plane).
sandbox-gateway/sandbox/
— 범용 샌드박스 이미지 및 ACP 브릿지.
agents/
— 가져올 수 있는 역할 기반 에이전트 작업 공간(role-agent workspaces).
docs/

— 프로젝트 사이트 및 이중 언어 도움말 콘텐츠.

구성 우선순위는 명시적 환경 변수 > 마운트된 설정 파일 > 기본값입니다. 모든 옵션은 server/CONFIGURATION.md를, 게이트웨이 계약(gateway contract)은 GATEWAY.md를 참조하세요.

런타임 자격 증명(ACP API 키, Git 토큰 및 SSH 키)은 프로젝트 자격 증명 UI에서만 가져옵니다. Agent 환경 변수, 프로젝트 공유 환경 변수 및 sandbox.env는 비밀 키를 거부하며, 서버 자체의 프로세스 환경은 샌드박스로 주입되지 않습니다. 위에서의 우선순위는 플랫폼 서비스 구성에 적용되며, 런타임 자격 증명에는 적용되지 않습니다.

개발 요구 사항: Go, Node.js 및 Docker Compose; 샌드박스 실행을 위해서는 Linux가 필요합니다.

./start.sh dev -d

모듈별 lint, 테스트, 커버리지 및 E2E 명령어는 AGENTS.md와 CONTRIBUTING.md에 문서화되어 있습니다. 보안 워크플로는 푸시 및 풀 리퀘스트에서 CodeQL, 웹 npm audit, gitleaks를 실행합니다.

• 기본 계정은 로컬 데모 전용입니다. 공유 또는 프로덕션 배포 전에 자체 인증 사용자를 구성하세요.
• ACP API 키와 Git 자격 증명은 프로젝트의 자격 증명 UI에서만 관리하고, 절대 자격 증명을 커밋하지 마세요.
• 프로덕션 이미지는 다이제스트(digest)로 고정하세요. 릴리스 이미지 및 스모크 테스트를 참조하세요.
• 1.0.0이 첫 번째 안정적인 공개 릴리스입니다. 프로덕션 사용 전에 자체 보안 검토, 백업 및 용량 유효성 검사를 수행하십시오.
  리버스 프록시 호스트: 임시 승인 공유 링크는 이 요청의 Host에서 생성됩니다 (절대 클라이언트 X-Forwarded-Host를 사용하지 마세요). 브라우저 Host(예: nginx proxy_set_header Host $host)를 유지하고, 업스트림에서 TLS가 종료될 때 X-Forwarded-Proto를 전달하세요. SECURITY.md를 참조하세요.
  .DB ↔ 첨부 파일 수명 주기: 릴리스 Compose는 SQLite (./.localdata/db)를 앱 데이터/블롭(app-data/blobs) (./.localdata/app-data)와 분리합니다. 이 둘을 쌍으로 백업하고 정리하세요 (설정된 경우 사용자 지정 GRASP_BLOBS_ROOT 포함); 그렇지 않으면 Run 입력은 blob: 참조를 유지할 수 있으며, GET /api/blobs/:id에서 접근 가능합니다.

returns 404. Historical orphans는 영구적인 UI 플레이스홀더로만 표시되며, 이 릴리스에는 오펀 스캐너가 포함되지 않습니다. Quick start · Database and attachments를 참조하십시오.

• Core concepts
• Quick start
• Full configuration
• Gateway contract
• Contributing guide
• Security policy
• Support

Issues 및 pull requests는 환영합니다. 기여하기 전에 CONTRIBUTING.md, AGENTS.md, 그리고 CODE_OF_CONDUCT.md를 읽어보십시오.

MIT © 2026 cocofhu