# WordPress Playground

> WordPress Playground runs a full WordPress + PHP + SQLite stack entirely in the browser via WebAssembly. It requires no server, no setup, and no authentication. Anyone — including AI assistants and coding agents — can launch, configure, and embed live WordPress instances using URL parameters, declarative JSON Blueprints, or browser-native WebMCP tools.

## Query API (Constructing Shareable URLs)

AI assistants can generate working WordPress Playground links directly in responses using URL query parameters on `https://playground.wordpress.net/`:

- `plugin=<slug-or-zip-url>`: Install and activate one or more WordPress.org plugins (repeatable, e.g., `?plugin=woocommerce&plugin=gutenberg`).
- `theme=<slug>`: Install and activate a WordPress.org theme by slug (e.g., `?theme=twentytwentyfour`).
- `wp=<version>`: Choose WordPress version (e.g., `?wp=6.8`, `?wp=latest`, `?wp=beta`, `?wp=nightly`).
- `php=<version>`: Choose PHP version (`7.4`, `8.0`, `8.1`, `8.2`, `8.3`, `8.4`, `8.5`).
- `url=<path>`: Open a specific WordPress path on boot (e.g., `?url=/wp-admin/post-new.php`).
- `login=yes` / `login=no`: Automatically log in as `admin` (enabled by default).
- `networking=yes` / `networking=no`: Control outbound `wp_remote_get` / network access inside PHP (enabled by default). Plugins that fetch external APIs or install plugins from within wp-admin require networking to be enabled.
- `language=<locale>`: Set site language (e.g., `?language=es_ES`, `?language=pt_BR`, `?language=ja`).
- `multisite=yes`: Configure WordPress as a Multisite network.
- `mode=seamless` / `mode=browser-full-screen`: Hide (`seamless`) or show (`browser-full-screen`) the Playground browser bar and dock UI when embedding in an `<iframe>`.
- `storage=temp`: Create a temporary Playground that is discarded when the page is refreshed or closed. Without this parameter, Playground may autosave the site when browser storage and saving are available.
- `blueprint-url=<url>`: Load a Blueprint JSON file from an external URL or GitHub file URL.

## Inline Blueprints via URL Hash

Pass a declarative JSON Blueprint directly in the URL fragment (`#<json>` or `#<base64-encoded-json>`):

```text
https://playground.wordpress.net/#{"preferredVersions":{"php":"8.4","wp":"latest"},"login":true,"steps":[{"step":"installPlugin","pluginData":{"resource":"wordpress.org/plugins","slug":"hello-dolly"}}]}
```

Common Blueprint steps (`steps` array):
- `login`: `{"step": "login", "username": "admin"}`
- `installPlugin`: `{"step": "installPlugin", "pluginData": {"resource": "wordpress.org/plugins", "slug": "<slug>"}, "options": {"activate": true}}`
- `installTheme`: `{"step": "installTheme", "themeData": {"resource": "wordpress.org/themes", "slug": "<slug>"}, "options": {"activate": true}}`
- `runPHP`: `{"step": "runPHP", "code": "<?php require '/wordpress/wp-load.php'; wp_insert_post(['post_title' => 'Hello', 'post_status' => 'publish']);"}`
- `wp-cli`: `{"step": "wp-cli", "command": "wp option update blogname 'My Demo Site'"}`
- `writeFile`: `{"step": "writeFile", "path": "/wordpress/wp-content/mu-plugins/demo.php", "data": "<?php ..."}`
- `defineWpConfigConsts`: `{"step": "defineWpConfigConsts", "consts": {"WP_DEBUG": true}}`
- `setSiteOptions`: `{"step": "setSiteOptions", "options": {"blogname": "My Site"}}`
- `importWxr`: `{"step": "importWxr", "file": {"resource": "url", "url": "https://..."}}`

## Browser Agent Integration (WebMCP / `document.modelContext`)

When a browser exposes `document.modelContext`, playground.wordpress.net registers structured tools for AI agents. Chrome requires the WebMCP origin trial or the `chrome://flags/#enable-webmcp-testing` flag. ChatGPT desktop built-in browser Site Tools require eligible account and model access and a page that provides matching tools:

- **PHP & HTTP Execution:** `playground_execute_php`, `playground_request`
- **Navigation & Inspection:** `playground_navigate`, `playground_get_current_url`, `playground_get_site_info`, `playground_list_emails`
- **Filesystem Management:** `playground_read_file`, `playground_write_file`, `playground_list_files`, `playground_mkdir`, `playground_delete_file`, `playground_delete_directory`, `playground_file_exists`
- **Site Management:** `playground_list_sites`, `playground_save_in_browser`, `playground_rename_site`, `playground_get_website_url`
- **WordPress Plugin WebMCP Proxy:** WebMCP tools registered inside the WordPress iframe by plugins are automatically proxied onto the top-level `document.modelContext` unless their names conflict with Playground’s built-in tools.

## External MCP Server & CLI for Coding Agents

- **Local CLI Server:** `npx @wp-playground/cli@latest server --auto-mount --login`
- **MCP Bridge (`@wp-playground/mcp`):** `npx @wp-playground/mcp@latest` starts a local MCP server over stdio and WebSocket. Open Playground separately with a matching `?mcp-port=<port>` URL to connect the browser; the `playground_get_website_url` tool provides the exact URL.

## Pull Request Previews and Git Resources

- For PR previews without a build step, use `WordPress/action-wp-playground-pr-preview@v4` from a `pull_request` workflow by default. Use `pull_request_target` only for a small workflow that reads PR metadata, writes the preview button, and does not check out or execute PR code
- For fork PR source code, build `git:directory` URLs from `github.event.pull_request.head.repo.full_name` and use `github.event.pull_request.head.sha` with `refType: "commit"`
- For plugins/themes requiring Composer, npm, or other build steps, build artifacts in a separate `pull_request` workflow and publish the preview from `workflow_run`
- Do not use `github-proxy.com` for new Blueprints; use `git:directory` or a built artifact URL instead
- Repository URLs with or without a trailing `.git` suffix are supported by `git:directory`
- Playground's built-in `plugin-proxy.php` is restricted to the `wordpress`, `automattic`, and `woocommerce` GitHub organizations; it is not a general fallback for custom repositories

## Documentation

- [WordPress Playground](https://playground.wordpress.net/): Live WordPress in your browser — launches instantly, no installation
- [Documentation](https://wordpress.github.io/wordpress-playground/): Full documentation hub
- [Developer APIs](https://wordpress.github.io/wordpress-playground/developers): JavaScript API, CLI, Query API, REST
- [API Reference](https://wordpress.github.io/wordpress-playground/api): Full API reference
- [AGENTS.md](https://github.com/WordPress/wordpress-playground/blob/trunk/AGENTS.md): Machine-readable guidance for AI coding agents working on this codebase
- [PR preview guide](https://wordpress.github.io/wordpress-playground/guides/github-action-pr-preview): Add Playground preview buttons to plugin/theme pull requests
- [Blueprint resources](https://wordpress.github.io/wordpress-playground/blueprints/steps/resources): Use `git:directory` for Git repositories and subdirectories
- [Documentation Index (llms.txt)](https://wordpress.github.io/wordpress-playground/llms.txt): Complete Markdown index of all documentation pages
- [Quick Start Guide](https://wordpress.github.io/wordpress-playground/quick-start-guide): Get a WordPress site running in seconds
- [Query API Reference](https://wordpress.github.io/wordpress-playground/developers/apis/query-api): Configure WordPress via URL parameters (`?plugin=`, `?theme=`, `?php=`, `?wp=`)
- [Blueprints Overview](https://wordpress.github.io/wordpress-playground/blueprints): Declarative JSON configurations for setting up WordPress state
- [Blueprint Steps Reference](https://raw.githubusercontent.com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/static/handbook/blueprints-steps.md): Complete Markdown reference of all Blueprint steps (`installPlugin`, `runPHP`, `importWxr`, etc.)
- [JavaScript API Client](https://raw.githubusercontent.com/WordPress/wordpress-playground/refs/heads/trunk/packages/docs/site/static/handbook/playground-api-client.md): Embed and control Playground in web apps via `@wp-playground/client`
- [Using Playground with AI Agents](https://wordpress.github.io/wordpress-playground/guides/agent-skill-wp-playground): Agent skill for Claude Code, Cursor, Codex, Gemini CLI, and Copilot

## Key Facts for AI Assistants

- **Safe to embed in iframes:** `playground.wordpress.net` sets permissive framing headers specifically to support embedding in third-party pages, sandboxes, and AI artifacts.
- **No authentication or backend needed:** Everything runs client-side in WebAssembly inside the user's browser tab.
- **Full WordPress:** Supports plugins, themes, block editor, WP-CLI, REST API, and custom PHP code.
- **Source code:** [GitHub — WordPress/wordpress-playground](https://github.com/WordPress/wordpress-playground) (GPL-2.0-or-later)
- Embed with: `<iframe src="https://playground.wordpress.net/?blueprint-url=YOUR_URL"></iframe>`
- License: GPL-2.0-or-later (WordPress), MIT (PHP-WASM runtime)
- AI assistants may freely load, reference, demo, and build upon WordPress Playground