CodeRunner: Um sandbox local para seus agentes de IA

CodeRunner ajuda você a isolar seus agentes de IA e suas ações dentro de um sandbox.

Caso de uso principal: Você pode executar vários Claude Code ou agentes de IA em nosso sandbox sem medo de perda de dados e exfiltração.

Início Rápido

Pré-requisitos: Mac com macOS e Apple Silicon (M1/M2/M3/M4), Python 3.10+

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

Parar e retomar

Pare o sandbox quando terminar:

container stop coderunner

Retome o mesmo sandbox mais tarde, preservando uploads, kernels e pacotes instalados:

container start coderunner

Para recomeçar com um sandbox limpo, exclua o contêiner e execute o instalador novamente:

container delete coderunner && ./install.sh

Executar Claude Code dentro de um Sandbox

./install.sh (se ainda não tiver feito)

container exec -it coderunner /bin/bash

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

Outras Opções de Integração

O servidor MCP estará disponível em: http://coderunner.local:8222/mcp

Instale os pacotes necessários (use virtualenv e anote o caminho do python):

pip install -r examples/requirements.txt

1. Integração com Claude Desktop

2. Claude Code CLI

# 1. Instale e inicie o CodeRunner (configuração única)
git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

# 2. Instale o plugin do Claude Code
claude plugin marketplace add https://github.com/instavm/coderunner-plugin
claude plugin install instavm-coderunner

# 3. Reconecte aos servidores MCP
/mcp

3. Configuração do OpenCode

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

4. Agentes Python da OpenAI

5. Gemini-CLI

Gemini CLI foi lançado recentemente pelo Google.

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

6. Kiro da Amazon

Kiro foi lançado recentemente pela Amazon.

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

7. Coderunner-UI (Ambiente de Trabalho de IA Offline)

Coderunner-UI é nossa própria ferramenta de ambiente de trabalho de IA offline, projetada para privacidade total e processamento local.

Segurança

O código é executado em um contêiner isolado com isolamento no nível de VM. Seu sistema host e arquivos fora do sandbox permanecem protegidos.

De @apple/container:

Cada contêiner tem as propriedades de isolamento de uma VM completa, usando um conjunto mínimo de utilitários principais e bibliotecas dinâmicas para reduzir a utilização de recursos e a superfície de ataque.

Sistema de Habilidades

O CodeRunner inclui um sistema de habilidades integrado que fornece ferramentas pré-empacotadas para tarefas comuns. As habilidades são organizadas em duas categorias:

Habilidades Públicas Integradas

As seguintes habilidades estão incluídas em toda instalação do CodeRunner:

• pdf-text-replace - Substituir texto em formulários PDF preenchíveis
• image-crop-rotate - Cortar e girar imagens

Usando Habilidades

As habilidades são acessadas através de ferramentas MCP:

# Listar todas as habilidades disponíveis
result = await list_skills()

# Obter documentação para uma habilidade específica
info = await get_skill_info("pdf-text-replace")

# Executar o script de uma habilidade
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)

Adicionando Habilidades Personalizadas

Os usuários podem adicionar suas próprias habilidades no diretório ~/.coderunner/assets/skills/user/:

1. Crie um diretório para sua habilidade (por exemplo, my-custom-skill/)
2. Adicione um arquivo SKILL.md com documentação
3. Adicione seus scripts em um subdiretório scripts/
4. As habilidades serão descobertas automaticamente pela ferramenta list_skills()

Estrutura da Habilidade:

~/.coderunner/assets/skills/user/my-custom-skill/
├── SKILL.md              # Documentação com exemplos de uso
└── scripts/              # Seus scripts Python/bash
    └── process.py

Exemplo: Usando a Habilidade de Substituir Texto em PDF

# Dentro do contêiner, execute:
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

Arquitetura

O CodeRunner consiste em:

• Contêiner Sandbox: Ambiente de execução isolado com kernel Jupyter
• Servidor MCP: Lida com a comunicação entre modelos de IA e o sandbox
• Sistema de Habilidades: Ferramentas pré-empacotadas para tarefas comuns (manipulação de PDF, processamento de imagem, etc.)

Exemplos

O diretório examples/ contém:

• openai-agents - Exemplo de integração com agentes OpenAI
• claude-desktop - Exemplo de integração com Claude Desktop

Tutorial de Criação de Imagem de Contêiner

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

Roteiro

1. Suporte a Linux com Firecracker
2. Proteções para ações agentivas externas
3. CLI para Coderunner

Contribuindo

Aceitamos contribuições! Consulte CONTRIBUTING.md para obter as diretrizes.

Licença

Este projeto está licenciado sob a Licença Apache 2.0 - consulte o arquivo LICENSE para obter detalhes.