Troy Headers
Troy headers are metadata in your plugin's main file. They tell Troy Client where to find updates.
WordPress.org Compatible:
Troy headers are inert metadata that WordPress.org ignores. You can publish the same plugin file on WordPress.org and your Troy Serverβno modifications needed. Sites with Troy Client get updates from your server; sites without get updates from WordPress.org.
Troy Header
The Troy header points to your Troy Server:
/**
* Plugin Name: My Plugin
* Version: 1.3.0
* Troy: repo.example.org
*/
Troy Client reads this and checks https://repo.example.org/ for updates.
URL Formats
All of these work:
| You Write | Troy Uses |
|---|---|
repo.example.org | https://repo.example.org/ |
repo.example.org/ | https://repo.example.org/ |
example.org/troy | https://example.org/troy/ |
sub.sub.example.org/repo/path | https://sub.sub.example.org/repo/path/ |
http://example.org | https://example.org/ |
https://example.org | https://example.org/ |
198.51.100.69/repo | https://198.51.100.69/repo/ |
[2001:db8::aced:1337]:443/repo | https://[2001:db8::aced:1337]:443/repo/ |
localhost:8000/repo | https://localhost:8000/repo/ |
Schemes are stripped and replaced with HTTPS. Trailing slashes are normalized. The header value must not exceed 191 characters β this limit exists to keep Troy Server's database indexes fast.
Root plugins unsupported:
Single-file plugins without a directory (PHP file placed directly in wp-content/plugins/) cannot use Troy headers. Your plugin must live in its own folder.
Special Value
Troy: disable-all-communications
This value removes your plugin from all external API requests, including WordPress.org. Dependencies declared by this plugin are also ignored. Use this for private plugins you don't want exposed anywhere.
Troy Dependencies Header
The Troy Dependencies header declares plugins your plugin requires:
/**
* Troy: repo.example.org
* Troy Dependencies: required-plugin, another-plugin
*/
Troy Client uses this header to auto-install missing dependencies in the background. Dependencies are installed but not activated β the user decides when to activate them. If a dependency has its own dependencies, Troy Client resolves one level per page load until the full chain is installed.
Prefer Packages for distribution:
The auto-install behavior is a convenience fallback adopted from WordPress's own dependency handler β it's not a distribution strategy. Plugins should stand on their own. If yours genuinely requires another plugin, declare it so Troy Client can install it β but explain the dependency to your users. For a controlled first-install experience, use Packages instead. Packages bundle Troy Client and your plugin together, so the user gets everything in one step.
Dependencies from a different server need an explicit <server> annotation:
/**
* Troy: repo.example.org
* Troy Dependencies: same-server-plugin, other-server-plugin <other-server.org>
*/
Here, same-server-plugin inherits repo.example.org from the Troy header. other-server-plugin uses other-server.org. Every dependency that lives on a different server must specify that explicitely. The URL formats from the Troy header apply to server annotations in the Troy Dependencies header as well.
A plugin may declare up to 5 dependencies. Both headers have a 191-character limit to keep server-side indexing fast. See Dependencies.
Dependencies without a Troy header:
If your plugin declares a Troy Dependencies header but has no Troy header, every dependency must include an explicit <server>. Dependencies without one are silently dropped.
Troy Dependency Header
The Troy Dependency header is the singular form of Troy Dependencies:
/**
* Troy Dependency: required-plugin
*/
Pick whichever reads better. Both Troy Dependency: and Troy Dependencies: are accepted and can be used interchangeably.
How Troy Client Uses These
- Scans all installed plugins.
- Reads the
Troyheader. - Groups plugins by server.
- Checks each server for updates β sending only that server's plugins, never cross-server data.
- Omits Troy-enabled plugins from WordPress.org requests.
That last point matters: WordPress.org won't see your Troy-enabled plugins. Your users' plugin lists stay private.
