docker-sandbox-operations

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

1. Read repository AGENTS.md, SESSION_CONTEXT.md, and docs/docker-sandbox/tasks.md.
2. Work on only the current eligible phase. Never claim an unexecuted LIVE TEST.
3. Read docs/docker-sandbox/phase-7/operator-runbooks.md for the host platform.
4. Keep secrets out of Git, arguments, logs, diagnostics, skills, and images.

Configure a host

1. Verify Git, Docker client/daemon, Compose, available CPU/RAM/disk, and the pinned sbx capability range in sandbox/config/artifacts.lock.
2. 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.
3. Run ./scripts/validate.sh and python3 sandbox/scripts/release-acceptance.py verify.
4. 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   # 8765/8766/8767 for 17/18/19

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.