🧪 Drupal Sandbox (Controlled-Mutation Boundary)

Optional. Disabled by default. drupal-sandbox is a separate safety boundary, not a runtime rung. It provides opaque database snapshots and disposable-clone lifecycle operations so that update-hook and config-import execution evidence can be gathered against an isolated, throwaway database — never against a shared or production target.

[!IMPORTANT] Installing this server does not enable it. Every mutation tool refuses to run unless .drupal-sandbox.json explicitly sets "enabled": true and the resolved target is allowlisted and of class local/disposable. Turning it on for a real project is a separate, explicit decision.

🧰 Tools (5)

| Tool | Gated? | Purpose | |---|---|---| | inspect_sandbox_state | No | Report ownership, target fingerprint, timestamps, retention, and restore eligibility. Read-only. | | create_snapshot | No (but rejects shared/production) | Write an opaque gzipped dump to the protected artifact area. Never returns or reads SQL. | | create_disposable_clone | Hard gate | Create an isolated clone (sandbox_id) in a dedicated disposable database. | | restore_disposable_clone | Hard gate | Restore a service-owned clone from a service-owned snapshot. | | destroy_disposable_clone | Hard gate | Destroy a clone. Requires explicit confirm_target (the target fingerprint). |

🔒 Safety model

• Hard gate: create_disposable_clone, restore_disposable_clone, and destroy_disposable_clone return SANDBOX_DISABLED unless enabled: true, and TARGET_NOT_ALLOWLISTED / TARGET_CLASS_PROHIBITED for targets that are absent or not local/disposable. This is a refusal, not a warning.
• Ownership: restore/destroy only act on sandboxes and snapshots created and fingerprinted by this service (SANDBOX_NOT_OWNED / SNAPSHOT_NOT_OWNED / FINGERPRINT_MISMATCH otherwise).
• Explicit destroy confirmation: destroy_disposable_clone requires confirm_target to equal the sandbox target fingerprint.
• Opaque dumps: snapshots are written via drush sql:dump --gzip --result-file=...; SQL contents are never read back or returned.
• Isolation: clones target a dedicated database_key (a $databases['<key>'] connection in settings.php). Without one, mutation tools return DRIVER_UNSUPPORTED rather than touching the default database.

⚙️ Configuration

Copy .drupal-sandbox.example.json to .drupal-sandbox.json at your project root. It ships with "enabled": false:

{
  "enabled": false,
  "artifact_dir": ".agent-forge/artifacts/drupal-sandbox",
  "retention_days": 7,
  "allowed_targets": [
    {
      "id": "local-disposable",
      "class": "disposable",
      "uri": "https://my-project.lndo.site",
      "database_key": "sandbox"
    }
  ]
}

• class must be local or disposable. shared and production are always rejected.
• database_key must name a dedicated disposable database connection in your settings — this is the database that clones are materialized into and dropped from.

🚀 Installation

npm install -g @drupal-forge/server-sandbox

{
  "mcpServers": {
    "drupal-sandbox": {
      "command": "npx",
      "args": ["-y", "@drupal-forge/server-sandbox"]
    }
  }
}

Requires Drush available in the target environment (local vendor/bin/drush, or via lando / ddev).