Packages: Distribution Made Easy
Packages are mini-installer plugins that bundle Troy Client with your plugins. When someone installs a Package, they get everything in one step — no manual Troy Client installation required.
Packages also double as Composer metapackages. Bedrock and other Composer-managed WordPress sites can pull in your entire bundle with a single composer require.
Plugins vs Packages:
Plugins are for updates. Packages are for distribution.
- Use Plugins to serve updates to users who already have Troy Client.
- Use Packages to distribute your plugins to new users.
Packages always fetch the latest version of bundled plugins at install time. You don't need to rebuild Packages when you release plugin updates.
Why Use Packages?
Without a Package
- Your users must find and install Troy Client separately.
- Without it, users can't fetch updates from your repository.
- Large plugin ZIPs stall on slow connections and trigger lengthy OS anti-malware scans.
With a Package
- Troy Client is bundled and connects your users to your repository automatically.
- Updates flow automatically after a single install.
- Packages are under 10 KB — uploads pass even on spotty connections.
Creating a Package
Create a New Package Post
In your WordPress admin:
- Go to Repo Packages → Add New Package.
- A new Package post opens in the editor.
Set the Title and Slug
Enter a title for your Package (e.g., "My Plugin Suite Installer"). The title determines the installed plugin name and the namespace the Package installer uses. It also predefines the slug, but you can override that in the Package settings.
Set the slug (e.g., example-package). The slug appears in the download URL and the Composer package name.
Add Plugins
In the Plugins meta box:
- Click Add Plugin.
- Select plugins from your repository.
- Configure each plugin:
- Activate — Activate the plugin after installation. On by default.
- Network — Network-activate the plugin on multisite. Off by default — the package-level Network Activation setting can override this.
- Overwrite — Replace the plugin if it's already installed on the site. On by default — turn this off to skip plugins that are already present.
- Overwrite Troy — Replace the plugin even if another Troy Server already manages it. Off by default — enable this to take over management from another repository.
Configure Settings
In the Settings meta box:
| Setting | Description |
|---|---|
| Install Timeout | Maximum seconds the installer can run before timing out. Default: 30. |
| Deactivate on Completion | Deactivate the Package plugin after a successful install. On by default — disable only for testing. |
| Delete on Completion | Delete the Package plugin after a successful install. |
| Network Activation | Block prevents network activation. Activate All network-activates every bundled plugin. Require network-activates all bundled plugins and adds a Network: true header so WordPress enforces network-only activation. Default: Block. |
| Notice Severity | How much feedback the installer shows: Detailed (every step), Verbose (important messages), or Silent (minimal output). |
| Requires WP | Minimum WordPress version the Package requires. Default: 6.7. |
| Requires PHP | Minimum PHP version the Package requires. Default: 7.4. |
Don't Delete on Completion:
Recommended settings: Deactivate on completion, but don't delete. Your users can delete manually if they want, and WordPress Site Health will remind them. This keeps things tidy while leaving control in their hands.
Publish
Click Publish. Your Package is now available at:
https://repo.example.org/package/get/zip/example-package
How Packages Work
When someone activates your Package on their WordPress site:
-
Troy Client Installation
- The installer checks whether Troy Client is already present.
- If not, it downloads and installs Troy Client from the official repository.
- Troy Client is always installed first — it's a forced dependency.
-
Plugin Installation
- The installer fetches the latest version of each bundled plugin from your repository.
- Each plugin is installed and optionally activated.
- Existing plugins are overwritten or skipped based on your settings.
-
Cleanup
- The Package deactivates itself (if configured).
- The user can delete the Package afterward.
Packages include the Troy: disable-all-communications header. Once Troy Client is installed, this header hides the installer plugin from all external API requests — WordPress.org and other Troy Servers won't see it.
Why Troy Client Is Always Bundled:
Troy Client is a forced dependency. Without it, WordPress fetches plugin information from wordpress.org instead of your repository — opening the door to supply chain attacks or broken updates.
Package vs Plugin Lifecycle
| Aspect | Plugin | Package |
|---|---|---|
| Purpose | Serve updates. | Distribute your plugin bundle. |
| Troy Client | You install it yourself. | Bundled automatically. |
| Versioning | Each version is stored. | Always fetches latest at install time. |
| Rebuilding | Upload new ZIPs. | Only when the bundle contents change. |
| User action | Install, receive updates. | Install once, then delete the Package. |
Advanced Settings
Per-Plugin Configuration Options
For each plugin in a Package:
| Option | Default | Description |
|---|---|---|
| Activate | On | Activate the plugin after installation. |
| Network | Off | Network-activate the plugin on WordPress multisite. |
| Overwrite | On | Replace the plugin if it's already installed on the site. |
| Overwrite Troy | Off | Replace the plugin even if another Troy Server already manages it. |
Overwrite Behavior:
With Overwrite off, an existing plugin (even if inactive) blocks installation. The default is on — leave it that way unless you have a reason not to.
Notice Severity Levels
Control how much feedback your users see during installation:
| Level | Behavior |
|---|---|
| Detailed | Logs every installation step and result. Best for debugging. |
| Verbose | Logs important messages only. Recommended for most Packages. |
| Silent | Minimal output — your users won't see what was installed. |
Distributing Packages
Share instructions like these on your website — adapt the plugin names and download link to match your Package:
Install via WordPress
1. Download the installer ZIP file from here.
2. Log in to your WordPress dashboard.
3. Go to Plugins → Add New.
4. Click "Upload Plugin" at the top.
5. Upload the ZIP file you downloaded.
6. Activate the plugin.
7. The installer sets up [my plugins] and Troy Client
(the update delivery plugin). You can delete the installer
afterward.
The download URL for your Package looks like:
https://repo.example.org/package/get/zip/example-package
Updating Packages
Packages fetch the latest version of each bundled plugin at install time — you don't need to rebuild them for every plugin update.
Rebuild your Package when:
- Adding or removing plugins from the bundle.
- Changing plugin configuration (activate, overwrite, etc.).
- Updating Package metadata (name, description, author).
- A new Troy Server version introduces installer improvements.
Composer users pick up the changes automatically — the metapackage always reflects the current bundle contents.
To rebuild: Open the Package in the editor and click Update. The ZIP is regenerated automatically. Bumping the version number is optional — it's purely decorative since the Package is a throwaway installer, not a versioned deliverable.
Next Steps
- Connect GitHub for automatic plugin updates.
- Read the API docs for programmatic access.
- Learn about Composer integration for dependency-managed WordPress sites.
