mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
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>
60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
---
|
|
name: python-environment
|
|
description: Use before running any Python, uv, pytest, mypy, ruff, pre-commit or make command. Keeps the agent's virtual environment out of the workspace .venv.
|
|
---
|
|
|
|
# Python Environment
|
|
|
|
## Why
|
|
|
|
The workspace may be shared with the developer's machine (e.g. a mounted
|
|
directory or a container). The workspace `.venv` then belongs to the developer
|
|
and is bound to an interpreter on their machine, which does not exist for the
|
|
agent. `uv` treats such a `.venv` as broken: it deletes and recreates it for
|
|
the agent's interpreter, which breaks the developer's environment, and the
|
|
developer's next `uv` call breaks the agent's in turn (e.g. dev tools such as
|
|
pytest or mypy go missing).
|
|
|
|
## Rules
|
|
|
|
- **Never use, create, modify or delete the workspace `.venv`.**
|
|
- Use a virtual environment outside the workspace, selected by
|
|
`UV_PROJECT_ENVIRONMENT`. In the AI development sandbox (`ai/`) it is
|
|
already set for every shell and tool call; check with
|
|
`echo "$UV_PROJECT_ENVIRONMENT"`.
|
|
- If it is not set, set it in **every** shell command that runs `uv` or
|
|
`make`, e.g.
|
|
`export UV_PROJECT_ENVIRONMENT="$HOME/.cache/eos-venv" && <command>`.
|
|
Exported variables do not carry over between separate tool calls. Put the
|
|
environment on a disk with enough space (it needs several hundred MB), not
|
|
on a small tmpfs such as `/tmp`.
|
|
- It applies to all commands that run Python through `uv`:
|
|
`uv sync`, `uv run ...` (pytest, mypy, python scripts, `pre-commit`), and the
|
|
`make` targets that use `uv run` (`make mypy`, `make gen-docs`, `make test`,
|
|
...).
|
|
- Create or update the environment with the dev tools:
|
|
|
|
```bash
|
|
uv sync --extra dev
|
|
```
|
|
|
|
A plain `uv sync` (without `--extra dev`) removes pytest, mypy and the other
|
|
dev tools from the environment.
|
|
- Do not let a newer local `uv` rewrite `uv.lock`: use `uv sync --frozen` /
|
|
`uv run --frozen`. When the lock must change (dependencies changed), lock with
|
|
the `uv` version CI uses (`.github/workflows/pre-commit.yml`), e.g.
|
|
`uv tool run --from uv==<version> uv lock`, and check that `revision` in
|
|
`uv.lock` did not change.
|
|
- Do not run commands that remove the workspace `.venv`, e.g. `make clean`
|
|
(`rm -rf build .venv`) or `rm -rf .venv`.
|
|
|
|
## Verify
|
|
|
|
- `uv run python -c "import sys; print(sys.prefix)"` prints the environment
|
|
outside the workspace, not `<workspace>/.venv`.
|
|
- If `uv` reports `Removed virtual environment at: .venv` or
|
|
`Ignoring existing virtual environment linked to non-existent Python
|
|
interpreter`, the variable was not set: the workspace `.venv` was rebuilt.
|
|
Do not try to repair it; tell the developer to run `uv sync --extra dev` on
|
|
their machine.
|