AutoAgent 自定义沙箱指南打造专属 Docker 运行环境与镜像定制【免费下载链接】AutoAgentAutoAgent: Fully-Automated and Zero-Code LLM Agent Framework项目地址: https://gitcode.com/GitHub_Trending/au/AutoAgent本指南以 AutoAgent 仓库中的《自定义沙箱》文档为骨架系统讲解沙箱Sandbox的运行机制、默认镜像、两种自定义路线以及完整的配置与启动流程并结合仓库源码autoagent/environment/docker_env.py、constant.py、autoagent/cli.py等深入剖析底层实现。读完本文你将掌握如何为代理定制一个基于 Debian 的专属 Docker 镜像、如何通过配置项指定基础镜像以及沙箱容器的生命周期管理与通信原理从而在自己的机器上安全、可复现地运行 AutoAgent。什么是沙箱代理执行任务的安全边界沙箱是代理执行任务的地方。代理并不会直接在你的计算机上运行命令这可能有风险例如误删文件、污染系统环境或泄露凭据而是在一个隔离的 Docker 容器内运行这个容器就是沙箱。为什么不直接在宿主机上执行仓库文档 Docker 运行时 总结了五个核心理由安全性不受信任的代码可能危及主机系统沙箱可防止恶意代码访问或修改主机资源一致性保证代码执行在不同机器和设置下结果一致消除在我的机器上能跑的问题资源控制更好地控制资源分配防止失控进程拖垮宿主机隔离不同项目或用户互不干扰可重现性执行环境一致可控便于复现错误与问题。在 AutoAgent 仓库中这一设计体现为 autoagent/environment/docker_env.py 中的DockerEnv类。它负责创建、启动、停止容器并通过 TCP 端口与容器内的tcp_server.py通信来执行命令——这正是沙箱机制的源码级实现。默认沙箱镜像开箱即用的基础环境默认的沙箱镜像为python-nodejs:python3.12-nodejs22来自nikolaik/python-nodejs它预装了 Python 3.12 和 Node.js 22 等常用软件包。对于大多数任务来说这个基础环境已经够用但如果你需要 Python/Node 之外的运行时如 Ruby、Go、Java或额外的系统级软件就需要自行定制。在 AutoAgent 中默认镜像由 constant.py 中的BASE_IMAGES常量控制DOCKER_WORKPLACE_NAME os.getenv(DOCKER_WORKPLACE_NAME, workplace) ... BASE_IMAGES os.getenv(BASE_IMAGES, None) def get_architecture(): machine platform.machine().lower() if x86 in machine or amd64 in machine or i386 in machine: return tjbtech1/metachain:amd64_latest elif arm in machine: return tjbtech1/metachain:latest else: return tjbtech1/metachain:latest if BASE_IMAGES is None: BASE_IMAGES get_architecture()可以看到AutoAgent 会根据机器架构x86/amd64 或 arm自动选择对应的预构建镜像无需手动 pull——这正是 README.md 中Docker Installation一节所述的能力。同时你也可以通过环境变量BASE_IMAGES覆盖默认值这本质上就是自定义沙箱镜像在 AutoAgent 中的入口。两条自定义路线总览自定义沙箱镜像有两种方式你可以根据情况选择使用已有的镜像如果你所需的软件已经存在于某个现成镜像如官方镜像或团队维护的镜像中直接指定该镜像即可无需编写任何 Dockerfile创建你自己的自定义 Docker 镜像当现成镜像无法满足需求时编写 Dockerfile 构建专属镜像。如果你选择第一个选项可以跳过下一节创建你的 Docker 镜像。创建你的 Docker 镜像基础镜像要求必须基于 Debian创建自定义 Docker 镜像时它必须基于 Debian。这是为了确保镜像内拥有与沙箱运行时兼容的软件包管理机制apt和系统布局。编写 Dockerfile例如如果你想让沙箱环境安装ruby创建一个包含以下内容的DockerfileFROM debian:latest # Install required packages RUN apt-get update apt-get install -y ruby要点说明FROM debian:latest指定基于 Debian 的最新版你也可以固定到具体版本号如debian:bookworm以保证构建可重现RUN apt-get update apt-get install -y ruby先更新软件源索引再安装软件包-y避免交互式确认阻塞构建如需安装多个软件包可在一条RUN中并列列出减少镜像层数。构建镜像将此文件保存在一个文件夹中然后在终端中导航到该文件夹并运行以下命令构建镜像示例镜像名为custom-imagedocker build -t custom-image .构建完成后会生成一个名为custom-image的新镜像它将在 Docker 中可用可通过docker images查看确认。重要注意事项在本文档描述的配置中代理将以用户openhands的身份在沙箱内运行因此通过 Dockerfile 安装的所有软件包应对系统上的所有用户可用而不仅仅是 root。这意味着避免把关键软件只安装到/root等仅 root 可读写的路径若需要自定义工作目录或环境变量应确保普通用户可访问需要写权限的目录如软件缓存、日志目录应设置合理的属主和权限。配置并使用自定义沙箱镜像指定基础沙箱镜像在原文档对应的配置方式中需要在config.toml文件中将sandbox_base_container_image设置为你要使用的镜像可以是你已经拉取的镜像也可以是你刚构建的镜像[core] ... sandbox_base_container_imagecustom-imageAutoAgent 仓库中的对应配置方式在 AutoAgent 仓库中与sandbox_base_container_image对应的配置机制是.env文件中的BASE_IMAGES环境变量。仓库在 constant.py 中通过os.getenv(BASE_IMAGES, None)读取若未设置则按架构自动选择默认镜像。因此自定义镜像只需在.env中添加BASE_IMAGEScustom-image结合 README.md 的 API Keys 配置说明一个典型的.env文件形如# 基础沙箱镜像自定义 BASE_IMAGEScustom-image # Required Github Tokens of your own GITHUB_AI_TOKEN # Optional API Keys OPENAI_API_KEY DEEPSEEK_API_KEY ANTHROPIC_API_KEY GEMINI_API_KEY容器配置参数一览无论使用默认镜像还是自定义镜像AutoAgent 都会通过 autoagent/environment/docker_env.py 中的DockerConfig数据类来组织容器的创建参数这些字段可以在 autoagent/cli.py 的get_config()中看到实际装配过程配置字段默认值说明container_name无CLI 默认auto_agentDocker 容器名称用于查找与复用容器workplace_nameworkplace来自DOCKER_WORKPLACE_NAME容器内工作区目录名communication_port12345宿主机与容器通信的 TCP 端口conda_path/root/miniconda3容器内 conda 安装路径test_pull_namemain需要拉取的测试分支名task_nameNone任务名称用于分支命名git_cloneFalse是否在容器工作区克隆 AutoAgent 仓库local_rootos.getcwd()宿主机工作区根目录与容器目录做卷挂载运行原文档的运行方式为在顶层目录执行make run来启动。在 AutoAgent 中对应的启动入口是auto main命令定义于 autoagent/cli.py其关键参数如下详见 README.md--container_nameDocker 容器名称默认auto_agent--port容器通信端口默认12347--test_pull_name测试拉取分支名默认autoagent_mirror--git_clone是否在本地环境克隆 AutoAgent 仓库镜像agent editor、workflow editor模式需要设为True--local_env是否使用本地环境替代 Docker 沙箱默认False。例如auto main --container_name my_agent --port 12347若希望完全绕开 Docker 而在本机 conda 环境中直接执行命令可将--local_env设为True此时 autoagent/environment/local_env.py 中的LocalEnv会通过source conda.sh conda activate auto的方式在宿主机上执行命令注意这会失去沙箱的隔离保护仅建议在受控环境使用。沙箱运行时的底层工作原理容器生命周期管理从源码看DockerEnv的容器管理逻辑autoagent/environment/docker_env.py包含三个关键环节幂等创建init_container()先检查同名容器是否已存在、是否在运行。已运行则直接复用存在但停止则docker start唤醒都不存在才创建新容器启动命令创建时执行的 Docker 命令形如docker run -d --name container_name --user root \ -v local_workplace:docker_workplace \ -w docker_workplace \ -p port:port BASE_IMAGES \ /bin/bash -c python3 docker_workplace/tcp_server.py --workplace workplace --conda_path conda_path --port port其中-v完成宿主机与容器工作区的目录挂载-p映射通信端口容器启动后运行的是 autoagent/environment/tcp_server.py 作为命令执行服务 3.就绪检查wait_for_container_ready()通过docker inspect轮询容器状态并校验端口映射与tcp_server.py进程是否真正运行避免容器起来了但服务未就绪的竞态问题。客户端-服务器通信模型沙箱内外的命令执行采用客户端-服务器架构宿主机上的DockerEnv.run_command()docker_env.py作为客户端通过 socket 连接容器映射出来的端口发送命令容器内的tcp_server.py执行命令并把结果以 JSON 流chunk/final两种消息类型回传支持流式输出回调。这与仓库文档 Docker 运行时 中描述的后端通过 REST API 与 Action 执行服务器通信的模式一脉相承。镜像标签与增量构建为了让镜像构建更高效运行时镜像采用多标签体系版本标签oh_v{version}_{base_image}最通用锁定标签oh_v{version}_{16位锁哈希}由基础镜像名、pyproject.toml、poetry.lock内容哈希得到源码标签oh_v{version}_{锁哈希}_{源码哈希}最具体。构建时按源码标签 → 锁定标签 → 版本标签 → 全新构建的顺序复用已有镜像层小改动时跳过poetry install、apt-get等安装步骤大幅缩短重建时间。插件系统扩展沙箱运行时还支持插件机制插件以继承基础Plugin类的 Python 类定义注册在ALL_PLUGINS字典中随运行时客户端启动时异步初始化。这为在沙箱内扩展 Jupyter、浏览器等能力提供了标准入口——如果你要定制的不只是镜像内的软件而是运行时能力本身可以从这里入手。常见问题与注意事项端口冲突AutoAgent 在 cli.py 中通过check_container_ports检测已有容器的端口映射并用filelock文件锁配合端口文件避免多实例端口分配冲突若12347被占用会自动递增寻找可用端口。架构匹配自定义镜像务必与宿主机 CPU 架构匹配amd64与arm64镜像不通用否则容器将无法运行AutoAgent 默认按platform.machine()自动选择架构对应镜像。用户权限代理以非 root 用户身份在沙箱内运行Dockerfile 中安装的软件必须对系统所有用户可用详见上文重要注意事项。隔离与安全沙箱的核心价值是隔离与可重现若使用--local_env直接在本机执行将失去这些保障务必自行评估风险。依赖环境运行前需确保 Docker 已安装并启动仓库 README.md 中给出了pip install -e .安装 AutoAgent 及 Docker 安装的完整指引。延伸阅读Docker 运行时架构详解沙箱存在的原因、客户端-服务器架构、镜像标签与插件系统的完整说明自定义沙箱指南英文原版同名文档的另一个版本Docker 环境实现源码DockerConfig与DockerEnv的完整实现本地环境实现源码不使用 Docker 时的替代执行环境CLI 入口与配置装配auto main命令及各启动参数的实际解析逻辑环境变量与镜像选择BASE_IMAGES等运行时关键常量的定义与架构探测逻辑。【免费下载链接】AutoAgentAutoAgent: Fully-Automated and Zero-Code LLM Agent Framework项目地址: https://gitcode.com/GitHub_Trending/au/AutoAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
