CodeRunner: AI 에이전트를 위한 로컬 샌드박스

CodeRunner는 AI 에이전트와 그 동작을 샌드박스 내에서 격리할 수 있도록 도와줍니다.

주요 사용 사례: 여러 Claude Code 또는 AI 에이전트를 데이터 손실 및 유출에 대한 걱정 없이 샌드박스에서 실행할 수 있습니다.

빠른 시작

사전 요구 사항: macOS와 Apple Silicon(M1/M2/M3/M4)이 탑재된 Mac, Python 3.10+

git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh

중지 및 재개

작업이 끝나면 샌드박스를 중지합니다:

container stop coderunner

업로드, 커널, 설치된 패키지를 유지한 상태로 나중에 동일한 샌드박스를 재개합니다:

container start coderunner

깨끗한 샌드박스로 다시 시작하려면 컨테이너를 삭제하고 설치 프로그램을 다시 실행하세요:

container delete coderunner && ./install.sh

샌드박스 내에서 Claude Code 실행

./install.sh (아직 실행하지 않은 경우)

container exec -it coderunner /bin/bash

root@coderunner:/app# npm install -g @anthropic-ai/claude-code

기타 통합 옵션

MCP 서버는 다음 주소에서 사용할 수 있습니다: http://coderunner.local:8222/mcp

필수 패키지 설치 (가상 환경을 사용하고 Python 경로를 기록해두세요):

pip install -r examples/requirements.txt

1. Claude Desktop 통합

Claude Desktop이 CodeRunner를 MCP 서버로 사용하도록 구성:

demo1

demo2

demo4

예제 구성 파일 복사:

cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json

구성 파일 편집 후 플레이스홀더 경로를 실제 경로로 바꾸기:
- /path/to/your/python을 실제 Python 경로(예: /usr/bin/python3 또는 /opt/homebrew/bin/python3)로 변경
- /path/to/coderunner를 클론한 저장소의 실제 경로로 변경
편집 후 예시:
```
{
  "mcpServers": {
    "coderunner": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
    }
  }
}
```
Claude Desktop 구성 업데이트:
- Claude Desktop을 엽니다

2. Claude Code CLI

터미널 기반 AI 도우미를 위해 CodeRunner를 Claude Code CLI와 함께 사용:

빠른 시작:

# 1. CodeRunner 설치 및 시작 (일회성 설정)
git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

# 2. Claude Code 플러그인 설치
claude plugin marketplace add https://github.com/instavm/coderunner-plugin
claude plugin install instavm-coderunner

# 3. MCP 서버에 재연결
/mcp

설치 단계:

플러그인 마켓플레이스로 이동:
InstaVM 저장소 추가:
Claude Code로 Python 코드 실행:

이것으로 끝입니다! 이제 Claude Code가 모든 CodeRunner 도구에 접근할 수 있습니다:

execute_python_code - 지속적인 Jupyter 커널에서 Python 코드 실행
navigate_and_get_all_visible_text - Playwright를 사용한 웹 스크래핑
list_skills - 사용 가능한 스킬 나열 (docx, xlsx, pptx, pdf, 이미지 처리 등)
get_skill_info - 특정 스킬에 대한 문서 확인
get_skill_file - 스킬 파일 및 예제 읽기

더 알아보기: 자세한 문서는 플러그인 저장소를 참조하세요.

3. OpenCode 구성

OpenCode가 CodeRunner를 MCP 서버로 사용하도록 구성:

OpenCode 예시

~/.config/opencode/opencode.json 파일을 생성하거나 편집합니다:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coderunner": {
      "type": "remote",
      "url": "http://coderunner.local:8222/mcp",
      "enabled": true
    }
  }
}

구성을 저장한 후:

OpenCode를 다시 시작합니다
CodeRunner 도구가 자동으로 사용 가능해집니다
샌드박스 환경에 대한 전체 접근 권한으로 Python 코드 실행을 시작하세요

4. Python OpenAI Agents

OpenAI의 Python agents 라이브러리와 함께 CodeRunner 사용:

demo3

OpenAI API 키 설정:

export OPENAI_API_KEY="your-openai-api-key-here"

클라이언트 실행:

python examples/openai_agents/openai_client.py

코딩 시작: "100개의 소수를 생성하는 Python 코드 작성"과 같은 프롬프트를 입력하면 샌드박스 내에서 안전하게 실행됩니다!

5. Gemini-CLI

Gemini CLI는 Google에서 최근 출시했습니다.

~/.gemini/settings.json

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "coderunner": {
      "httpUrl": "http://coderunner.local:8222/mcp"
    }
  }
}

gemini1

gemini2

6. Amazon Kiro

Kiro는 Amazon에서 최근 출시했습니다.

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "coderunner": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code"
      ]
    }
  }
}

kiro

7. Coderunner-UI (오프라인 AI 작업 공간)

Coderunner-UI는 완전한 프라이버시와 로컬 처리를 위해 설계된 자체 오프라인 AI 작업 공간 도구입니다.

coderunner-ui

보안

코드는 VM 수준 격리가 적용된 격리된 컨테이너에서 실행됩니다. 호스트 시스템과 샌드박스 외부의 파일은 보호됩니다.

@apple/container에서 발췌:

각 컨테이너는 전체 VM의 격리 속성을 가지며, 리소스 사용량과 공격 표면을 줄이기 위해 최소한의 핵심 유틸리티 및 동적 라이브러리 세트를 사용합니다.

스킬 시스템

CodeRunner는 일반적인 작업을 위한 사전 패키지 도구를 제공하는 내장 스킬 시스템을 포함합니다. 스킬은 두 가지 범주로 구성됩니다:

내장 공개 스킬

모든 CodeRunner 설치에 포함된 스킬:

pdf-text-replace - 채울 수 있는 PDF 양식의 텍스트 바꾸기
image-crop-rotate - 이미지 자르기 및 회전

스킬 사용

스킬은 MCP 도구를 통해 접근합니다:

# 모든 사용 가능한 스킬 나열
result = await list_skills()

# 특정 스킬에 대한 문서 확인
info = await get_skill_info("pdf-text-replace")

# 스킬 스크립트 실행
code = """
import subprocess
subprocess.run([
    'python',
    '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py',
    '/app/uploads/input.pdf',
    'OLD TEXT',
    'NEW TEXT',
    '/app/uploads/output.pdf'
])
"""
result = await execute_python_code(code)

사용자 정의 스킬 추가

사용자는 자신만의 스킬을 ~/.coderunner/assets/skills/user/ 디렉토리에 추가할 수 있습니다:

스킬 디렉토리 생성 (예: my-custom-skill/)
문서를 포함한 SKILL.md 파일 추가
scripts/ 하위 디렉토리에 스크립트 추가
스킬은 list_skills() 도구에 의해 자동으로 발견됩니다

스킬 구조:

~/.coderunner/assets/skills/user/my-custom-skill/
├── SKILL.md              # 사용 예제가 포함된 문서
└── scripts/              # Python/bash 스크립트
    └── process.py

예제: PDF 텍스트 바꾸기 스킬 사용

# 컨테이너 내부에서 실행:
python /app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py \
    /app/uploads/tax_form.pdf \
    "John Doe" \
    "Jane Smith" \
    /app/uploads/tax_form_updated.pdf

아키텍처

CodeRunner는 다음으로 구성됩니다:

샌드박스 컨테이너: Jupyter 커널이 있는 격리된 실행 환경
MCP 서버: AI 모델과 샌드박스 간의 통신 처리
스킬 시스템: 일반적인 작업을 위한 사전 패키지 도구 (PDF 조작, 이미지 처리 등)

예제

examples/ 디렉토리에는 다음이 포함됩니다:

openai-agents - OpenAI agents 통합 예제
claude-desktop - Claude Desktop 통합 예제

컨테이너 이미지 빌드 튜토리얼

https://github.com/apple/container/blob/main/docs/tutorial.md

로드맵

Firecracker를 사용한 Linux 지원
외부 에이전트 동작에 대한 가드레일
Coderunner용 CLI

기여

기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.

라이선스

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

coderunner

인기