sandbox

环境要求

• 已安装 Docker 与 Docker Compose
• 需要拉取镜像 ghcr.io/agent-infra/sandbox:latest 的网络环境
• 容器建议分配 2GB 共享内存（shm_size）
• 如需用 SDK 调用，需准备 Python、Node.js 或 Go 环境之一

安装与启动步骤

1. 1创建 compose 文件

   在任意目录新建 docker-compose.yml，内容照抄下方命令，注意 ${HOST_PORT:-8080} 等变量保持原样不要展开

   cat > docker-compose.yml << 'EOF'
   services:
     sandbox:
       container_name: aio-sandbox
       image: ghcr.io/agent-infra/sandbox:latest
       security_opt:
         - seccomp:unconfined
       ports:
         - "127.0.0.1:${HOST_PORT:-8080}:8080"
       volumes:
         - sandbox_data:/home/gem/workspace
       extra_hosts:
         - "host.docker.internal:host-gateway"
       restart: "unless-stopped"
       shm_size: "2gb"
       environment:
         SANDBOX_API_KEY: ${SANDBOX_API_KEY:-}
         PROXY_SERVER: ${PROXY_SERVER:-}
         WORKSPACE: ${WORKSPACE:-/home/gem/workspace}
         TZ: ${TZ:-Asia/Singapore}
   
   volumes:
     sandbox_data:
   EOF

   复制

2. 2设置访问密钥

   可选但推荐：通过环境变量 SANDBOX_API_KEY 开启认证，保护 API、JupyterLab、VNC 三类服务

   export SANDBOX_API_KEY=sk-xxxxxxxx

   复制

3. 3启动沙箱容器

   在 docker-compose.yml 所在目录执行，首次会拉取镜像，后台运行容器

   docker compose up -d

   复制

4. 4安装 Python SDK

   在宿主机或自己的智能体项目里安装 SDK，用于远程调用沙箱内的能力

   pip install agent-sandbox

   复制

5. 5安装其他语言 SDK

   按需选择，TypeScript/JavaScript 项目或 Golang 项目使用对应命令

   npm install @agent-infra/sandbox
   go get github.com/agent-infra/sandbox-sdk-go

   复制

6. 6调用沙箱执行代码

   在 Python 中导入 Sandbox 类并创建实例，再调用 jupyter 或 nodejs 的执行代码接口

   from agent_sandbox import Sandbox
   
   sandbox = Sandbox()
   
   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

   复制

关键配置

如何确认成功

docker compose ps 显示容器 Up，浏览器访问 http://127.0.0.1:8080 能看到沙箱服务页面即成功。

常见问题

注意事项

• 端口默认只绑定 127.0.0.1，若需外部访问需自行调整映射地址并注意安全。
• 容器配置了 security_opt: seccomp:unconfined 与 shm_size: 2gb，改动前请确认宿主机安全策略。
• 浏览器访问地址为 http://127.0.0.1:8080，请勿把未设密钥的实例暴露到公网。