CodeRunner: Un entorno aislado local para tus agentes de IA

CodeRunner te ayuda a aislar tus agentes de IA y sus acciones dentro de un entorno aislado.

Caso de uso clave: Puedes ejecutar múltiples Claude Code o agentes de IA en nuestro entorno aislado sin temor a pérdida de datos o exfiltración.

Inicio rápido

Requisitos previos: Mac con macOS y 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

Detener y reanudar

Detén el entorno aislado cuando hayas terminado:

container stop coderunner

Reanuda el mismo entorno aislado más tarde, conservando las subidas, los kernels y los paquetes instalados:

container start coderunner

Para empezar de nuevo con un entorno aislado limpio, elimina el contenedor y ejecuta el instalador de nuevo:

container delete coderunner && ./install.sh

Ejecutar Claude Code dentro de un entorno aislado

./install.sh (si no se ha hecho ya)

container exec -it coderunner /bin/bash

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

Otras opciones de integración

El servidor MCP estará disponible en: http://coderunner.local:8222/mcp

Instalar paquetes necesarios (usa virtualenv y anota la ruta de Python):

pip install -r examples/requirements.txt

1. Integración con Claude Desktop

2. Claude Code CLI

# 1. Instalar e iniciar CodeRunner (configuración única)
git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

# 2. Instalar el plugin de Claude Code
claude plugin marketplace add https://github.com/instavm/coderunner-plugin
claude plugin install instavm-coderunner

# 3. Reconectar a los servidores MCP
/mcp

3. Configuración de OpenCode

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

4. Agentes Python de OpenAI

5. Gemini-CLI

Gemini CLI fue lanzado recientemente por Google.

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

6. Kiro de Amazon

Kiro fue lanzado recientemente por Amazon.

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

7. Coderunner-UI (Entorno de trabajo AI sin conexión)

Coderunner-UI es nuestra propia herramienta de entorno de trabajo AI sin conexión diseñada para privacidad total y procesamiento local.

Seguridad

El código se ejecuta en un contenedor aislado con aislamiento a nivel de máquina virtual. Tu sistema anfitrión y los archivos fuera del entorno aislado permanecen protegidos.

De @apple/container:

Cada contenedor tiene las propiedades de aislamiento de una máquina virtual completa, utilizando un conjunto mínimo de utilidades centrales y bibliotecas dinámicas para reducir la utilización de recursos y la superficie de ataque.

Sistema de Habilidades

CodeRunner incluye un sistema de habilidades integrado que proporciona herramientas preempaquetadas para tareas comunes. Las habilidades se organizan en dos categorías:

Habilidades Públicas Integradas

Las siguientes habilidades están incluidas en cada instalación de CodeRunner:

• pdf-text-replace - Reemplazar texto en formularios PDF rellenables
• image-crop-rotate - Recortar y rotar imágenes

Uso de Habilidades

Las habilidades se acceden a través de las herramientas MCP:

# Listar todas las habilidades disponibles
resultado = await list_skills()

# Obtener documentación para una habilidad específica
info = await get_skill_info("pdf-text-replace")

# Ejecutar el script de una habilidad
codigo = """
import subprocess
subprocess.run([
    'python',
    '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py',
    '/app/uploads/input.pdf',
    'TEXTO ANTIGUO',
    'TEXTO NUEVO',
    '/app/uploads/output.pdf'
])
"""
resultado = await execute_python_code(codigo)

Agregar Habilidades Personalizadas

Los usuarios pueden agregar sus propias habilidades al directorio ~/.coderunner/assets/skills/user/:

1. Crea un directorio para tu habilidad (ej. mi-habilidad-personalizada/)
2. Agrega un archivo SKILL.md con documentación
3. Agrega tus scripts en un subdirectorio scripts/
4. Las habilidades serán descubiertas automáticamente por la herramienta list_skills()

Estructura de la habilidad:

~/.coderunner/assets/skills/user/mi-habilidad-personalizada/
├── SKILL.md              # Documentación con ejemplos de uso
└── scripts/              # Tus scripts Python/bash
    └── process.py

Ejemplo: Usar la Habilidad de Reemplazo de Texto en PDF

# Dentro del contenedor, ejecuta:
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

Arquitectura

CodeRunner consta de:

• Contenedor del Entorno Aislado: Entorno de ejecución aislado con kernel Jupyter
• Servidor MCP: Maneja la comunicación entre los modelos de IA y el entorno aislado
• Sistema de Habilidades: Herramientas preempaquetadas para tareas comunes (manipulación de PDF, procesamiento de imágenes, etc.)

Ejemplos

El directorio examples/ contiene:

• openai-agents - Ejemplo de integración con agentes de OpenAI
• claude-desktop - Ejemplo de integración con Claude Desktop

Tutorial de Construcción de la Imagen del Contenedor

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

Hoja de Ruta

1. Soporte para Linux con Firecracker
2. Barreras de protección para acciones agentes externas
3. CLI para Coderunner

Contribuciones

¡Aceptamos contribuciones! Consulta CONTRIBUTING.md para las pautas.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0 - consulta el archivo LICENSE para más detalles.