# Constile for WordPress The Constile plugin serves the Constile offer to AI agents that fetch your articles for a person. People, search engines, and crawlers get your pages as usual. The plugin bundles the PHP gate from `integrations/php`. ## Install 1. Download `constile-wordpress-0.6.0.zip` from your site page in the Constile dashboard. 2. In WordPress, go to **Plugins > Add New > Upload Plugin**, choose the zip, and select **Install Now**. Then select **Activate**. 3. Go to **Settings > Constile**. Enter the site id, the site secret, and the network URL from your site page, and select **Save Changes**. 4. Select **Check install**. The plugin checks the settings, your site's registered domain, the seller file, that its own requests reach WordPress (a 200 HTML page, with their bypass header), and page caches. Then the network checks the install itself: it sends a one-time code to your site's `/.well-known/constile`, and the plugin confirms it with the site's credentials. The network URL must start with `https://`, so the site secret never crosses the internet in the clear. WordPress multisite isn't supported yet. On a multisite network, only a super admin can set the network URL and the connect URL. WordPress in a subdirectory (a home URL such as `https://www.example.com/blog/`) isn't supported either: the network checks `/.well-known/constile` at your domain's root, which that WordPress doesn't serve. The install check says so. The plugin needs PHP 8.1 or later. It was tested on WordPress 6.9 and 7.1. To keep the secret out of the database, set it in `wp-config.php` instead. The settings page then shows that it's set there: ```php define('CONSTILE_SITE_ID', 'site_...'); define('CONSTILE_SITE_SECRET', '...'); define('CONSTILE_NETWORK_URL', 'https://network.example.com'); ``` ## Settings | Setting | What it does | |---|---| | Site id, Site secret, Network URL | Connect the site to Constile. The page shows only the last four characters of the saved secret. To keep the saved secret, leave the field empty. | | Trusted proxies | Addresses or ranges (such as `10.0.0.0/8`) of a load balancer or CDN in front of WordPress. The plugin reads the visitor's address from `X-Forwarded-For` only when a request comes from one of them. Otherwise it uses `REMOTE_ADDR`. | | Turn the gate off | Sends every request to WordPress unchanged, and nothing to the network, from the next request on. If you can't reach the settings page, add `define('CONSTILE_DISABLED', true);` to `wp-config.php`, or deactivate the plugin. | | Connect URL | Where the plugin connects to fetch your own pages, such as `http://127.0.0.1`, when the server can't reach its public address or a CDN blocks its requests. It changes only where the plugin connects: the plugin still sends your registered domain as the host name. Only `http://` and `https://` work. | If Apache's `mod_remoteip` or nginx's `realip` module rewrites `REMOTE_ADDR`, the plugin uses the address they set. The official WordPress Docker image turns on `mod_remoteip` and trusts `X-Forwarded-For` from every private address. If visitors can reach that container from a private network, narrow its `RemoteIPInternalProxy` list. ## Paywalled content Gate 0.6.0 and later can fetch a paywalled article with the release instructions the network sends, so an agent gets the full text and the offer fits it. The network gives the gate a page address on your site's own host and, optionally, headers to send: `Cookie`, `Authorization`, `Constile-Paywall-Key`, or a header starting with `X-`. The gate ignores an address on another host and drops other headers. It strips `Set-Cookie` from what it releases and never logs the headers. To set up a method, open your site's page in the dashboard and choose a content API, a paywall rule, or a Constile login. A paywalled page gets offers only after the method works and the gate is 0.6.0 or later. ## Page caches A page cache answers before WordPress loads, so it would give an agent the cached article instead of the offer. The plugin registers the agent user-agent tokens from the network as "don't cache" in four cache plugins, and updates them hourly and whenever the network's list changes: | Cache plugin | What the plugin changes | |---|---| | WP Super Cache | Its rejected user agents, plus a file it loads before it serves a cached page. WP Super Cache checks rejected user agents only when it stores a page, so without that file it would still serve cached pages to agents. In Expert mode, the plugin also adds a rewrite condition to `.htaccess`. | | W3 Total Cache | Page Cache > Rejected user agents (`pgcache.reject.ua`). | | LiteSpeed Cache | Excludes > Do Not Cache User Agents (`cache-exc_useragents`), which LiteSpeed also writes to `.htaccess`. | | WP Rocket | The `rocket_cache_reject_ua` filter, then its config file and `.htaccess` are regenerated. | Other page caches (WP Fastest Cache, WP-Optimize, Cache Enabler, and Breeze, or any `wp-content/advanced-cache.php` the four above didn't install) can't be configured by the plugin. When one is active, the settings page and the install check name it. Exclude the agent tokens in its own settings. Cache plugins match user agents only. In two cases a cached page can still reach an agent: agents that sign their requests (Web Bot Auth) with an ordinary browser user agent, and, when your site offers to clients that aren't browsers, those clients. WP Super Cache in its default mode is the exception: the plugin's file checks both. Every response the plugin makes (offers, callbacks, and releases) sends `Cache-Control: no-store` and tells each cache plugin not to store it. ### Host caches Some hosts run their own cache in front of WordPress, which the plugin can't configure. The settings page lists the agent tokens to exclude and what to ask each host: - **WP Engine**: open a support ticket and ask to bypass the page cache for the agent tokens. WP Engine's own cache exclusions match paths and query strings, not user agents, and its Varnish cache overrides `Cache-Control`. Do this before your site goes live with offers. - **Kinsta**: ask support for a cache bypass rule for the agent tokens. If Edge Caching is on, ask whether the rule covers it. - **SiteGround**: turn on Browser-Specific Caching in Speed Optimizer, then flush the Dynamic Cache. - **Cloudways**: ask support for a Varnish rule for the agent tokens, or turn Varnish off for the application. To test a host cache, request an article with an agent user agent, such as `curl -A "ChatGPT-User/1.0" https://www.example.com/an-article/`, and check that you get the offer. ## How it works - The plugin runs on `plugins_loaded`, before WordPress parses the request. It answers `/.well-known/constile` and `/sponsored/*` before WordPress would route them to a 404, and answers an agent before the theme renders anything. - For an agent, it gets the page with a self-fetch: it requests the same path from your site's registered domain, which the network's config names, with a `Constile-Gate-Bypass` header carrying a random value made when you activate the plugin. A request with that value goes straight to WordPress, ungated. Releases use the same header. - The self-fetch never uses `home_url()`. Some hosts (Bitnami's images, for one) build it from the request's `Host` header, which a visitor can forge. - At most two self-fetches run at once across the server's PHP processes, for at most 3 seconds each, so agents can't tie up a small server. When none is free, the agent gets the page without an offer. To change the limit, use the `constile_max_self_fetches` filter. - If a WAF or CDN strips `Constile-Gate-Bypass`, the self-fetch still can't loop: while it's in flight, the same request arriving without the header passes through ungated. The install check reports a stripped header. - The plugin uses a self-fetch, not output buffering. Anything that flushes output early (a theme, a plugin, a cache plugin's own buffer) would send the status and headers before the gate could replace them. A cache plugin whose buffer wraps the plugin's could also store the offer as the page for everyone. - If the self-fetch doesn't return the page (a CDN or firewall in the way, a redirect, or a 404), WordPress serves the request itself, as if the gate weren't there. - The plugin handles only requests for your registered domain (or its `www.` twin), and passes every other request to WordPress ungated. - When the network can't be reached, the plugin serves your pages as usual. It keeps using the last config for up to a day, fetching a new one after the response. The config call waits at most 3 seconds and other network calls 5, and after a failed config fetch it stops asking for 30 seconds. - A page passed through to an agent keeps its exact bytes, in its own charset. ## Run the test You need Docker. The test builds the zip, installs it in WordPress the way **Upload Plugin** does, and checks offers, callbacks, the bypass, forged hosts, trusted proxies, the self-fetch limit and loop guard, a forged `Host` and `X-Forwarded-Host` with a Bitnami-style `WP_HOME`, the settings page, the install check, and unsupported cache plugins. It also turns on WP Super Cache and W3 Total Cache and checks that neither serves a cached page to an agent, and checks the settings the plugin writes to LiteSpeed Cache: ```sh integrations/wordpress/tests/run.sh ``` To leave the containers running afterward, set `KEEP=1`. To test another WordPress image, set `WP_IMAGE`, such as `WP_IMAGE=wordpress:php8.1-apache`.