micrograils/opencode-ultra repository overview

⁠micrograils/opencode-ultra

把 opencode⁠（AI 编码 agent）与 Impetus（OpenSpec + Superpowers 双星工作流）打包成一个开箱即用的交互式开发环境镜像。

启动后你会得到一个已经初始化好的 AI 开发工作区：opencode、impetus、openspec、skills、codegraph、docker 都可用，技能与命令已就位，直接在项目目录里敲 opencode 就能开始干活——包括用 docker build / docker run 自测你自己的项目。

⁠镜像里有什么

⁠快速开始（推荐：启动器脚本）

仓库自带宿主侧启动器 bin/opencode-ultra-here.sh，一条命令搞定「启动 / 复用 / 清理」：

install -m 0755 bin/opencode-ultra-here.sh ~/.local/bin/opencode-ultra-here.sh
cd /path/to/your/project
opencode-ultra-here.sh

它会：

• 以你当前的绝对路径镜像挂载项目（-v "$PWD":"$PWD" -w "$PWD"），容器内 pwd 与宿主一致；
• 创建常驻容器并进入交互式 shell；退出 shell 后容器仍在，下次再进去秒开；
• 默认挂载宿主 docker socket，容器内 docker build / docker run 直接作用于宿主 daemon；
• 记住「哪个目录用哪个容器」，同一目录重复执行只会复用。

用法：

环境变量：OPENCODE_ULTRA_IMAGE（镜像名，默认 micrograils/opencode-ultra）、USER_UID / USER_GID、DOCKER_SOCK。

⁠手动运行（不用启动器）

docker run -it \
  --name opencode-ultra-$(basename "$PWD") \
  -v "$PWD":"$PWD" -w "$PWD" \
  -e USER_UID="$(id -u)" -e USER_GID="$(id -g)" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --add-host=host.docker.internal:host-gateway \
  micrograils/opencode-ultra

默认进入交互式 bash，敲 opencode 开始。也可以直接执行命令：

docker run --rm -v "$PWD":"$PWD" -w "$PWD" micrograils/opencode-ultra opencode --version

习惯把项目挂到 /workspace 也一样：镜像的 WORKDIR 就是 /workspace。

⁠容器内的 Docker（DooD）

容器里的 docker 命令操作的是宿主 Docker，所以 docker build / docker run 构建、运行的容器都在宿主上，正是「自测我自己项目」的预期。

-v /var/run/docker.sock:/var/run/docker.sock

• 挂上 socket 即可使用，无需 --group-add；
• 建议加 --add-host=host.docker.internal:host-gateway，容器内可用 host.docker.internal 访问宿主；
• 不需要 --privileged；
• 远端 daemon 可用 -e DOCKER_HOST=... 透传。

⁠运行身份

容器内以你的身份（UID/GID）运行，写出的文件在宿主机上属主一致，不用事后 chown。

docker run -it -v "$PWD":"$PWD" -w "$PWD" \
  -e USER_UID="$(id -u)" -e USER_GID="$(id -g)" \
  micrograils/opencode-ultra

• USER_UID / USER_GID（别名 PUID / PGID）可手动指定；
• 不指定时自动沿用在宿主上的身份，兜底 1000:1000；
• 用 --user 指定了身份时，容器内就按那个身份运行；
• 宿主账号本身是 root 时，容器内同样是 root。

容器不会递归修改你挂载目录的属主，宿主文件不会被改动。

⁠工作区初始化

首次在某个目录里启动容器时，会自动补齐 Impetus 工作区脚手架：

• .git/（没有就 git init）
• .opencode/、.agents/、.impetus/、openspec/、docs/、skills-lock.json

已经存在的文件一律不动，不会覆盖你已有的工程。整个初始化不需要联网，也不需要再手动执行 impetus init。

跳过初始化：

docker run -it --rm -v "$PWD":"$PWD" -w "$PWD" -e IMPETUS_SKIP_INIT=1 micrograils/opencode-ultra

⁠环境变量

凭据绝不写入镜像。 只通过运行时环境变量（或挂载你自己的配置文件）注入。

⁠持久化（具名 volume）

opencode 的配置与会话默认在容器内，容器删除即丢失。用具名 volume 持久化：

docker volume create opencode-config
docker volume create opencode-data

docker run -it \
  -v "$PWD":"$PWD" -w "$PWD" \
  -v opencode-config:/home/dev/.config/opencode \
  -v opencode-data:/home/dev/.local/share/opencode \
  micrograils/opencode-ultra

首次挂载即可直接读写。

⁠组件一览

⁠常用命令

⁠镜像信息

• 基础镜像:node:22-bookworm-slim（Debian 12）
• 默认工作目录:/workspace（用启动器时按宿主真实路径挂载并切到该路径）
• 多架构:amd64 / arm64
• 许可证:OpenCode (MIT)、Impetus (MIT)

⁠已知限制

• 首次构建镜像需要网络（npm registry、github.com、download.docker.com）。
• 技能（skills）内容随镜像版本提供；升级技能请重建镜像。
• 工作区模板的语言为英文。
• CodeGraph 首次建立索引会占用一些 CPU / IO。
• 容器内的 Docker 依赖宿主提供 socket；宿主未装 Docker 或未开放 socket 时容器内 docker 不可用。
• bin/opencode-ultra-here.sh 是宿主侧脚本，不包含在镜像内。

维护者文档（构建 / 版本管理 / 升级 / 维护）见 MAINTENANCE.md⁠。