Get started

This is an archived copy of the SandyWP docs. It is kept online as a fallback and may be out of date. The maintained documentation lives at docs.sandywp.com.

Plugin Library

The Plugin Library keeps the plugins you reach for again and again, such as premium plugins you buy as ZIPs or your own private plugins on GitHub. Once a plugin is in the library, you or your AI agent can install it on any ready sandbox by its name, without hunting for the file. You can also store each plugin's license key, so an agent can activate the license for you.

The library belongs to your workspace. Installing from it needs the permission to deploy plugins; adding, replacing, or removing plugins and license keys needs the same permission as Templates and Blueprints.

Add a plugin

Open Plugins in the app and click Add plugin.

  • Upload ZIP. Choose the plugin ZIP (up to 50 MB). The name defaults to the file name. Uploading again under the same name replaces the stored ZIP, so updating a premium plugin is one upload. The stored license key is kept.
  • GitHub release. Pick a repository SandyWP's GitHub App can read. Every install checks the repository's latest published release and uses its .zip asset, so sandboxes always get the newest version.
For GitHub, attach the built plugin ZIP to each release. SandyWP uses the only .zip asset, or the one named <repository>.zip when a release has several. GitHub's automatic "Source code" archives are never used: their folder name changes with every tag, which WordPress would treat as a new plugin.

To give the GitHub App access to a repository, open Account → GitHub. See GitHub.

Install a plugin

From the dashboard, click Install next to a plugin and choose a ready sandbox. The plugin is installed and activated.

From an AI agent connected to the SandyWP MCP server, just ask, for example "install gravityforms on my-shop". The agent calls sandywp_list_plugin_library to find the name and sandywp_deploy_plugin with libraryPlugin to install it. The agent never needs the ZIP file.

From the CLI:

sandywp library add ./gravityforms.zip --name gravityforms
sandywp library add --github acme/acme-pro
sandywp library list
sandywp deploy my-shop --library gravityforms

From the API, send { "libraryPlugin": "gravityforms" } to POST /api/app/sites/:id/deploy-plugin.

License keys

Premium plugins usually need a license key before they update or unlock features. Save the key next to the plugin once, and your AI agent can fetch it and activate the license on the sandbox after installing the plugin. SandyWP itself does nothing with the key: it only keeps it safe until an agent asks for it.

To add a key, open the plugin's actions menu on Plugins and choose Set license key (or Replace license key), or paste it into the optional License key field while adding the plugin. The same dialog removes it. From the CLI:

sandywp library license gravityforms --set "$GF_LICENSE_KEY"
sandywp library license gravityforms --clear

Pass the key from an environment variable or a secret manager, as above, so it does not end up in your shell history.

When you ask an agent to "install gravityforms on my-shop and activate the license", it installs the plugin with sandywp_deploy_plugin, reads the key with sandywp_get_plugin_license, and activates it the way that plugin expects, for example with the plugin's WP-CLI command or its settings screen.

Only add keys for plugins you are licensed to use in your workspace, and check that the license allows activation on test or staging sites.

Security

  • Encrypted at rest. Keys are encrypted with AES-256-GCM before they are stored. They are never stored in plain text.
  • Write-only where you manage them. The dashboard, the API, and the CLI never show a saved key, only whether one is stored and its last four characters, for example ••••ABCD. Keys shorter than 12 characters show no characters at all.
  • A separate permission for agents. Reading a key needs the licenses:read permission, which you approve when you connect an agent. An agent that can install library plugins cannot read their keys without it. Agents connected before this permission existed must reconnect to get it.
  • Every read is recorded. Each time an agent reads a key, SandyWP records who read it, with which connection, when, and for which plugin in your workspace audit log. The Plugins page shows when an agent last read each key.
Once an agent reads a key, it is in that agent's chat transcript, and once the plugin is activated, it is stored in the sandbox's WordPress database. Anyone who can open that sandbox or its wp-admin can read it there. Do not share sandboxes with activated licenses through public template launch links, and delete them when you are done.

Next steps