
AI 에이전트용 로컬 샌드박스
CodeRunner는 AI 에이전트와 그 동작을 샌드박스 내부에서 격리(샌드박싱)할 수 있도록 도와줍니다.
주요 사용 사례: 명시적으로 선택한 호스트 마운트와 네트워크 액세스를 갖춘 샌드박스에서 AI 에이전트 코드를 실행합니다. 격리는 위험을 줄여주지만, 모든 데이터 손실이나 유출을 방지하지는 않습니다.
에이전트를 위한 클라우드 관리형 VM으로 InstaVM - AI 에이전트를 위한 즉석 컴퓨터를 출시했습니다.
사전 요구 사항: macOS와 Apple Silicon(M1/M2/M3/M4)이 탑재된 Mac, Python 3.10+
설치 프로그램은 샌드박스 토큰을 ~/.coderunner/api-token에 생성합니다(또는 내보낸
CODERUNNER_API_TOKEN을 저장합니다). 클라이언트는 이를
Authorization: Bearer <token>으로 전송하며, cat ~/.coderunner/api-token으로 출력할 수 있습니다. 오직
GET /health만 공개되며, 토큰이 없거나 취약하면 기본적으로 거부(fail closed)됩니다. Claude
Desktop 프록시와 예제들은 변수가 설정되지 않은 경우 해당 파일에서 토큰을 읽습니다. 인증 및 네트워크 경계를 참조하세요.
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh
작업이 끝나면 샌드박스를 중지하세요:
container stop coderunner
나중에 동일한 샌드박스를 재개하여 파일 시스템을 보존합니다. Python 커널 상태는 휘발성이므로 VM 또는 서버 재시작 후에는 유지되지 않습니다:
container start coderunner
깨끗한 샌드박스로 처음부터 다시 시작하려면 컨테이너를 삭제하고 설치 프로그램을 다시 실행하세요:
container delete coderunner && ./install.sh
CPU 및 메모리 제한은 설치 프로그램 옵션이나 CODERUNNER_CPUS 및 CODERUNNER_MEMORY 환경 변수로 설정할 수 있습니다:
./install.sh --cpus 4 --memory 8g
/workspace 아래에 추가 호스트 디렉터리를 마운트해야 합니다. 기본적으로 읽기 전용이며, 샌드박스가 호스트에 쓰기를 해야 하는 경우에만 :rw를 추가하세요:
./install.sh \
--mount "$HOME/projects/api:/workspace/api" \
--mount "$HOME/projects/output:/workspace/output:rw"
추가 마운트는 기본적으로 없음입니다. 리소스 및 마운트 설정은 컨테이너가 생성될 때 고정되므로, 변경하려면 컨테이너를 삭제한 후 다시 생성해야 합니다.
기본적으로 샌드박스에서 실행되는 코드는 제한 없는 네트워크 액세스 권한을 가집니다. 인터넷 액세스가 없는 호스트 전용 네트워크에서 실행하려면:
CODERUNNER_NETWORK=none ./install.sh
이 모드에서는 MCP 서버가 http://127.0.0.1:8222/mcp에서 사용 가능합니다. 이 설정은 컨테이너가 생성될 때 고정되며, 설치 프로그램은 다른 네트워크 모드로 컨테이너를 재개하는 것을 거부합니다.
Claude Code는 권한 프롬프트만을 경계로 하여 사용자 머신에서 사용자 권한으로 명령을 실행합니다. 대신 CodeRunner의 도구를 가리키면 작성한 코드가 VM 내에서 실행됩니다. 즉, 어떤 지시를 받았든 마운트된 /workspace 아래의 폴더, 허용된 네트워크, 그리고 샌드박스 자체의 파일시스템에만 접근할 수 있습니다. 신뢰할 수 없는 입력을 처리하는 코드나 직접 실행하지 않을 코드, 그리고 상태를 공유해서는 안 되는 여러 에이전트(명명된 세션)에는 샌드박스를 사용하십시오. 읽기-쓰기로 마운트한 항목은 보호하지 않습니다.
./install.sh (아직 실행하지 않은 경우)
container exec -it coderunner /bin/bash
root@coderunner:/app# npm install -g @anthropic-ai/claude-code
MCP 서버는 다음 위치에서 사용 가능합니다: http://coderunner.local:8222/mcp
설치 프로그램은 Claude Desktop 프록시를 위해 ~/.coderunner/venv를 생성합니다. 다른 Python 예제의 경우, 자체 virtualenv에 해당 의존성을 설치하십시오:
pip install -r examples/requirements.txt



예제 구성 복사:
cd examples
cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
구성 파일을 편집하고 자리 표시자 경로를 교체하세요:
/path/to/your/python을 $HOME/.coderunner/venv/bin/python으로 교체하되, 홈 디렉터리의 전체 경로를 사용하세요/path/to/coderunner를 클론한 저장소의 실제 경로로 교체하세요편집 후 예시:
{
"mcpServers": {
"coderunner": {
"command": "/Users/yourname/.coderunner/venv/bin/python",
"args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
}
}
}
Claude Desktop 구성 업데이트:
Claude에서 CodeRunner 사용 시작: 이제 Claude가 작성한 코드는 샌드박스에서 실행됩니다.
서버가 실행 중으로 표시되는데도 채팅의 도구 메뉴에서 도구가 "Disabled"로 표시되면: Claude
Desktop을 완전히 종료(Cmd-Q)한 후 다시 열고, command가 설치 프로그램이 출력한 venv python인지(여기에는
fastmcp가 포함됨) 확인한 다음, 프록시의 오류를 확인하려면 ~/Library/Logs/Claude/mcp-server-coderunner.log를 읽으십시오. 프록시는
샌드박스가 실행 중이어야 하며(container list) 토큰 파일 ~/.coderunner/api-token이 필요합니다.
빠른 시작:
# 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
git clone https://github.com/instavm/coderunner.git
cd coderunner
./install.sh
# 2. Add the sandbox with its token (the installer prints this command)
claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
--header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
# 3. Reconnect to MCP servers
/mcp
Claude Code 플러그인(claude plugin marketplace add https://github.com/instavm/coderunner-plugin)은 토큰보다 먼저 만들어졌기 때문에 동일한 헤더를 전송할 때까지 401 오류가 발생합니다. 플러그인이 업데이트될 때까지는 위 명령을 사용하세요.
설치 단계:
플러그인 마켓플레이스로 이동:

InstaVM 저장소 추가:

Claude Code로 Python 코드 실행:

이게 전부입니다! 이제 Claude Code에서 모든 CodeRunner 도구를 사용할 수 있습니다:
에이전트 간에 상태를 격리된 상태로 유지하려면 반환된 session_id를 execute_python_code에 전달하세요. 최대 5개의 이름 지정 세션을 동시에 실행할 수 있습니다.
자세히 알아보기: 자세한 문서는 플러그인 저장소를 참조하세요.

~/.config/opencode/opencode.json을 생성하거나 편집하세요:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"coderunner": {
"type": "remote",
"url": "http://coderunner.local:8222/mcp",
"headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" },
"enabled": true
}
}
}
구성을 저장한 후:

OpenAI API 키를 설정합니다:
export OPENAI_API_KEY="your-openai-api-key-here"
클라이언트 실행:
python examples/openai_agents/openai_client.py