Jak uruchomić przeglądarkę, terminal i VSCode w jednej piaskownicy dla LLM-ów
Kiedy po raz pierwszy złożyłem stos dla autonomicznego agenta AI, wszystko szybko zamieniło się w koszmar z tuzinem różnych usług. Przeglądarka działała w jednym izolowanym kontenerze, interpreter Pythona w innym, a pliki musiały być przesyłane między nimi przez S3 lub nieeleganckie montowania woluminów. W rezultacie agent pobierał PDF w przeglądarce, ale nie mógł go otworzyć w sesji bash, ponieważ systemy plików były od siebie odizolowane.
Ludzie z agent-infra przyjęli pragmatyczne podejście. Stworzyli projekt AIO Sandbox (All-in-One Agent Sandbox Environment), pakując całą infrastrukturę potrzebną agentowi do jednego kontenera Docker z wspólnym dyskiem.
Co kryje się w środku
Koncept projektu jest prosty: zapewnić LLM-om dostęp do wszystkich niezbędnych narzędzi deweloperskich, jednocześnie izolując wszystko od systemu hosta. W ramach jednego obrazu otrzymujesz:
- Headless Chromium z obsługą protokołu CDP i zdalnym dostępem przez VNC bezpośrednio w przeglądarce
- VSCode Server (code-server) oraz interaktywny Jupyter Notebook do wykonywania kodu
- Terminal WebSocket do uruchamiania poleceń bash
- Wbudowane serwery MCP (Model Context Protocol) do bezpośredniej integracji z Claude, Cursor lub niestandardowymi agentami
- Proxy do podglądu portów i aplikacji webowych
Główną zaletą tego rozwiązania jest ujednolicony system plików. Jeśli agent zapisze zrzut ekranu lub pobierze plik CSV do katalogu domowego przez Playwright, może natychmiast odczytać ten plik skryptem bash, przetworzyć go w Jupyter i otworzyć wynik w edytorze kodu. Bez skomplikowanej synchronizacji czy narzutu sieciowego.
Szybki start
Kontener można uruchomić lokalnie jednym poleceniem:
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
Po uruchomieniu port 8080 zapewnia dostęp do pełnego zestawu narzędzi:
- Dokumentacja API:
http://localhost:8080/v1/docs - Strumieniowanie pulpitu przeglądarki przez VNC:
http://localhost:8080/vnc/index.html?autoconnect=true - Webowa wersja edytora VSCode:
http://localhost:8080/code-server/ - Endpointy MCP:
http://localhost:8080/mcp
Jeśli potrzebujesz wdrożyć środowisko do produkcji, repozytorium zawiera gotowe manifesty dla Docker Compose i Kubernetes. Przy wdrażaniu w chmurze port 8080 powinien być ukryty za reverse proxy z uwierzytelnianiem, ponieważ agent wykonuje dowolny kod wewnątrz kontenera.
Jak pracować z piaskownicą przez kod
Autorzy udostępniają oficjalne SDK dla Pythona, TypeScript i Go. Praca z API jest prosta.
Instalacja pakietu Pythona:
pip install agent-sandbox
Podstawowe operacje na powłoce i plikach:
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()
SDK TypeScript ma niemal identyczne sygnatury:
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);
Scenariusz end-to-end: od strony webowej do raportu w Markdown
Oto przykład demonstrujący, jak komponenty współpracują ze sobą. Skrypt łączy się z przeglądarką piaskownicy przez Chrome DevTools Protocol, ładuje stronę, robi zrzut ekranu, a następnie przekazuje HTML do jądra Jupyter w celu konwersji i zapisuje wynik.
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("Отчет успешно сохранен")
Integracja z gotowymi frameworkami
Piaskownicę można łatwo zintegrować z popularnymi bibliotekami jak LangChain, Browser Use czy standardowym API OpenAI.
Oto jak wygląda wywoływanie funkcji w OpenAI Chat Completions do wykonywania kodu Python i 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'])
Dla kogo jest ten projekt
Jeśli budujesz asystenta AI, który potrzebuje czegoś więcej niż prostej odpowiedzi tekstowej, ten projekt zaoszczędzi Ci mnóstwo czasu na konfigurację środowiska. Sprawdza się świetnie przy autonomiczny scrapowaniu stron, analizie danych, generowaniu i debugowaniu kodu, a także testowaniu UI przez VNC.
Jedno oczywiste zastrzeżenie: obraz kontenera jest dość duży ze względu na zainstalowane Chromium, Node.js, Pythona i code-server. Przy lekkich zadaniach, gdzie agent potrzebuje tylko basha, może to być przesada. Ale jeśli potrzebujesz pełnego zestawu narzędzi z wspólnym systemem plików, AIO Sandbox wygląda na jedno z najbardziej przemyślanych rozwiązań na GitHubie.
Powiązane projekty