Agency hub Agency plan

Agency · The agency hub is part of the Agency plan (and its free trial). Plans

The agency hub turns one of your sites into the control room for your clients' sites. From it you can:

• push a snippet, a folder or a selection to any of them, and switch it on there,
• see where each snippet runs, and which version,
• roll back, switch off or remove a snippet on one site,
• keep an eye on every site's health: versions, snippets with errors, safe mode.

There's no cloud service in between. The hub is a normal WordPress site with Snipfire Pro on the Agency plan, and it talks to your clients' Snipfire directly, over their REST API, with WordPress application passwords.

What you need #

• On the hub: Snipfire Pro on the Agency plan (or its trial), and full Snipfire access as an administrator (super admin on multisite). Team access can't give the hub to anyone else.
• On each client site: Snipfire (free is enough; Snipfire Pro is optional), and an administrator's login.
• HTTPS on the client sites: WordPress only offers application passwords over HTTPS on live sites, and the hub only connects over HTTPS (plain HTTP only when the hub itself is a local or development site).
• For the health overview, Snipfire 0.17 or later on the client. Pushing works with older versions too.

Add a client site #

In the editor, click Sites at the bottom of the sidebar, then Add a site. Type the Site address, then either:

• Connect with WordPress (easiest): you're sent to the client site, log in there if needed, and approve Snipfire Hub. WordPress then sends the hub its own application password and brings you back. Nothing to copy.
• or use an application password: on the client site, go to Users → Profile → Application passwords, make one (name it "Snipfire Hub"), and paste it with the User name on that site. Click Test and add site.

Before storing anything, the hub checks that it can reach the site and that the user has full Snipfire access there (administrators do). The application password is stored encrypted on the hub and never shown or sent to a browser again.

The Sites view #

Each site shows:

Refresh all asks every site now; Check asks one. The hub also checks all of them twice a day in the background (with WP-Cron). Opening the view doesn't make any requests: it shows what the hub last saw, until you refresh.

Click a site to see the Snippets from the hub on it: each one's version, whether it's on, and when it was last pushed, with Where is it running?, Roll back, Switch off and Remove.

Push snippets #

Choose what to push:

• Ticked snippets: Push to sites… in the bulk actions bar.
• A folder: the ⇪ button on its row (Push folder "…" to sites…).
• One snippet: ⋯ → Push to sites….

Then choose the sites (or All sites), and tick Switch on after pushing if you want them running straight away. Click Push.

• On each site, the snippet goes through that site's own checks, and switching it on test-loads that site, exactly as when you save it there. A snippet that fails there stays off, and the report says why.
• New snippets arrive switched off unless you ticked Switch on after pushing; snippets already on a site stay on or off as they are.
• The hub finds a snippet on each site by its permanent ID (uid), so renaming it on either side doesn't matter. Its folder and tags come along for new snippets.
• Every push is recorded in the activity log of the hub and of the client site (as Agency hub).

A copy changed on the site #

If someone changed the snippet on a client site since the hub last pushed it there, the hub never overwrites it without asking. The push report lists it: Some sites changed these snippets since they were last pushed: choose which version to keep. Pick Keep the site's or Overwrite with this version, then Apply choices. The version not kept stays in the snippet's history on the site.

Where is it running? #

⋯ → Where is it running? lists every site for one snippet:

Versions compare the code and the settings, not whether it's on or off, its folder or its tags.

From here you can push this version to a site, or Roll back… on one site:

• Previous version: puts back the version before the one the hub pushed, from the snippet's history on the hub (or pick A version from the history),
• Switch it off there,
• Remove it from the site (it's deleted there, with its history on that site; it stays on the hub).

Remove a site #

Remove on a site forgets it and its application password. The snippets stay on the site. The hub can't revoke the password for you: on the client site, go to Users → Profile and revoke the Snipfire Hub application password.

Security #

• Only administrators with full Snipfire access on the hub can use it (super admins on multisite).
• Application passwords are stored encrypted, with the same key as the secrets vault (SNIPFIRE_SECRETS_KEY, or the site's salts). If that key changes, the sites show Connect again. Passwords never appear in the editor, the REST API, the activity log or error messages.
• The hub only connects to public web addresses: over HTTPS, with TLS certificates checked, no redirects followed, and never to private, loopback or cloud metadata addresses. A local or development hub may also use HTTP and reach sites on private addresses, for testing.
• With Connect with WordPress, the new password travels back to the hub in the address WordPress redirects to (that's how WordPress's authorization works), so it can appear in the hub's web server access log. The hub moves on straight away, so it doesn't stay in your browser's address bar.

What is sent #

• To a client site, when you push: the snippet's code and settings (type, where and when it runs, conditions, settings form fields and values), with its permanent uid, and for a new snippet the hub's folder and tags. Nothing about your other client sites.
• From a client site: its status for the Sites view (GET /snipfire/v1/status: WordPress, PHP and Snipfire versions, snippet counts, recorded errors, safe mode and the safety switches; never code or secrets), and the pushed snippets' code and settings to compare versions.
• With every request: the hub's address in an X-Snipfire-Hub header. It's only a label: the client shows the change in its activity log as via hub with that address; the request is checked like any other, with the application password.

Good to know #

• SCSS and LESS partials pushed to other sites should be imported by title, not by ID (@use '12'): IDs differ from site to site.
• Client sites without Snipfire Pro work too: Pro settings (testing mode, cookie consent…) arrive and stay safely off there, as usual.
• Pushes and checks go through the sites one after the other: fine for dozens of sites.
• Developers can change the time the hub waits for each site (15 seconds by default) with the snipfire_hub_timeout filter.
• A client on a very old Snipfire that gives a pushed snippet a different uid can't be followed; the push report says so. Health checks need Snipfire 0.17 or later on the client.
• Deleting Snipfire Pro on the hub forgets every connected site and its password (deactivating doesn't). See Uninstalling Pro.

From the command line #

wp snipfire hub add https://client.example --username=admin --password="abcd efgh ijkl mnop qrst uvwx"
wp snipfire hub sites                         # the sites and what the hub last saw
wp snipfire hub status --refresh              # health, asked now
wp snipfire hub push 12,14 --sites=all --on   # push two snippets and switch them on
wp snipfire hub push --folder=Shared --sites=2,3 --overwrite
wp snipfire hub where 12                      # where snippet 12 runs
wp snipfire hub rollback 12 --site=3          # the previous version on site 3
wp snipfire hub remove 3

See WP-CLI and the REST API.