Skip to content

Architecture

Jump to bottom
Nick Hamze edited this page Aug 31, 2026 · 5 revisions

Architecture

The two roles

Fleet does not introduce a new WordPress site type.

  • The hub is the WordPress install where Fleet for OpenStation is activated.
  • A managed site is any other WordPress install that has approved a connection from that hub.

The hub stores its site list in the current manager's user meta. The managed site stores no Fleet-specific record. Its only evidence of the relationship is a WordPress Application Password named Fleet for OpenStation on <hub-domain>.

Different managers on the same hub have separate site lists and credentials. A managed site can also approve more than one hub; WordPress treats each approval as a separate revocable Application Password.

Connection flow

  1. The manager enters a public HTTPS site URL on the hub.
  2. Fleet requests the target site's WordPress REST API index.
  3. The index advertises whether Application Passwords are available and provides the Core authorization endpoint.
  4. Fleet sends the manager to that endpoint with a short-lived state value and a callback URL on the hub.
  5. WordPress asks the target-site user to approve the connection.
  6. WordPress returns the site URL, username, and new Application Password to the hub callback.
  7. Fleet verifies that the response came from the expected origin, encrypts the credential, and introspects it through the target site's Core API.
  8. Fleet requests the target's Core Plugins endpoint and caches OpenStation's current state.

Rejected, invalid, expired, cross-origin, or unverifiable callbacks are not stored.

Installing OpenStation

Fleet first reads GET /wp/v2/plugins.

  • If OpenStation is missing, Fleet sends POST /wp/v2/plugins with the WordPress.org slug desktop-mode and an active status.
  • If OpenStation is installed but inactive, Fleet sends POST /wp/v2/plugins/desktop-mode/desktop-mode with an active status.
  • If OpenStation is already active, Fleet does nothing.

The target WordPress install performs the download, filesystem work, dependency checks, and activation. Fleet does not ship or upload its own copy of OpenStation.

Disconnecting

Fleet stores the UUID of the Application Password it is currently using. Disconnect sends DELETE /wp/v2/users/me/application-passwords/<uuid> to the managed site. The local connection is removed only after WordPress confirms revocation.

If the managed site is unreachable or refuses revocation, Fleet keeps the connection so the manager can retry instead of silently abandoning a working credential.

WordPress Core building blocks

  • Admin menu pages and forms
  • Capabilities and nonces
  • Application Password authorization, introspection, and deletion
  • User meta and transients
  • The safe HTTP API
  • The Plugins REST controller
  • WordPress's bundled sodium compatibility layer

Fleet adds orchestration and a small interface around these existing pieces. It does not duplicate them.

OpenStation integration

Fleet registers a standard top-level wp-admin page. OpenStation already presents WordPress admin pages as desktop windows, so the plugin needs no private OpenStation rendering API or separate JavaScript application.

The plugin declares Requires Plugins: desktop-mode. That makes OpenStation a Core-managed dependency on the hub. Managed sites do not install Fleet; Fleet installs ordinary OpenStation there through the Plugins REST API.

Clone this wiki locally