MCP-Project-bus/docs/SANDBOX_ACTIVATION_RUNBOOK.md

Sandbox Activation Runbook

This runbook operationalises the Project Bus for the Epimonos Sandbox project. It does not itself authorize an internet-facing endpoint or replacement of the existing formal project channels.

Authority and transition rule

WP-PA-001 is the accepted software baseline. WP-PA-002 covers deployment and activation. SG, PTO and the existing project threads remain authoritative until the independent reviewer returns APPROVE on the operationalisation commit and the Sandbox PM closes the WP-PA-002 gate with ACCEPT.

Before that gate, Project Bus records are shadow records. Differences are resolved in favour of the formal threads and recorded as corrections rather than silently rewriting history.

Deployment preparation

1. Use a dedicated single-node host or controlled test VM.
2. Keep the endpoint private unless PM-to-PO consultation has approved internet exposure.
3. Copy deploy/project-bus.env.example to a root/service-owner-readable file outside the repository.
4. Generate independent random bearer credentials of at least 32 bytes for SYSTEM, PO, PM, PA, Codex and Claude. Never reuse Git or account tokens.
5. Replace the example values and set permissions to owner-read/write only.
6. Configure TLS/authenticated ingress before any non-local exposure.
7. Pin the reviewed Git commit or immutable image digest.

Start:

docker compose --env-file /secure/path/project-bus.env \
  -f deploy/compose.yaml up -d --build
docker compose -f deploy/compose.yaml ps

The container must report healthy and run as the non-root image user.

Project bootstrap

The bootstrap command reads the SYSTEM credential only from an environment variable. The manifest contains identities and roles, never credentials.

export PROJECT_BUS_BOOTSTRAP_TOKEN='read-from-secret-store'
project-bus-ops bootstrap \
  --endpoint http://127.0.0.1:8080/mcp \
  --manifest deploy/sandbox-project.json
unset PROJECT_BUS_BOOTSTRAP_TOKEN

Run the same command a second time. It must replay successfully and create no duplicate project, actor or event records.

After bootstrap, remove the SYSTEM credential from the steady-state service configuration and restart. Retain it offline only if the operating policy requires future project creation; otherwise rotate/revoke it.

Actor connection and smoke test

For each actor credential:

1. call initialize without authentication;
2. call get_project for epimonos-sandbox;
3. verify returned roster and formal role expectations;
4. call sync_since with that client's durable cursor;
5. call list_pending_actions;
6. persist the new cursor only after processing all returned events.

Store each actor token in that client's secret facility. Do not place tokens in .mcp.json, project instructions, prompts, shell history or Git.

Claude Code endpoint registration:

claude mcp add --scope project --transport http \
  epimonos-project-bus https://approved-project-bus.example/mcp

The endpoint configuration may be project-scoped; the credential must remain in a user/workload secret store.

Initial shadow records

Once the actors authenticate, the PM registers WP-PA-002 through issue_work_package, Codex claims it, and the PA links the implementation commit and evidence. These records mirror the formal thread record during the bootstrap phase. Claude submits the independent review through both the existing formal channel and the bus.

The PM then closes the WP-PA-002 gate. Only an ACCEPT outcome after an independent APPROVE permits the separately recorded operational decision that the bus becomes the primary project interface.

Backup and restore

Create a consistent online backup:

project-bus-ops backup \
  --source /data/project-bus.db \
  --destination /secure/backup/project-bus-$(date +%Y%m%dT%H%M%S).db

The command uses SQLite's online backup API and runs PRAGMA integrity_check. Copy the backup off-host under the applicable retention policy.

Quarterly and before primary-interface activation:

1. restore a backup into an isolated instance;
2. start the exact reviewed application version against the restored database;
3. authenticate with a temporary test credential;
4. compare the restored maximum event cursor with the backup receipt;
5. run get_project, sync_since and list_pending_actions;
6. destroy the isolated restore instance and revoke the test credential.

Rotation and revocation

Static-token changes require a restart in v0.1. Generate a replacement, update the external secret configuration, restart, verify the new credential, then remove the old credential and restart again. Treat exposure as an incident; rotate first and investigate from the immutable event trail and edge logs.

Cursor recovery

Each consumer owns a durable cursor per project. When processing fails, retain the last successfully processed cursor and replay from it. Reads are safe to repeat; mutations require stable idempotency keys. Never advance a cursor before all returned events have been durably processed.

Rollback

Before the activation gate, stop the bus and return solely to SG/PTO/project threads; no authority has transferred. After activation, announce the incident in the fallback formal channels, stop writes, preserve the database and logs, restore the latest verified backup if required, and record reconciliation events when service resumes. Never delete or edit prior events.

Gate evidence checklist

• exact reviewed commit/image digest;
• healthy non-root container;
• two successful bootstrap runs with unchanged event cursor on replay;
• successful authenticated checks for every formal actor;
• backup receipt, restore result and matching event cursor;
• secret scan with no credential material in Git;
• independent Claude review report;
• PM ACCEPT gate event and explicit primary-interface operational decision.