Cómo ejecutar un navegador, terminal y VSCode en un solo sandbox para LLMs
Cuando armé por primera vez un stack para un agente de IA autónomo, todo se convirtió rápidamente en una pesadilla de una docena de servicios diferentes. El navegador se ejecutaba en un contenedor aislado, el intérprete de Python en otro, y los archivos tenían que transportarse entre ellos a través de S3 o montajes de volúmenes improvisados. Como resultado, el agente descargaba un PDF en el navegador pero no podía abrirlo en una sesión bash porque los sistemas de archivos estaban aislados entre sí.
El equipo de agent-infra adoptó un enfoque pragmático. Crearon el proyecto AIO Sandbox (All-in-One Agent Sandbox Environment), empaquetando toda la infraestructura que necesita un agente en un único contenedor Docker con un disco compartido.
Qué hay dentro de la caja
El concepto del proyecto es directo: proporcionar a los LLMs acceso a todas las herramientas esenciales para desarrolladores mientras se mantiene todo aislado del sistema host. Dentro de una sola imagen, obtienes:
- Chromium headless con soporte del protocolo CDP y acceso remoto a través de VNC directamente en el navegador
- VSCode Server (code-server) y Jupyter Notebook interactivo para la ejecución de código
- Terminal WebSocket para ejecutar comandos bash
- Servidores MCP integrados (Model Context Protocol) para integración directa con Claude, Cursor o agentes personalizados
- Proxy para previsualizar puertos y aplicaciones web
La principal ventaja de esta configuración es el sistema de archivos unificado. Si un agente guarda una captura de pantalla o descarga un CSV en el directorio home a través de Playwright, puede leer inmediatamente ese archivo con un script bash, procesarlo en Jupyter y abrir el resultado en el editor de código. No se requiere sincronización compleja ni sobrecarga de red.
Inicio rápido
Puedes iniciar el contenedor localmente con un solo comando:
docker run --security-opt seccomp=unconfined --rm -it \
-e SANDBOX_API_KEY=your-secret-key \
-p 127.0.0.1:8080:8080 ghcr.io/agent-infra/sandbox:latest
Una vez en ejecución, el puerto 8080 proporciona acceso a un conjunto completo de herramientas:
- Documentación de la API:
http://localhost:8080/v1/docs - Streaming del escritorio del navegador a través de VNC:
http://localhost:8080/vnc/index.html?autoconnect=true - Versión web del editor VSCode:
http://localhost:8080/code-server/ - Endpoints MCP:
http://localhost:8080/mcp
Si necesitas desplegar el entorno en producción, el repositorio incluye manifiestos listos para usar para Docker Compose y Kubernetes. Al desplegar en la nube, el puerto 8080 debe ocultarse detrás de un proxy inverso con autenticación, ya que el agente ejecuta código arbitrario dentro del contenedor.
Cómo trabajar con el sandbox a través de código
Los autores proporcionan SDKs oficiales para Python, TypeScript y Go. Trabajar con la API es sencillo.
Instalación del paquete de Python:
pip install agent-sandbox
Operaciones básicas de shell y archivos:
from agent_sandbox import Sandbox
client = Sandbox(base_url="http://localhost:8080")
home_dir = client.sandbox.get_context().home_dir
# Выполняем bash команду
result = client.shell.exec_command(command="ls -la")
print(result.data.output)
# Читаем конфигурационный файл
content = client.file.read_file(file=f"{home_dir}/.bashrc")
print(content.data.content)
# Делаем снимок экрана в браузере
screenshot = client.browser.screenshot()
El SDK de TypeScript tiene firmas casi idénticas:
import { Sandbox } from '@agent-infra/sandbox';
const sandbox = new Sandbox({ baseURL: 'http://localhost:8080' });
const result = await sandbox.shell.exec({ command: 'ls -la' });
console.log(result.output);
const content = await sandbox.file.read({ path: '/home/gem/.bashrc' });
console.log(content);
Escenario completo: de página web a informe en Markdown
Aquí tienes un ejemplo que demuestra cómo los componentes trabajan juntos. El script se conecta al navegador del sandbox a través del Chrome DevTools Protocol, carga una página, toma una captura de pantalla, y luego pasa el HTML al kernel de Jupyter para la conversión y guarda el archivo final.
import asyncio
import base64
from playwright.async_api import async_playwright
from agent_sandbox import Sandbox
async def site_to_markdown():
c = Sandbox(base_url="http://localhost:8080")
home_dir = c.sandbox.get_context().home_dir
# 1. Браузер: заходим на сайт и забираем разметку
async with async_playwright() as p:
browser_info = c.browser.get_info().data
page = await (await p.chromium.connect_over_cdp(browser_info.cdp_url)).new_page()
await page.goto("https://example.com", wait_until="networkidle")
html = await page.content()
screenshot_b64 = base64.b64encode(await page.screenshot()).decode('utf-8')
# 2. Jupyter: выполняем скрипт конвертации внутри песочницы
c.jupyter.execute_code(code=f"""
from markdownify import markdownify
html = '''{html}'''
screenshot_b64 = "{screenshot_b64}"
md = f"{{markdownify(html)}}\\n\\n"
with open('{home_dir}/site.md', 'w') as f:
f.write(md)
print("Done!")
""")
# 3. Shell: проверяем созданные файлы
list_result = c.shell.exec_command(command=f"ls -lh {home_dir}")
print(f"Файлы в песочнице: {list_result.data.output}")
# 4. File API: забираем готовый markdown
return c.file.read_file(file=f"{home_dir}/site.md").data.content
if __name__ == "__main__":
result = asyncio.run(site_to_markdown())
print("Отчет успешно сохранен")
Integración con frameworks existentes
El sandbox puede integrarse fácilmente con bibliotecas populares como LangChain, Browser Use o la API estándar de OpenAI.
Así es como se ve el function calling en OpenAI Chat Completions para ejecutar código Python y Node.js:
import json
from openai import OpenAI
from agent_sandbox import Sandbox
client = OpenAI(api_key="your_api_key")
sandbox = Sandbox(base_url="http://localhost:8080")
def run_code(code, lang="python"):
if lang == "python":
return sandbox.jupyter.execute_code(code=code).data
return sandbox.nodejs.execute_nodejs_code(code=code).data
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Посчитай факториал числа 12 на Python"}],
tools=[
{
"type": "function",
"function": {
"name": "run_code",
"parameters": {
"type": "object",
"properties": {
"code": {"type": "string"},
"lang": {"type": "string"},
},
},
},
}
],
)
if response.choices[0].message.tool_calls:
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)
result = run_code(**args)
print(result['outputs'][0]['text'])
¿Para quién es este proyecto?
Si estás construyendo un asistente de IA que necesita más que una simple respuesta de texto, este proyecto te ahorrará mucho tiempo en la configuración del entorno. Es excelente para web scraping autónomo, análisis de datos, generación y depuración de código, así como pruebas de interfaz de usuario a través de VNC.
Una advertencia obvia: la imagen del contenedor es bastante grande debido a Chromium, Node.js, Python y code-server instalados. Para tareas ligeras donde el agente solo necesita bash, esto puede ser excesivo. Pero si necesitas un stack completo de herramientas con un sistema de archivos compartido, AIO Sandbox parece una de las soluciones más cuidadosamente diseñadas en GitHub.
Proyectos relacionados