Bobby NoelteandClaude Opus 5.5
dd41e5d57c
Additional changes Agents write a task plan to .scratch/<branch>/plan.md and self-review with code-review Agents fix hard violations, report judgement calls and rerun the self-review before every push Agents declare the review in a Self-review section of the pull request body Add the ai-self-review workflow and scripts/check_pr_self_review.py for pull requests into main Detect agents by Assisted-by or Anthropic Co-Authored-By trailers, body markers or the AI box Fail only on a missing Self-review section or a missing, malformed or stale Reviewed SHA Note an unticked AI-assisted box and malformed optional lines without failing Comment on the pull request how to fix a failure and update that one comment on later runs Show the same report in the job summary and accept Windows line endings in the body Skip dependabot and release pull requests Run on pull_request_target with the base branch's script, never pull request code Add the pull request template: the pr skill's sections plus Checklist and Self-review Require always valid optimization parameters in the energy-domain skill Require datetimeutil for date and time handling in new and changed code in AGENTS.md Require the Assisted-by trailer on agent commits in the commit-messages skill Add tests for the check in tests/test_ai.py Add GLOSSARY.md and the agent tracker docs in docs/agents/ Add decision record docs/adr/0001 with an ADR index in the docs toctree Document the workflow in docs/develop/ai.md and CONTRIBUTING.md Exclude docs/agents from Sphinx and PyMarkdown and ignore .scratch/ Document cz check instead of make gitlint for commit messages in docs/develop/ai.md Assisted-by: Claude Code (claude-opus-5-5) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AkkudoktorEOS AI Development Sandbox
Isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository.
The sandbox does not protect your repository from harmful changes by the agent. It limits
what a misled agent can reach on your machine, but the agent can still write any change into the
repository. Check every change before you run it on the host, open a pull request or update one.
See the security model in docs/develop/ai.md.
Layout
compose.yaml– service definition (bind-mounts the repo root to/workspace, withai/read-only)Dockerfile– Debian slim + Python 3.13 + uv + Node.js + OpenCode + Claude Code + Qwen Code + gh, with pinned versionsentrypoint.sh– container init (exec-bit stripping and reset of the shell startup files in$HOME, warning about active git hooks, uv cache, git config, gh credential helper); installed to/usr/local/binin the image, outside theai-homevolume.env.example– template, copied to.envon first runrun.sh/run.ps1/run.bat– entry points (prerequisite checks, sanity check ofcompose.yaml, launch)skills/– project rules for the agents, indexed inAGENTS.md
Usage
From the repository root:
- Linux/macOS:
chmod +x ai/run.sh && ./ai/run.sh - Windows PowerShell:
.\ai\run.ps1 - Windows CMD:
ai\run.bat
Options (environment variables):
AI_SANDBOX_REBUILD=1– rebuild the image (e.g. after bumping the agent CLI versions inDockerfile)AI_SANDBOX_PORTS=1– publish the ports ofcompose.yaml(8503 EOS, 8504 EOSdash) on127.0.0.1of the host. Off by default, as only one sandbox at a time can publish them. Start the servers with--host 0.0.0.0inside the container to make them reachable.AI_SANDBOX_SKILLS_RW=1– makeai/skillswritable in the sandbox, so the agent can update the skills. The rest ofai/stays read-only.
A command after -- runs instead of the shell, e.g. ./ai/run.sh -- claude. In PowerShell the
-- is optional: .\ai\run.ps1 claude. On Windows prefer PowerShell 7; run.bat cannot pass
! and % to the container.
On Windows the repository must be checked out with LF line endings, which .gitattributes
enforces (see docs/develop/ai.md). In the sandbox, run pre-commit on the changed files only;
--all-files fails on the read-only ai/ directory. Changes to ai/ itself (outside ai/skills,
or to ai/skills without AI_SANDBOX_SKILLS_RW=1) must be checked on the host for the same reason.
See docs/develop/ai.md for the AI coding workflow.
Inside the container (working dir /workspace):
opencode auth login # or /connect in the TUI
claude # then /login on first run
qwen
gh auth login # then gh auth setup-git
All auth state persists in the akkudoktor-ai-home Docker volume. The local
repository is bind-mounted at /workspace, so AI-made changes are visible on
the host immediately.
Security notes
- No
privilegedmode, no Docker socket, no host home mount, nosudo. ai/(sandbox definition and launchers) is read-only in the container..gitis writable, so the agent can commit. It can also plant git configuration and hooks that run on the host (e.g. through.git/commondir). Check.gitbefore you run any git command on the host, see the review checklist indocs/develop/ai.md.- Git worktree checkouts are not supported: their
.gitis a file pointing outside the repository, so git does not work in the sandbox. - Container user matches the host UID/GID (Linux/macOS) so file ownership is preserved.
- Credentials are never written to git or to
compose.yaml; they live only in the persistent home volume via each tool's own login flow. - The home volume persists between sessions. Remove it (
docker volume rm akkudoktor-ai-home) if a session may have been misled. - The launchers' checks of
compose.yamlare a sanity check, not a complete validation.