Come Eseguire un Browser, Terminale e VSCode in un Singolo Sandbox per LLM
Quando ho assemblato per la prima volta uno stack per un agente AI autonomo, tutto si è rapidamente trasformato in un incubo fatto di una dozzina di servizi diversi. Il browser girava in un container isolato, l'interprete Python in un altro, e i file dovevano essere trasferiti tra loro tramite S3 o mount di volumi improvvisati. Di conseguenza, l'agente poteva scaricare un PDF nel browser ma non poteva aprirlo in una sessione bash perché i filesystem erano isolati tra loro.
Il team di agent-infra ha adottato un approccio pragmatico. Hanno creato il progetto AIO Sandbox (All-in-One Agent Sandbox Environment), raggruppando tutta l'infrastruttura necessaria per un agente in un singolo container Docker con disco condiviso.
Cosa C'è all'Interno della Scatola
Il concetto del progetto è semplice: fornire agli LLM accesso a tutti gli strumenti essenziali per sviluppatori mantenendo tutto isolato dal sistema host. All'interno di una singola immagine, ottieni:
- Chromium headless con supporto al protocollo CDP e accesso remoto tramite VNC direttamente nel browser
- VSCode Server (code-server) e Jupyter Notebook interattivo per l'esecuzione del codice
- Terminale WebSocket per l'esecuzione di comandi bash
- Server MCP (Model Context Protocol) integrati per l'integrazione diretta con Claude, Cursor o agenti personalizzati
- Proxy per il preview di porte e applicazioni web
Il vantaggio principale di questa configurazione è il filesystem unificato. Se un agente salva uno screenshot o scarica un CSV nella home directory tramite Playwright, può immediatamente leggere quel file con uno script bash, elaborarlo in Jupyter e aprire il risultato nell'editor di codice. Nessuna sincronizzazione complessa o overhead di rete richiesto.
Avvio Rapido
Puoi avviare il container localmente con un singolo 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 volta in esecuzione, la porta 8080 fornisce accesso a una suite completa di strumenti:
- Documentazione API:
http://localhost:8080/v1/docs - Streaming del desktop del browser tramite VNC:
http://localhost:8080/vnc/index.html?autoconnect=true - Versione web dell'editor VSCode:
http://localhost:8080/code-server/ - Endpoint MCP:
http://localhost:8080/mcp
Se hai bisogno di distribuire l'ambiente in produzione, il repository include manifest pronti per Docker Compose e Kubernetes. Quando distribuisci sul cloud, la porta 8080 dovrebbe essere nascosta dietro un reverse proxy con autenticazione dato che l'agente esegue codice arbitrario all'interno del container.
Come Lavorare con il Sandbox tramite Codice
Gli autori forniscono SDK ufficiali per Python, TypeScript e Go. Lavorare con l'API è immediato.
Installazione del pacchetto Python:
pip install agent-sandbox
Operazioni base su shell e file:
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()
L'SDK TypeScript ha firme quasi identiche:
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);
Scenario End-to-End: dalla Pagina Web al Report Markdown
Ecco un esempio che dimostra come i componenti funzionano insieme. Lo script si connette al browser del sandbox tramite Chrome DevTools Protocol, carica una pagina, acquisisce uno screenshot, poi passa l'HTML al kernel Jupyter per la conversione e salva il file finale.
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("Отчет успешно сохранен")
Integrazione con Framework Pronti all'Uso
Il sandbox può essere facilmente integrato con librerie popolari come LangChain, Browser Use o l'API OpenAI standard.
Ecco come appare il function calling in OpenAI Chat Completions per l'esecuzione di codice Python e 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'])
Per Chi È Questo Progetto
Se stai costruendo un assistente AI che ha bisogno di più di una semplice risposta testuale, questo progetto ti farà risparmiare un sacco di tempo sulla configurazione dell'ambiente. È ottimo per web scraping autonomo, analisi dei dati, generazione e debug del codice, così come test dell'interfaccia utente tramite VNC.
Un caveat ovvio: l'immagine del container è piuttosto grande a causa di Chromium, Node.js, Python e code-server installati. Per attività leggere dove l'agente ha solo bisogno di bash, questo potrebbe essere eccessivo. Ma se hai bisogno di uno stack completo di strumenti con filesystem condiviso, AIO Sandbox sembra una delle soluzioni più ben pensate su GitHub.
Progetti correlati