지박스

gbox는 MCP 통합 또는 기타 AI 에이전트 활용 사례를 위한 자체 호스팅 샌드박스를 제공하는 오픈 소스 프로젝트입니다. 샌드박스는 에이전트의 컴퓨터로 사용할 수 있으며, 터미널, 브라우저, 파일 편집기 등 에이전트의 일상 업무에 필요한 모든 도구를 포함합니다. 자세한 내용은 "기능" 섹션을 참조하세요.

MCP의 인기가 점점 높아짐에 따라, Claude Desktop/Cursor와 같은 MCP 클라이언트가 로컬에서 안전하게 작업을 실행할 수 있도록 하는 쉬운 방법이 없다는 것을 알게 되었습니다. 이 프로젝트는 gru.ai 기술을 기반으로 하며, 시스템 명령과 MCP 서버에 통합하여 사용하기 쉽게 만들었습니다.

고급 시나리오의 경우 k8s 클러스터에서 로컬 또는 원격으로 샌드박스를 실행할 수 있는 기능도 유지했습니다.

특징

단말기
- 모든 리눅스 명령을 실행하세요
- 파이썬 스크립트를 직접 실행하세요
- 여러 호출 간 세션 공유 [개발 중]
파일
- 호스트 머신 폴더를 샌드박스에 마운트합니다.
- http 링크를 통해 샌드박스 파일에 액세스
- 멀티모달로 파일 내용 읽기
- 파일 쓰기/다시 쓰기 [개발 중]
- 파일 편집 [개발 중]
- 파일 검색 [개발 중]
브라우저
- 모든 URL을 열고 다중 모달로 콘텐츠를 반환합니다.
- 모든 URL에서 다운로드 [개발 중]
- [개발 중] 지침에 따라 브라우저 작동
- 인간의 점령 [미개발]
HTTP 서버
- 필요에 따라 모든 폴더에서 http 서비스 시작 [개발 중]
SDKs
- Python SDK: pip install pygbox 사용하여 설치하세요. 자세한 내용은 PyPI를 참조하세요.
- Typescript SDK [개발 중]
엠씨피
- 표준 MCP 지원
- Claude Desktop 및 커서 통합

사용 사례

Claude Desktop과 같은 AI 클라이언트는 gbox MCP를 사용하여 다음과 같은 더 나은 결과를 제공할 수 있습니다.

4. 로컬 파일 처리

다운로드 폴더에서 이미지를 찾아 zip으로 압축합니다. https://claude.ai/share/f8c4c617-9b32-4062-a8e2-2ab33ef46f42

5. 임의의 작업 실행

유튜브 비디오 다운로드: https://claude.ai/share/c2ab6bcb-7032-489f-87d5-cc38f72c2ca9

설치

시스템 요구 사항

macOS 10.15 이상
Mac용 Docker Desktop
홈브루

참고: 다른 플랫폼(Linux, Windows)에 대한 지원도 곧 제공될 예정입니다.

설치 단계

지엑스피1

업데이트 단계

# Update gbox to the latest version
brew update && brew upgrade gbox

# Update the environment
gbox setup

# Export and merge latest MCP config into Claude Desktop
gbox mcp export --merge-to claude
# or gbox mcp export --merge-to cursor

# Restart Claude Desktop

명령줄 사용법

이 프로젝트는 샌드박스 컨테이너를 관리하기 위한 명령줄 도구 gbox 제공합니다.

# Cluster management
gbox cluster setup    # Setup cluster environment
gbox cluster cleanup  # Cleanup cluster environment

# Container management
gbox box create --image python:3.9 --env "DEBUG=true" -w /app -v /host/path:/app   # Create container
gbox box list                                                                      # List containers
gbox box start <box-id>                                                            # Start container
gbox box stop <box-id>                                                             # Stop container
gbox box delete <box-id>                                                           # Delete container
gbox box exec <box-id> -- python -c "print('Hello')"                               # Execute command
gbox box inspect <box-id>                                                          # Inspect container

# MCP configuration
gbox mcp export                          # Export MCP configuration
gbox mcp export --merge-to claude        # Export and merge into Claude Desktop config
gbox mcp export --dry-run                # Preview merge result without applying changes

볼륨 마운트

gbox box create 명령은 -v 또는 --volume 플래그를 사용하여 Docker 호환 볼륨 마운트를 지원합니다. 이를 통해 호스트 시스템과 샌드박스 컨테이너 간에 파일과 디렉터리를 공유할 수 있습니다.

볼륨 마운트 구문은 다음 형식을 따릅니다.

-v /host/path:/container/path[:ro][:propagation]

어디:

/host/path : 호스트 시스템의 파일이나 디렉토리 경로
/container/path : 컨테이너에 파일이나 디렉토리가 마운트될 경로
ro (선택 사항): 마운트를 읽기 전용으로 만듭니다.
propagation (선택 사항): 마운트 전파 모드(개인, rprivate, 공유, rshared, 슬레이브, rslave)를 설정합니다.

예:

# Basic bind mount
gbox box create -v /data:/data --image python:3.9

# Read-only bind mount
gbox box create -v /data:/data:ro

# Multiple bind mounts
gbox box create \
  -v /config:/etc/myapp \
  -v /data:/var/lib/myapp:ro \
  -v /logs:/var/log/myapp:ro:rprivate \
  --image python:3.9

참고: 컨테이너를 생성하기 전에 호스트 경로가 존재해야 합니다. 호스트 경로가 없으면 컨테이너 경로가 자동으로 생성됩니다.

개발 설정

필수 조건

1.21 이상 버전 사용
도커 데스크톱
만들다
pnpm(corepack을 통해)
Node.js 16.13 이상

짓다

# Build all components
make build

# Create distribution package
make dist

러닝 서비스

# API Server
make -C packages/api-server dev

# MCP Server
cd packages/mcp-server && pnpm dev

# MCP Inspector
cd packages/mcp-server && pnpm inspect

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요. 중요한 변경 사항이 있는 경우, 먼저 이슈를 열어 변경 사항을 논의해 주세요.

저장소를 포크하세요
기능 브랜치를 생성합니다( git checkout -b username/feature-name )
변경 사항을 커밋합니다( git commit -m 'Add some feature' )
브랜치에 푸시( git push origin username/feature-name )
풀 리퀘스트 열기

로컬에서 개발 및 디버깅에 대해 알아야 할 사항

시스템에 설치된 환경 대신 dev 환경에서 gbox를 실행하는 방법

gbox cleanup 실행하여 설치된 gbox를 중지하세요. 그러면 API 서버가 중지되어 개발자 환경에서 API 서버를 실행할 수 있습니다.
프로젝트 루트에서 make api-dev 실행합니다.
./gbox box list 실행합니다. 이는 개발 환경에서 실행되는 명령입니다.

Dev env에서 Claude Desktop과 같은 MCP 클라이언트를 MCP 서버에 연결하는 방법

프로젝트 루트에서 make mcp-dev 실행합니다.
./gbox mcp export --merge-to claude 실행합니다.

MCP 검사를 여는 방법

프로젝트 루트에서 make mcp-inspect 실행합니다.
터미널에서 반환된 링크를 클릭하세요.

개발 환경에서 이미지를 빌드하고 사용하는 방법

프로젝트 루트에서 make build-image-python 실행하여 Python 이미지를 빌드하거나, make build-images 모든 이미지를 빌드합니다.
필요에 따라 이미지 이름을 변경합니다(예: TypeScript 이미지의 경우 make build-image-typescript ).
새 이미지를 적용하려면 현재 샌드박스를 삭제해야 할 수도 있습니다 ./gbox box delete --all

MCP 클라이언트가 여전히 이전 MCP 콘텐츠를 받는 이유는 무엇입니까?

도구 정의와 같은 MCP 구성을 변경한 후에는 make build 실행하여 dist/index.js 파일을 업데이트해야 합니다.
./gbox mcp export --merge-to claude 실행해야 할 수도 있습니다.

특허

이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

gbox

Integrations

지박스

특징