TL;DR: AIO Sandbox hợp nhất Browser (VNC), Shell/Terminal, File Ops, VSCode Server, Jupyter, và MCP Hub trong một container Docker duy nhất. Bài viết này phân tích kiến trúc, API, bảo mật, quy trình làm việc (workflows), triển khai thực tế (Docker/Docker Compose/Kubernetes), tối ưu SEO nội dung, cùng ưu/nhược điểm khi ứng dụng vào tác vụ AI Agents (đặc biệt hữu ích cho tự động hoá kiểm thử, R&D agent, và demo nhanh).
1) Tổng quan & giá trị cốt lõi
AIO Sandbox là một môi trường thực thi hợp nhất cho AI Agent, gộp các khả năng then chốt:
- Unified File System: Browser tải file → Shell/VSCode/Jupyter thấy ngay, không cần đồng bộ thủ công.
- Multi-Interfaces: VNC desktop (trình duyệt thật), VSCode Server (IDE trên web), Jupyter, Terminal WebSocket.
- MCP‑Ready: Cổng MCP Hub giúp Agent kết nối/điều khiển Browser, Shell, File, Markdown… theo giao thức chuẩn.
- Zero/Low‑Config: Dựng lên là dùng; phù hợp demo, PoC, workshop, và tích hợp nhanh trong pipelines.
- Isolation‑by‑Container: Bao bọc trong Docker để giảm rủi ro khi chạy mã chưa tin cậy (cần cân nhắc hardening cho prod).
Khi nào nên dùng?
- Bạn cần một môi trường duy nhất nơi Agent có thể vừa duyệt web, vừa chạy lệnh, vừa đọc/ghi file, vừa chỉnh code mà không đổi ngữ cảnh.
- Bạn muốn demo nhanh một Agent có hành vi phức tạp (tương tác web + xử lý file + script), giảm ma sát thiết lập.
- Bạn cần lab thử nghiệm an toàn hơn mức chạy trực tiếp trên host, nhưng nhẹ hơn VM full-blown.
2) Kiến trúc hệ thống
┌────────────────────────────────────────────────────────────┐
│ Browser (VNC Desktop) │
├────────────────────────────────────────────────────────────┤
│ VSCode Server │ Shell / Terminal │ File │
├────────────────────────────────────────────────────────────┤
│ MCP Hub + Sandbox Fusion Layer │
├────────────────────────────────────────────────────────────┤
│ Preview Proxy │ Service Monitoring │ APIs (/v1) │
└────────────────────────────────────────────────────────────┘
Ý tưởng chính: Tất cả mô‑đun chạy trong cùng container và chia sẻ workspace. Agent gọi MCP tools hoặc REST API để thao tác Browser/Shell/File. Người dùng có thể vào VNC xem agent làm gì, VSCode để chỉnh code, hoặc Jupyter để thử nghiệm.
3) Bản đồ cổng & đường dẫn
| Đường dẫn/Cổng | Chức năng | Lưu ý nhanh |
|---|---|---|
/v1/docs |
API docs (Swagger) | Thử API ngay trong trình duyệt |
/vnc/index.html?autoconnect=true |
Desktop VNC + Browser | Quan sát/điều khiển trình duyệt thực |
/code-server/ |
VSCode Server | Chỉnh code, terminal tích hợp |
/mcp |
MCP endpoints | Kết nối agent ↔ công cụ |
TCP :8080 |
Exposed port mặc định | Có thể đổi qua ENV/Compose |
4) API chính (/v1) & MCP Tools
4.1 REST API tiêu biểu
| Endpoint | Chức năng | Ví dụ |
|---|---|---|
GET /v1/sandbox |
Thông tin môi trường (home, workspace, services) | Kiểm tra context trước khi chạy |
POST /v1/shell/exec |
Thực thi lệnh shell | {“command”: “ls -la”} |
POST /v1/file/read |
Đọc nội dung file | {“path”: “/workspace/a.txt”} |
POST /v1/file/write |
Ghi nội dung file | {“path”: “/workspace/a.txt”,”content”:”hi”} |
POST /v1/browser/screenshot |
Chụp ảnh màn hình trình duyệt | {“url”:”https://example.com”} |
POST /v1/jupyter/execute |
Chạy code trong Jupyter kernel | {“code”:”print(1)”} |
Lưu ý: Tên endpoint tham khảo từ tài liệu điển hình của sandbox. Triển khai có thể thay đổi theo phiên bản — hãy kiểm tra
/v1/docstrên instance của bạn.
4.2 MCP Tools (dành cho Agent)
- browser: navigate, screenshot, click, type, scroll
- file: read, write, list, search, replace
- shell: exec, create_session, kill
- markdown: convert, extracttext, extractimages
Các tool này cho phép Agent tương tác như một “trợ thủ vận hành” có tay/chân: vừa lướt web, vừa sửa file, vừa chạy lệnh.
5) Quy trình làm việc (Workflows) khuyến nghị
5.1 Browser → File → Shell (pipeline ba bước)
- Agent dùng browser.navigate tải trang/đăng nhập/tải file.
- File tải về rơi vào workspace (được mount chung).
- Agent gọi shell.exec để xử lý file (giải nén, phân tích, chạy tool), hoặc file.read/write để thao tác nội dung.
5.2 Quan sát & can thiệp trực tiếp
- Mở VNC để xem agent thao tác; khi cần, bạn có thể chủ động click/nhập để “giải cứu” workflow.
- Dùng VSCode Server để chỉnh script, ghi log, cài thêm gói (pip/npm) trong cùng môi trường.
5.3 Notebook‑driven Agent Dev
- Chạy Jupyter để thử nghiệm thuật toán, prompt, hoặc nhỏ hoá PoC.
- Khi ổn, “đóng gói” thành lệnh/flow để agent gọi qua MCP/REST.
5.4 Tích hợp CI/CD & demo
- Tạo job container khởi chạy AIO Sandbox cho mỗi nhánh PR → chạy test agent end‑to‑end.
- Dùng VNC & record để quay demo hành vi agent cho stakeholders.
6) Triển khai thực tế
6.1 Docker (nhanh nhất)
docker run --rm -it -p 8080:8080 \
-e WORKSPACE=/workspace \
-v $(pwd):/workspace \
ghcr.io/agent-infra/sandbox:latest
Truy cập: /v1/docs, /vnc/index.html?autoconnect=true, /code-server/, /mcp.
6.2 Docker Compose (đề xuất cho dev team)
version: '3.8'
services:
aio-sandbox:
image: ghcr.io/agent-infra/sandbox:latest
container_name: aio-sandbox
ports:
- "8080:8080"
environment:
- WORKSPACE=/workspace
- BROWSER_EXTRA_ARGS=--no-sandbox --autoplay-policy=no-user-gesture-required
- TZ=Asia/Ho_Chi_Minh
volumes:
- ./workspace:/workspace
security_opt:
- seccomp:unconfined # xem mục bảo mật bên dưới
6.3 Kubernetes (tham khảo)
apiVersion: apps/v1
kind: Deployment
metadata:
name: aio-sandbox
spec:
replicas: 1
selector: { matchLabels: { app: aio-sandbox } }
template:
metadata: { labels: { app: aio-sandbox } }
spec:
containers:
- name: aio-sandbox
image: ghcr.io/agent-infra/sandbox:latest
ports:
- containerPort: 8080
env:
- name: WORKSPACE
value: /workspace
volumeMounts:
- name: ws
mountPath: /workspace
volumes:
- name: ws
emptyDir: {}
---
apiVersion: v1
kind: Service
metadata:
name: aio-sandbox
spec:
type: ClusterIP
selector: { app: aio-sandbox }
ports:
- name: http
port: 8080
targetPort: 8080
Gợi ý: Với demo công khai, đặt Ingress + Auth (HTTP basic/OIDC) để tránh lộ môi trường thực thi ra Internet.
7) SDK & snippet mẫu
7.1 Python
from agent_sandbox import Sandbox
client = Sandbox(base_url="http://localhost:8080")
ctx = client.sandbox.get_context()
print("HOME:", ctx.home_dir)
# Shell
out = client.shell.exec_command(command="ls -la /workspace")
print(out.data.output)
# Browser screenshot
png = client.browser.screenshot(url="https://example.com")
open("/workspace/example.png", "wb").write(png)
# File ops
client.file.write(path="/workspace/notes.txt", content="hello")
text = client.file.read(path="/workspace/notes.txt")
print(text)
7.2 Gọi thẳng REST (curl)
curl -s http://localhost:8080/v1/shell/exec \
-H 'Content-Type: application/json' \
-d '{"command":"uname -a"}'
8) Bảo mật & vận hành (rất quan trọng)
-
Nguyên tắc cách ly: Dù đã nằm trong container, mã do Agent chạy có thể không tin cậy. Hãy thêm:
-
User không phải root, read‑only mounts nếu có thể.
-
AppArmor/Seccomp profile phù hợp (tránh
unconfinedở prod). -
Network policies (K8s) / firewall rule (Docker) hạn chế outbound.
-
Quota CPU/RAM/FS để chống lạm dụng.
-
Quản trị truy cập: Bảo vệ /vnc, /code-server, /v1 bằng auth (basic, OAuth/OIDC, mTLS…).
-
Giám sát & audit: Forward logs (API, shell), bật metrics, lưu artifacts (screenshot, output) để replay/debug.
-
Cập nhật định kỳ: Theo dõi release image mới, vá CVE nền tảng.
Best‑practice: Dùng AIO Sandbox cho dev/test/staging. Với prod, hãy tách chức năng theo micro‑sandbox hoặc hardened images.
9) Tình huống sử dụng tiêu biểu
- Agent kiểm thử ứng dụng web: crawl → tải tài liệu → phân tích → báo cáo screenshot.
- Autonomous data prep: trình duyệt tải dataset, shell xử lý, notebook trực quan hoá.
- Demo/Workshop: khởi tạo sandbox theo nhóm, người học chỉ việc truy cập URL.
- Bug repro lab: đính kèm lệnh & logs; dùng VNC để chứng minh bước làm của agent.
10) Ưu/nhược điểm
| Ưu điểm | Nhược điểm |
|---|---|
|
• Dựng nhanh, trọn gói; • Workspace chia sẻ giữa Browser/Shell/File; • Hỗ trợ VSCode/Jupyter/VNC tích hợp; • API & MCP tiện cho Agent. |
• Container khá nặng nếu chỉ cần một chức năng; • Cần hardening thêm cho prod; • Với workload lớn, nên chia nhỏ. |
11) Tối ưu SEO cho bài viết
- Từ khoá: AIO Sandbox, agent-infra/sandbox, AI agent sandbox, MCP tools, Browser Shell VSCode, unified sandbox environment.
- Meta description (gợi ý): “Phân tích chuyên sâu AIO Sandbox — môi trường hợp nhất Browser, Shell, File, VSCode Server, Jupyter và MCP cho AI Agents trong một container Docker. Hướng dẫn triển khai & bảo mật.”
- Heading hợp lý: H1 (tựa bài), H2 cho các mục 1‑11, tiêu đề mô tả rõ nội dung.
- Hình ảnh minh hoạ: Đã chèn logo/UI/background của dự án để tăng CTR & thời gian onsite.
12) Kết luận
AIO Sandbox là một “đế” tối giản mà đầy đủ để bạn phát triển, trình diễn và thử nghiệm AI Agents có hành vi phức tạp. Nếu mục tiêu là rút ngắn thời gian setup, quan sát hành vi agent trực quan, và tận dụng tiêu chuẩn MCP để orkestrate công cụ — đây là lựa chọn đáng cân nhắc.
Source link: agent-infra/sandbox
