Hoe een Browser, Terminal en VSCode in Één Sandbox voor LLMs uit te voeren
Toen ik voor het eerst een stack samenstelde voor een autonoom AI-agent, veranderde alles al snel in een nachtmerrie van een dozijn verschillende services. De browser draaide in één geïsoleerde container, de Python-interpreter in een andere, en bestanden moesten ertussen worden overgezet via S3 of gehackte volume-mounts. Als gevolg daarvan kon de agent een PDF downloaden in de browser, maar kon deze niet openen in een bash-sessie omdat de bestandssystemen van elkaar geïsoleerd waren.
De mensen van agent-infra kozen een pragmatische aanpak. Ze bouwden het AIO Sandbox-project (All-in-One Agent Sandbox Environment), dat alle infrastructuur die een agent nodig heeft in één Docker-container met een gedeelde schijf verpakt.
Wat zit er in de doos
Het concept van het project is eenvoudig: geef LLMs toegang tot alle essentiële ontwikkelaarstools terwijl alles geïsoleerd blijft van het hostsysteem. Binnen één image krijg je:
- Headless Chromium met CDP-protocolondersteuning en externe toegang via VNC direct in de browser
- VSCode Server (code-server) en interactieve Jupyter Notebook voor code-uitvoering
- WebSocket-terminal voor het uitvoeren van bash-commando's
- Ingebouwde MCP-servers (Model Context Protocol) voor directe integratie met Claude, Cursor of aangepaste agents
- Proxy voor het bekijken van poorten en webapplicaties
Het belangrijkste voordeel van deze opzet is het uniforme bestandssysteem. Als een agent een screenshot maakt of een CSV downloadt naar de thuismap via Playwright, kan deze dat bestand onmiddellijk lezen met een bash-script, het verwerken in Jupyter en het resultaat openen in de code-editor. Geen complexe synchronisatie of netwerkoverhead nodig.
Snelle start
Je kunt de container lokaal opstarten met één commando:
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
Zodra deze draait, biedt poort 8080 toegang tot een complete toolsuite:
- API-documentatie:
http://localhost:8080/v1/docs - Browser desktop streaming via VNC:
http://localhost:8080/vnc/index.html?autoconnect=true - Webversie van VSCode-editor:
http://localhost:8080/code-server/ - MCP-eindpunten:
http://localhost:8080/mcp
Als je de omgeving naar productie moet uitrollen, bevat de repository kant-en-klare manifests voor Docker Compose en Kubernetes. Bij uitrol naar de cloud moet poort 8080 verborgen worden achter een reverse proxy met authenticatie, aangezien de agent willekeurige code uitvoert binnen de container.
Hoe te werken met de Sandbox via Code
De auteurs bieden officiële SDK's voor Python, TypeScript en Go. Werken met de API is eenvoudig.
Het Python-pakket installeren:
pip install agent-sandbox
Basis shell- en bestandsoperaties:
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()
De TypeScript SDK heeft vrijwel identieke signatures:
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);
End-to-end scenario: Van webpagina naar Markdown-rapport
Hier is een voorbeeld dat demonstreert hoe de componenten samenwerken. Het script maakt verbinding met de sandbox-browser via Chrome DevTools Protocol, laadt een pagina, maakt een screenshot, en geeft vervolgens de HTML door aan de Jupyter-kernel voor conversie en slaat het uiteindelijke bestand op.
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("Отчет успешно сохранен")
Integratie met kant-en-klare frameworks
De sandbox kan eenvoudig worden geïntegreerd met populaire bibliotheken zoals LangChain, Browser Use of de standaard OpenAI API.
Zo ziet functie-aanroeping in OpenAI Chat Completies eruit voor het uitvoeren van Python en Node.js-code:
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'])
Voor wie is dit project
Als je een AI-assistent bouwt die meer nodig heeft dan een eenvoudige tekstreactie, zal dit project je veel tijd besparen op omgevingsconfiguratie. Het blinkt uit in autonoom webscrapen, data-analyse, codegeneratie en debugging, evenals UI-testen via VNC.
Een voor de hand liggende kanttekening: de container-image is vrij groot vanwege de geïnstalleerde Chromium, Node.js, Python en code-server. Voor lichte taken waarbij de agent alleen bash nodig heeft, kan dit overkill zijn. Maar als je een complete toolstack met een gedeeld bestandssysteem nodig hebt, ziet AIO Sandbox eruit als een van de meest doordachte oplossingen op GitHub.
Gerelateerde projecten