2245976de4
The sandbox provides an isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository. The sandbox does not protect the repository from harmful changes by the agent. It limits what a misled agent can reach on the machine, but the agent can still write any change into the repository. Primary security defence is to check every change before it is run on the host. Same holds for opening a pull request or updating one. Additional changes - Reduce AGENTS.md to the project summary, baseline rules, completion checklist, and an index of the skills. - Add skills for the Python environment and REST API error responses. - Add the development guide page docs/develop/ai.md: the AI coding workflow, how agents get the project rules from AGENTS.md and ai/skills, and how to use the sandbox (start, agent logins, project commands with a virtual environment outside the workspace, running EOS and EOSdash, GitHub access, persistent data, security model). - Add a checklist for reviewing agent changes before pushing, starting with .git, which stays writable in the sandbox. - Check out all text files with LF line endings (.gitattributes), also on Windows with core.autocrlf, so the sandbox scripts run in the container and git in the container agrees with git on the host. Batch files keep CRLF. - Publish the ports of ai/compose.yaml on request (AI_SANDBOX_PORTS=1). docker compose run publishes them only with --service-ports. Off by default, so that several sandboxes can run in parallel. 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.