Development and verification

Repository layout

agent_platform/
  runtime/        Agent API, loop, context, model transport, and tools
  gateway/        Authenticated workspace and file service
  auth.py         Internal service and signed identity verification
  models.py       Public model catalog and server-side budgets
  store.py        Run events, memories, and plans
docker/
  web/            Open WebUI components and reproducible patch set
  *.Dockerfile    Web, Runtime, Gateway, and Workspace images
docs/
  site/           Static source for /doc/
deploy/           Production Compose files and SSH override
e2e/              Deterministic full-stack verifier and fake provider
scripts/          Verification, evaluation, audit, and secret helpers
tests/            Unit and real Docker integration tests

Local environment

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
cp .env.example .env
./scripts/init-secrets.sh

Keep real provider credentials in a protected local environment or deployment file. Never add them to Git, Docker build arguments, frontend code, test fixtures, or logs.

Build the user workspace, then start the stack:

docker compose --profile build-only build workspace-image
docker compose up --build

Open http://localhost:3000. New registrations have the pending role until approved by the bootstrap administrator.

Fast feedback

.venv/bin/ruff check agent_platform tests e2e
.venv/bin/ruff format --check agent_platform tests e2e
.venv/bin/pytest

Unit tests are deterministic and do not require a model provider.

Real Docker integration

docker build -f docker/workspace.Dockerfile \
  -t k1412-agent-workspace:test .
RUN_DOCKER_INTEGRATION=1 \
  .venv/bin/pytest tests/test_docker_workspace.py

The test creates unique containers, networks, and volumes and removes only those resources in cleanup.

Full-stack E2E

./scripts/verify-e2e.sh

The script builds a disposable six-service stack, uses a deterministic model stub, performs authentication and isolation checks, and removes the stack and test volumes on exit.

Live Agent evaluation

set -a
source /path/to/protected/provider.env
set +a
.venv/bin/python scripts/eval-live-work.py --model deepseek-v4-pro

Use --keep-workspace only when inspecting a failed case; remove that uniquely named evaluation workspace afterward.

Image audit

./scripts/audit-images.sh

The audit requires consistent Python environments and no fixable High/Critical vulnerabilities in the finished images. Web also receives a Python dependency audit.

Documentation portal

docs/site/ is dependency-free static HTML, CSS, JavaScript, and JSON. It is copied into /app/build/doc by docker/web.Dockerfile after Open WebUI's frontend build completes.

Validate it locally with:

python3 -m http.server 4173 --directory docs/site

The production path is /doc/; all internal assets therefore use relative URLs. Keep the Markdown documents and portal content aligned in the same commit. Add experiment cards through docs/site/experiments.json.

Change checklist

Before pushing:

keep unrelated working-tree changes untouched;
update architecture or behavior documentation;
add deterministic tests for policy changes;
run unit and formatting checks;
run Docker integration for workspace/Gateway changes;
run E2E for public model, auth, loop, or file-delivery changes;
audit every rebuilt image;
use immutable production image tags;
verify public health and one representative user flow;
retain the previous image and deployment backup until verification passes.

3.6 KiB Raw Blame History