Comment exécuter un navigateur, un terminal et VSCode dans un seul bac à sable pour les LLMs
Lorsque j'ai assemblé une pile pour un agent IA autonome, tout s'est rapidement transformé en cauchemar avec une douzaine de services différents. Le navigateur fonctionnait dans un conteneur isolé, l'interpréteur Python dans un autre, et les fichiers devaient être déplacés entre eux via S3 ou des montages de volumes improvisés. En conséquence, l'agent pouvait télécharger un PDF dans le navigateur mais ne pouvait pas l'ouvrir dans une session bash car les systèmes de fichiers étaient isolés les uns des autres.
Les équipes d'agent-infra ont adopté une approche pragmatique. Elles ont créé le projet AIO Sandbox (All-in-One Agent Sandbox Environment), regroupant toute l'infrastructure nécessaire à un agent dans un seul conteneur Docker avec un disque partagé.
Qu'y a-t-il dans la boîte
Le concept du projet est simple : donner aux LLMs accès à tous les outils essentiels pour les développeurs tout en maintenant l'isolation par rapport au système hôte. Dans une seule image, vous obtenez :
- Chromium headless avec support du protocole CDP et accès distant via VNC directement dans le navigateur
- VSCode Server (code-server) et Jupyter Notebook interactif pour l'exécution de code
- Terminal WebSocket pour exécuter des commandes bash
- Serveurs MCP intégrés (Model Context Protocol) pour une intégration directe avec Claude, Cursor ou des agents personnalisés
- Proxy pour prévisualiser les ports et les applications web
L'avantage principal de cette configuration est le système de fichiers unifié. Si un agent enregistre une capture d'écran ou télécharge un CSV dans le répertoire personnel via Playwright, il peut immédiatement lire ce fichier avec un script bash, le traiter dans Jupyter, et ouvrir le résultat dans l'éditeur de code. Aucune synchronisation complexe ni surcharge réseau nécessaire.
Démarrage rapide
Vous pouvez démarrer le conteneur localement avec une seule commande :
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
Une fois en cours d'exécution, le port 8080 donne accès à une suite d'outils complète :
- Documentation de l'API :
http://localhost:8080/v1/docs - Streaming du bureau via VNC :
http://localhost:8080/vnc/index.html?autoconnect=true - Version web de l'éditeur VSCode :
http://localhost:8080/code-server/ - Points de terminaison MCP :
http://localhost:8080/mcp
Si vous devez déployer l'environnement en production, le dépôt inclut des manifests prêts à l'emploi pour Docker Compose et Kubernetes. Lors du déploiement dans le cloud, le port 8080 doit être masqué derrière un proxy inverse avec authentification car l'agent exécute du code arbitraire à l'intérieur du conteneur.
Comment travailler avec le bac à sable via du code
Les auteurs fournissent des SDK officiels pour Python, TypeScript et Go. Travailler avec l'API est simple.
Installation du package Python :
pip install agent-sandbox
Opérations de base sur les fichiers et le shell :
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()
Le SDK TypeScript a des signatures presque identiques :
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);
Scénario de bout en bout : De la page web au rapport Markdown
Voici un exemple démontrant comment les composants fonctionnent ensemble. Le script se connecte au navigateur du bac à sable via le Chrome DevTools Protocol, charge une page, prend une capture d'écran, puis passe le HTML au noyau Jupyter pour conversion et enregistre le fichier 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("Отчет успешно сохранен")
Intégration avec les frameworks existants
Le bac à sable peut être facilement intégré avec des bibliothèques populaires comme LangChain, Browser Use ou l'API OpenAI standard.
Voici à quoi ressemble l'appel de fonction dans OpenAI Chat Completions pour l'exécution de code Python et 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'])
Pour qui est ce projet
Si vous construisez un assistant IA qui a besoin de plus qu'une simple réponse textuelle, ce projet vous fera gagner beaucoup de temps sur la configuration de l'environnement. Il excelle dans le scraping web autonome, l'analyse de données, la génération et le débogage de code, ainsi que les tests d'interface via VNC.
Une mise en garde évidente : l'image du conteneur est assez volumineuse en raison de Chromium, Node.js, Python et code-server installés. Pour des tâches légères où l'agent n'a besoin que de bash, cela peut être excessif. Mais si vous avez besoin d'une pile d'outils complète avec un système de fichiers partagé, AIO Sandbox semble être l'une des solutions les mieux pensées sur GitHub.
Projets similaires