docker/run/AGENTS.md

Docker Runtime Image DOX

Purpose

• Own the runnable Agent Zero image context and local compose example.
• Install Agent Zero from a selected branch onto the base image and prepare runtime entrypoints.

Ownership

• Dockerfile owns branch-based image assembly, exposed ports, and container startup command.
• docker-compose.yml owns the local compose service example.
• build.txt owns maintainer build and push command notes.
• fs/exe/ owns runtime entrypoint, supervisor, self-update, Node eval, and service scripts.
• fs/exe/huggingface-entrypoint.sh owns Space-specific startup defaults, including disabling outbound Cloudflare tunnels and enabling MCP/A2A only when SPYNEL_AGENT_ZERO_API_KEY is configured; otherwise both are explicitly disabled with a safe warning.
• fs/ins/ owns preinstall, installation, virtualenv, Playwright, SSH, and postinstall scripts.
• fs/ins/install_argus_supervisor.sh installs immutable, SHA-pinned Argus and Foreman sources into separate build-time venvs; dependency constraints and adapters live in plugins/argus_supervisor/runtime/. Mutable supervision state stays under /a0/usr/argus-supervisor; no extra listener or runtime installs.
• fs/exe/huggingface-services.py owns non-root Space service lifecycle: private SearXNG on 127.0.0.1:55510, bounded readiness, restart delay and joint shutdown. Its temporary settings enable JSON, disable the limiter and generate a per-boot secret without changing user data. SearXNG/Gunicorn are verified/installed at image build; runtime installs remain disabled.
• Files under fs/ are copied to container root during the runtime build.

Local Contracts

• BRANCH is required for branch-based Docker builds.
• Preserve exposed ports for SSH, HTTP, and tunneled services unless docs and workflows are updated together.
• Keep the two-runtime Python model aligned with the root contract.
• Keep runtime desktop packages on kali-last-snapshot; carry the rolling base's matching ATK introspection package into that transaction, then pin the verified Python 3.13-compatible LibreOffice and complete Xpra runtime versions in fs/ins/install_additional.sh for both published architectures.
• Do not bake secrets, local .env values, or user data into the image.
• Runtime startup must ensure /a0/usr/uploads exists before supervised services start.
• Runtime startup raises the soft open-file limit toward A0_NOFILE_LIMIT (default 65535) before supervisord starts, bounded by the container hard limit.
• Self-update user-data backups skip Time Travel shadow history under usr/.time_travel/ and transient Desktop agent state.
• Self-update waits up to 180 seconds for the updated or restored WebUI health check by default; A0_SELF_UPDATE_HEALTH_TIMEOUT_SECONDS may override it.
• Successful or already-current self-updates refresh an installed Codex CLI with npm on a best-effort basis; missing CLIs and registry failures must not block Agent Zero startup.

Work Guidance

• Keep startup scripts explicit about framework runtime versus execution runtime.
• Coordinate tag, branch, and publishing changes with GitHub workflow automation.

Verification

• Build docker/run when changing Dockerfile or install scripts.
• Smoke-test container startup after entrypoint, supervisor, port, or compose changes.

Child DOX Index

No child DOX files.