| name | docker-sandbox-operations |
| description | Configure, migrate, operate, validate, benchmark, upgrade, roll back, and release the Odoo 17/18/19 Docker Sandbox runtime. Use for Docker Sandbox onboarding, platform setup, local-to-sandbox migration, session lifecycle, release acceptance, capacity measurement, or troubleshooting in this repository. |
Docker Sandbox Operations
Establish context
- Read repository
AGENTS.md, SESSION_CONTEXT.md, and docs/docker-sandbox/tasks.md.
- Work on only the current eligible phase. Never claim an unexecuted LIVE TEST.
- Read
docs/docker-sandbox/phase-7/operator-runbooks.md for the host platform.
- Keep secrets out of Git, arguments, logs, diagnostics, skills, and images.
Configure a host
- Verify Git, Docker client/daemon, Compose, available CPU/RAM/disk, and the pinned
sbx capability range in sandbox/config/artifacts.lock.
- Use the Intel macOS workstation for repository, Docker, and registry checks. Run microVM/runtime acceptance on an Ubuntu 24.04+ KVM host. Treat other platform claims as unverified until their runbook matrix passes.
- Run
./scripts/validate.sh and python3 sandbox/scripts/release-acceptance.py verify.
- Use
sandbox/bin/sandbox-agent preflight before creating an outer agent Sandbox.
Operate a session
Use sandbox/bin/sandboxctl for inner runtime lifecycle and module operations. Use sandbox/bin/sandbox-fleet only for bounded single-host concurrency. Never invoke raw odoo-bin for an install, update, or test lifecycle gate.
sandbox/bin/sandboxctl create --version 19 --module my_module
sandbox/bin/sandboxctl module <session> install my_module
sandbox/bin/sandboxctl module <session> test my_module
sandbox/bin/sandboxctl logs <session> --service odoo
sandbox/bin/sandboxctl export <session>
sandbox/bin/sandboxctl destroy <session>
Read .sandbox/session.json and operation-result JSON. Require status: succeeded before advancing a lifecycle gate.
Expose odoo_mcp to a live session
sandbox/compose/compose.yaml does not publish Odoo's port outside the
sandbox's private Docker network, so plugin/odoo_mcp cannot reach a
sandboxed Odoo without extra wiring — and this pinned file must not be
edited. Use the additive Compose override at sandbox/mcp-sidecar/ instead:
sbx exec <name> -- bash sandbox/mcp-sidecar/mcp_up.sh <session-id>
sbx ports <name> --publish 8767:8767
See OdooHermesEnvironmentSetup/SKILL.md step 6 for the full flow, the
mcp[server]<2.0.0 pin pitfall, and why a bare docker run sidecar does not
survive sbx microVM idle-suspend/cold-reboot cycles.
Migrate local work
Require a clean source Git repository, then stage a secret-filtered copy:
python3 sandbox/scripts/migrate-local.py --source /absolute/custom-addons --version 19 --name my_module
Review migration-report.json; do not silently move a workspace or import a production database.
Release and rollback
Run the release verifier, Compose validation, CI smoke matrix, and documented clean-host LIVE TEST. Record benchmarks with benchmark.py. For rollback, restore the prior lock files and clean session data; restore a database only from an explicit compatible backup. Never downgrade persisted schema/database state in place.
Update implementation, README, requirements/design/runbooks, phase tasks, and SESSION_CONTEXT.md together. Run ./scripts/validate.sh from a clean shell before a focused phase commit.
