The Sandbox

The sandbox is a designated directory where AI agents can write PHP files that persist across requests. This page explains how it works, what it provides, and what it does not provide.

What is the sandbox?

The sandbox is the directory wp-content/novamira-sandbox/. When an AI agent uses the Write File ability to create a PHP file, the file can only be written to this directory. Non-PHP files (CSS, JS, JSON, etc.) can be written anywhere under ABSPATH.

PHP files placed in the sandbox are automatically loaded on every WordPress request by the Novamira sandbox loader, a must-use plugin. This means any PHP file written to the sandbox becomes active immediately, similar to a regular WordPress plugin.

Why the sandbox exists

The sandbox provides two things:

  1. Persistence: Code written to the sandbox survives across requests. Unlike Execute PHP (which uses eval() and is temporary), sandbox files are loaded on every page load. This is how AI agents create persistent functionality: custom post types, shortcodes, REST endpoints, cron jobs, and more.
  2. Organization: All AI-generated PHP files are in one place, making them easy to find, review, disable, or delete through the Novamira > Sandbox admin page.

What the sandbox is NOT

The sandbox is not a security boundary. This is important to understand:

  • Code running inside sandbox files has the same unrestricted access as any WordPress plugin. It can read and write any file, access the database, make network requests, and modify WordPress behavior in any way.
  • The Execute PHP ability runs code via eval() with full WordPress environment access, completely outside the sandbox. The sandbox restriction only applies to file writes, not to code execution.
  • The sandbox is a convenience guardrail that helps organize AI-written code, not a security mechanism that limits what AI agents can do.

Managing sandbox files

The Novamira > Sandbox page in the WordPress admin provides a file manager for sandbox files:

  • View: See all files in the sandbox with their status, size, and last modified date.
  • Disable: Appends .disabled to the filename. The file stays on disk but is no longer loaded by the sandbox loader. This is safer than deleting because you can re-enable it later.
  • Enable: Removes the .disabled suffix, making the file active again.
  • Delete: Permanently removes the file from disk.

AI agents can also manage sandbox files using the Disable File, Enable File, and Delete File abilities.

Sandbox loader

The sandbox loader runs as a must-use plugin. On every request, it:

  1. Checks if the sandbox directory exists.
  2. Finds all *.php files in the directory (files with .disabled suffix are skipped).
  3. Loads each file via require_once.

When AI abilities are enabled, the loader also performs crash detection to handle fatal errors from sandbox files.