mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-11-13 09:13:30 +01:00

Files

T

2245976de4 docs(ai): move agent rules to ai/skills and add an AI development sandbox (#1498 )

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>

2026-11-09 09:15:12 +01:00

4.0 KiB

Raw Blame History

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, with ai/ read-only)
Dockerfile – Debian slim + Python 3.13 + uv + Node.js + OpenCode + Claude Code + Qwen Code + gh, with pinned versions
entrypoint.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/bin in the image, outside the ai-home volume
.env.example – template, copied to .env on first run
run.sh / run.ps1 / run.bat – entry points (prerequisite checks, sanity check of compose.yaml, launch)
skills/ – project rules for the agents, indexed in AGENTS.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 in Dockerfile)
AI_SANDBOX_PORTS=1 – publish the ports of compose.yaml (8503 EOS, 8504 EOSdash) on 127.0.0.1 of the host. Off by default, as only one sandbox at a time can publish them. Start the servers with --host 0.0.0.0 inside the container to make them reachable.
AI_SANDBOX_SKILLS_RW=1 – make ai/skills writable in the sandbox, so the agent can update the skills. The rest of ai/ 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 privileged mode, no Docker socket, no host home mount, no sudo.
ai/ (sandbox definition and launchers) is read-only in the container.
.git is 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 .git before you run any git command on the host, see the review checklist in docs/develop/ai.md.
Git worktree checkouts are not supported: their .git is 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.yaml are a sanity check, not a complete validation.

4.0 KiB Raw Blame History Unescape Escape

AkkudoktorEOS AI Development Sandbox

Layout

Usage

Security notes

4.0 KiB

Raw Blame History