The Sandbox
The SproutOS sandbox gives your AI a safe place to write and test PHP - isolated from your core files, auto-validated, and crash-guarded.
When your AI writes PHP, it doesn't go straight into your theme or plugin files. It goes into a dedicated sandbox folder (wp-content/sproutos-mcp-sandbox/) where it's validated, loaded automatically, and easy to disable if something goes wrong.
This keeps AI-generated code separate from everything else on your site - and gives you full control over what runs.
Isolated Folder
AI-generated PHP lives in wp-content/sproutos-mcp-sandbox/ — completely separate from your theme and plugin files.
Crash Guard
Fatal errors auto-disable the broken file and activate Safe Mode. The rest of your site keeps running untouched.
File Controls
Enable, disable, review, or delete individual PHP files at any time from SproutOS > Sandbox.
Sandbox vs PHP Execution
Two separate features. The sandbox persists files that auto-load. PHP Execution runs code directly in WordPress.
Here's how to set up and manage your sandbox.
The sandbox is disabled by default. You need to turn it on before your AI can write PHP files. PHP execution (sprout/execute-php) is a separate feature - see What's the difference between the Sandbox and PHP Execution? below.
How do I enable the Sandbox?
Open SproutOS Settings
In your WordPress admin, go to SproutOS > Settings.
Enable the sandbox
Find the Sandbox toggle and turn it on. Save your settings.
Confirm it's active
A Sandbox tab now appears in your SproutOS admin panel. This is where you manage all AI-generated PHP files.
How do I manage sandbox files?
Once the sandbox is enabled, every PHP file your AI writes appears in SproutOS > Sandbox. From there you can:
- Enable or disable individual files - a disabled file stays on disk but stops loading
- Review file content before re-enabling anything that was auto-disabled
- Delete files you no longer need
Files load automatically on every WordPress request the moment they're enabled. Disabling one takes effect immediately on the next request.
How do I disable a sandbox file?
If a file is causing problems or you want to pause it:
Go to the Sandbox tab
Navigate to SproutOS > Sandbox.
Find the file
Locate the file in the list. Active files show a green status indicator.
Disable it
Click Disable. The file is renamed with a .disabled extension and stops loading immediately. It stays on disk - nothing is deleted.
To re-enable it, click Enable from the same screen.
What happens if a PHP file crashes?
If a sandbox file causes a fatal PHP error, SproutOS handles it automatically:
- The broken file is disabled (
.disabledextension added) - Safe Mode activates - your AI can read but cannot write until you review
- All other sandbox files keep running normally
- Nothing is deleted
You review the file in SproutOS > Sandbox, fix or remove it, then turn Safe Mode off to resume normal operation.
Crash Guard means one bad snippet can't take down your site. Each file is isolated - a fatal error in one file doesn't affect the others.
What's the difference between the Sandbox and PHP Execution?
These are two separate features that work differently:
| Sandbox | PHP Execution | |
|---|---|---|
| What it does | AI writes PHP files that auto-load | AI runs PHP code directly in WordPress |
| How to enable | SproutOS > Settings > Sandbox toggle | Enabled by default in GitHub version |
| Availability | GitHub + WordPress.org | GitHub version only |
| Use case | Persistent snippets and custom functionality | Testing, debugging, one-off queries |
Both are available in the GitHub version. PHP execution (sprout/execute-php) is disabled in the WordPress.org build.
Frequently Asked Questions
No. The sandbox is a completely separate directory (wp-content/sproutos-mcp-sandbox/). Your AI never writes PHP directly into theme or plugin folders - only into the sandbox.
The files stay on disk but stop loading - SproutOS's sandbox loader is what includes them on each request. Reactivating the plugin restores normal sandbox behavior.
Yes. Click any file in SproutOS > Sandbox to view its content before enabling or disabling it.
Yes. SproutOS runs PHP tokenizer validation and symbol conflict detection before saving any file. Malformed code is rejected before it ever reaches the sandbox.