Agent Sandbox极速版提供了官方 GitHub 模板仓库 aliyun-fc/fce2b-template-builder。从该模板创建自己的仓库后，只需要维护一个 Dockerfile，GitHub Actions 会自动完成：构建 linux/amd64 镜像并推送到你仓库的私有 GHCR、从该镜像构建 Sandbox 模板、创建 Sandbox 做冒烟校验，最后输出可直接使用的 Template ID。
与使用 GHCR 自定义镜像构建 Sandbox 模板相比，后者需要自己把镜像推送到 GHCR 再调用 SDK 构建模板；本文的方式把模板发布集成进 GitHub Actions，适合希望把模板定义纳入 Git 流程、随代码提交自动发布新模板版本的场景。
业务场景
-
模板定义（Dockerfile 和依赖）与业务代码一起版本化管理，每次提交自动发布新的模板版本。
-
团队成员不需要在本地安装 Docker 或 SDK，通过提交代码或在 GitHub 上手工触发即可完成发布。
-
镜像保存在私有 GHCR 仓库，不允许匿名拉取，构建产物由自己的 GitHub 账号管控。
支持的地域
| 地域 | Region |
| 中国香港 | cn-hongkong |
| 新加坡 | ap-southeast-1 |
| 美国（弗吉尼亚） | us-east-1 |
| 美国（硅谷） | us-west-1 |
API Key 按地域隔离，一次发布只面向一个地域。
前置条件
-
已开通Agent Sandbox极速版，并获取目标地域的 API Key。
-
拥有 GitHub 账号，且具备创建仓库的权限。
步骤一：创建自己的仓库
在 aliyun-fc/fce2b-template-builder 仓库页面右上角点击 Use this template，选择 Create a new repository。
创建仓库后，根据需要修改根目录的 Dockerfile。提交代码前，请确保 Dockerfile 可以构建 linux/amd64 镜像。
步骤二：创建 GitHub Token
创建一个 GitHub Personal Access Token (classic)，并授予以下权限：
-
read:packages -
write:packages
Token 所属用户必须对当前仓库及其 private GHCR package 具有读写权限。如果组织启用了 SSO，还需要为该 Token 完成组织授权。
步骤三：配置 GitHub Actions 凭据
进入仓库的 Settings → Secrets and variables → Actions。
在 Secrets 中添加：
| 名称 | 说明 |
FCE2B_API_KEY |
目标地域的Agent Sandbox极速版 API Key。 |
GHCR_TOKEN |
上一步创建的 GitHub Token。 |
在 Variables 中添加：
| 名称 | 示例 | 说明 |
FCE2B_REGION |
us-west-1 |
创建模板的目标地域。 |
修改 FCE2B_REGION 时，必须同时把 FCE2B_API_KEY 替换为该地域的 API Key。
步骤四：发布模板
使用以下任一方式触发发布：
-
修改并提交
Dockerfile、依赖文件或landing目录中的文件到master分支； -
进入 Actions → Build fce2b template → Run workflow 手工触发。
一次完整执行通常需要约 1～3 分钟，实际时间取决于地域和镜像大小。
步骤五：获取发布结果
执行成功后，在对应的 GitHub Actions run 中查看：
-
Summary：Template ID、Build ID、Sandbox ID、镜像地址和验证结果；
-
Artifacts → landing-result：下载完整的
landing.json。
保存输出的 Template ID，后续即可使用 E2B SDK 通过该模板创建 Sandbox。
更新模板
修改 Dockerfile 或依赖后重新触发 workflow。每次成功发布都会生成新的 Template ID，不会覆盖之前的模板；需要回滚时继续使用旧的 Template ID 即可。
也可以通过 Git tag 发布带版本号的镜像：
git tag v1.0.0
git push origin v1.0.0tag 推送后会自动构建 linux/amd64 镜像并发布到：
ghcr.io/<owner>/<repository>:v1.0.0版本 tag 不会同时覆盖 latest。如需发布新版本，请创建新的 Git tag。
凭据维护
-
不要把
FCE2B_API_KEY或GHCR_TOKEN写入仓库文件、Dockerfile 或 Action 日志。 -
GHCR_TOKEN必须保持有效，确保Agent Sandbox极速版能够继续读取你的私有 GHCR 镜像。 -
Token 轮换后，更新
GHCR_TOKEN并重新发布模板。 -
API Key 轮换或切换地域后，更新
FCE2B_API_KEY并重新发布模板。
常见问题
-
GHCR 登录或推送返回 401/403：检查
GHCR_TOKEN是否具有read:packages、write:packages权限，以及 Token 所属用户是否能访问当前仓库。如果仓库属于组织，还需检查 SSO 授权。 -
API Key 被拒绝：检查 API Key 是否为目标地域的有效 Key，并确认它与
FCE2B_REGION对应。 -
workflow 没有自动运行：自动触发仅监听
master分支中的 Dockerfile、依赖、workflow 和landing相关文件，也可以在 Actions 页面手工运行。 -
模板创建成功但后续无法拉取镜像：检查 GHCR package 是否保持 private、
GHCR_TOKEN是否过期，以及 Token 所属用户是否仍有 package 读取权限；更新 Token 后重新发布模板。