Pursae Docs
Pursae docs

From install to your first plugin, it is all here.

Everything you need to install, run and extend Pursae. Pick a topic or search above.

Getting started

From zero to a running site

What Pursae is, what it needs, how to install it with Docker or as a single binary, how the first-run installer works and how updates and rollbacks are handled.

What is Pursae

Pursae is WordPress core rewritten in Go. It ships as one static binary that talks to a PostgreSQL database and serves the familiar WordPress admin (/wp-admin/), the block editor, the wp/v2 REST API, classic themes and a page builder. Plugins are WebAssembly packages that run in a sandbox with the permissions you grant at activation, so a broken plugin cannot take the site down or read what it was not allowed to.

  • Admin — Dashboard, Posts, Pages, Media, Comments, Appearance (Themes, Customize, Widgets, Menus, Theme File Editor), Plugins, Users, Tools, Settings; same markup and CSS as WordPress.
  • Editors — the block editor (Pursae Editor, built on the @wordpress/* packages) and a built-in Classic Editor plugin (TinyMCE).
  • Pursae Web Builder — a section-based visual page builder that publishes pages as static HTML; off on a fresh install.
  • REST API — wp/v2 with cookie + nonce and Application Password authentication.
  • Themes — bundled themes plus code-free theme packages uploaded as a zip.
  • Pursae Cache — a built-in full-page cache with tag-based purging.
  • System — migrations on start, a job runner for scheduled events and e-mail, WXR import/export.
  • 18 built-in plugins — Commerce, Web Builder, SEO, Cache, Security, CDN, Headless, Cookie, Pixel, Analytics, Forum, SMTP, Custom Fields, Multi Language, Contact Form, Maintenance, Backup Manager, Classic Editor. All are off on a fresh install except Pursae Cache and Classic Editor.

Architecture

  • One static binary (CGO_ENABLED=0) with the admin, the editors and the bundled themes embedded.
  • gin for HTTP, pgx on PostgreSQL 17 (14+ works); migrations run on start.
  • Plugins run as WebAssembly in wazero — no cgo, no separate runtime.
Not supported PHP plugins and PHP themes (themes are Go templates with a theme.json manifest), and multisite.

Source: getting-started/index.md, README.md

Requirements

Docker routeBinary route
RuntimeDocker Desktop or Docker Engine + Compose v2 (plus git and make for the quick start)Go 1.27 to build; nothing else to run
Databasestarted by compose (PostgreSQL 17)PostgreSQL 14 or newer (17 is what compose uses) that the user can create tables in
Memory512 MB is comfortablesame
Ports8088 for the site (127.0.0.1 in production), 5432 for PostgreSQL (127.0.0.1, development only)whatever WPGO_ADDR says (default :8080)

Pursae runs on Linux, macOS and Windows (amd64 and arm64). The Docker image is based on Alpine and runs as an unprivileged user.

Install with Docker

You need Docker (Docker Desktop on macOS/Windows, Docker Engine with Compose v2 on Linux) and git; make is optional.

On a server (production build)

The production build talks to https://hub.pursae.com, so core updates are one click in Dashboard › Updates. Settings go in docker/.env (git-ignored).

git clone https://github.com/pursae/pursae.git
cd pursae
cp docker/.env.example docker/.env   # set WPGO_DB_PASSWORD, WPGO_SITE_URL (https://…), WPGO_SMTP_*, WPGO_MAIL_FROM
make prod-up                         # site on 127.0.0.1:8088; point Caddy or nginx at it

Without make:

docker compose --env-file docker/.env -f docker/compose.yaml -f docker/compose.prod.yaml up -d --build

make prod-logs follows the log, make prod-down stops the stack (data is kept). Put a TLS proxy in front, then open the https:// address.

Run the installer right away. Until the installer is finished, anyone who reaches the site can run it and become its administrator.

On your machine (development build)

git clone https://github.com/pursae/pursae.git
cd pursae
make docker-up
# without make:
docker compose -f docker/compose.yaml up -d --build

This development build does not talk to hub.pursae.com (no core updates; it looks for a local Pursae Manager instead), uses the test database password wpgo and trusts the demo plugin signing key. Use it to try Pursae, not to run a site. The first build downloads Go modules and compiles the binary (a minute or two); then open http://localhost:8088 and you land on the installer.

ServiceWhat it isHost port
wpgothe Pursae server8088 (production: 127.0.0.1:8088)
dbPostgreSQL 17127.0.0.1:5432 (production: not published)

Another port or address

The site URL is written into the settings at install time, so set it before the first run:

WPGO_PORT=9000 WPGO_SITE_URL=http://localhost:9000 make docker-up
# reach it from another device on your LAN:
WPGO_SITE_URL=http://192.168.1.50:8088 make docker-up

Installed with the wrong URL already? Change it under Settings › General or start over (see Troubleshooting).

Volumes

Compose keeps state in named volumes, so docker compose down loses nothing.

VolumeMounted atContains
pgdata/var/lib/postgresql/datathe database
bin/data/binthe running binary; Dashboard › Updates replaces it
uploads/data/uploadsmedia library files
plugins/data/pluginsinstalled plugin packages
themes/data/themestheme packages and files edited in the Theme File Editor
pagecache/data/wpgo-cachePursae Cache disk copy (can be rebuilt)
languages/data/languagesdownloaded language packs
backups/data/backupsTools › Backups archives (scheduled and manual)
mail/data/mail.eml files of messages sent without SMTP

Everyday commands

make docker-up            # development: build and start in the background
make docker-down          # stop; data is kept
make prod-up              # production: with docker/compose.prod.yaml and docker/.env
make prod-down            # stop the production stack (data is kept)
make prod-logs            # follow the production server log
make test                 # unit tests + PostgreSQL integration tests
make docker-test          # the same suite inside a Go container
make build                # compile bin/wpgo
make builder              # rebuild the Web Builder editor into web/web-builder (needs Node 22+)
docker compose -f docker/compose.yaml logs -f wpgo
docker compose -f docker/compose.yaml restart wpgo
Demo signing key The compose file sets WPGO_TRUST_DEV_KEY=1 so the bundled example plugins install. That is for development only: make prod-up adds docker/compose.prod.yaml, which turns it off.

Source: install-docker.md, GUIDE.md

Install the binary

You need Go 1.27 and a PostgreSQL database (14 or newer; the compose file uses 17) that the configured user can create tables in.

Build

git clone https://github.com/pursae/pursae.git
cd pursae
make build                # writes bin/wpgo

make build is CGO_ENABLED=0 go build -o bin/wpgo ./cmd/wpgo: a static binary with the admin, the editors and the bundled themes embedded. Copy it anywhere.

Run

export DATABASE_URL='postgres://wpgo:wpgo@localhost:5432/wpgo?sslmode=disable'
export WPGO_SITE_URL='https://blog.example.com'   # the public address, without a trailing slash
export WPGO_UPLOADS_DIR=/var/lib/wpgo/uploads
./bin/wpgo serve

On start the server runs the database migrations (under an advisory lock, so several instances can start at once), creates the uploads directory and listens on WPGO_ADDR (default :8080). Open the site and the installer appears.

CommandDoes
wpgo servemigrate, then serve (the default)
wpgo migrateapply pending migrations and exit
wpgo versionprint the version

Other subcommands referenced in the docs: wpgo launch (the Docker entrypoint), wpgo healthcheck / wpgo healthcheck ready, wpgo mcp (MCP stdio bridge) and wpgo adminsec disable-hide-login.

Development mode

Read templates, CSS and JS from the working tree instead of the embedded copy, so edits show on refresh:

make db                                  # starts only PostgreSQL from the compose file
WPGO_WEB_DIR=web go run ./cmd/wpgo serve

make dev does both. make test runs the unit tests and the PostgreSQL integration tests against the compose database, one package at a time; they drop and recreate the database TEST_DB names (default wpgo_test), so give each checkout running tests at once its own, e.g. make test TEST_DB=wpgo_test_feature.

The variables you set first

VariableDefaultPurpose
DATABASE_URLpostgres://wpgo:wpgo@localhost:5432/wpgo?sslmode=disablePostgreSQL connection string
WPGO_ADDR:8080listen address
WPGO_SITE_URLhttp://localhost:8080public URL, written to the settings at install
WPGO_UPLOADS_DIR./data/uploadsmedia uploads; plugins, themes, the plugin cache and mail go next to it
WPGO_SECRETgeneratedsigning secret for sessions and nonces
WPGO_SMTP_HOST …—outgoing mail; without it messages become .eml files

The full list is in the Configuration article below; a systemd unit is in Reverse proxy & TLS.

Source: install-binary.md

Your first site

The installer

Until the site is installed every request redirects to /wp-admin/install — the same five-minute install as WordPress:

  1. Site title
  2. Username and password of the first administrator
  3. Email of that administrator
  4. whether to ask search engines not to index the site

The installer creates the "Hello world!" post with its first comment, the Sample Page, a draft Privacy Policy page and the default sidebar widgets. Then sign in at /wp-login.

No .php needed Admin URLs have no .php suffix (/wp-admin/edit, /wp-login). WordPress spellings (/wp-admin/edit.php, /wp-login.php) still work: GET requests redirect permanently and POSTs are served in place, so bookmarks, clients and tutorials keep working.

The admin

MenuNotes
Posts, Pages, Media, Commentsthe block editor opens by default; switch to the Classic Editor under Settings › Writing
AppearanceThemes (with Live Preview), Customize, Widgets, Menus, Theme File Editor; Add Theme uploads theme packages
PluginsInstalled Plugins, Add Plugin (marketplace, upload); activating a plugin shows the permissions it asks for
Usersroles administrator, editor, author, contributor, subscriber, with per-user capability overrides
ToolsImport and Export (WXR), Site Health, personal data export and erasure
SettingsGeneral, Writing, Reading, Discussion, Media, Permalinks, Privacy, plus pages plugins add
Pursae Cachethe built-in page cache

Write a post

Posts › Add New opens the block editor. Write, add media (the Media Library modal is the real wp.media), pick categories and tags, then Publish. The post appears on the front page with the active theme and in the REST API at /wp-json/wp/v2/posts. Plugin shortcodes such as [gopher-facts] can be typed in a Shortcode block or a paragraph; the plugin expands them at render time.

Pretty permalinks

Settings › Permalinks offers the WordPress structures (/%year%/%monthnum%/%postname%/, /%postname%/, …). No web-server rewrite rules are needed: the Go server routes them itself.

Next steps

  • Install a theme: Appearance › Themes › Add Theme.
  • Install a plugin: Plugins › Add Plugin, or upload a package.
  • Put the site behind TLS (see Reverse proxy & TLS).
  • Coming from WordPress: export with Tools › Export (WXR) there, import with Tools › Import here — posts, pages, terms, comments, menus, and media fetched from their public URLs. Products move with WooCommerce's product CSV. Users' passwords, settings, PHP plugins and themes do not move.

Source: first-site.md

Upgrading

A production site updates itself from Dashboard › Updates in one click; when a newer release exists, every admin page says Pursae X is available! Please update now. Otherwise you replace the binary (or rebuild the image) and start it. Development builds (make docker-up, make dev) get no updates from https://hub.pursae.com. Database migrations run automatically on start, before the server listens.

What a one-click update does

When Pursae Manager publishes a release built for the site's platform (core.artifacts in GET /api/v1/index has the running GOOS/GOARCH), Dashboard › Updates shows Update to version X. The site then:

  1. downloads the binary from the Manager (at most 1 GB), checking its size and SHA-256;
  2. verifies the Ed25519 signature by the Manager key named in the release over pursae-core-v1\n{version}\n{os}-{arch}\n{sha256 hex};
  3. runs the downloaded binary once (version): a binary this system cannot start, or one that reports another version, is refused while nothing has changed;
  4. keeps the running binary as <executable>.prev, records the update in <executable>.update.json and renames the new binary over the old one;
  5. shows Updated, restarting…, records a core_update event and re-executes itself; the new version runs its migrations on start.

The restart does not drop visitors: the listening socket is handed to the new binary (WPGO_LISTEN_FD), in-flight requests finish first (up to 10 seconds), and new connections wait in the kernel queue until the new version accepts them — a second or two, no error page, also behind a proxy such as Traefik in Dokploy.

Automatic rollback

The new binary confirms the update once it answers requests (within two minutes); until then .update.json stays pending. If it dies first and is started again — by Docker's restart: unless-stopped, systemd's Restart=always or another supervisor — the second start puts <executable>.prev back and runs it, and Dashboard › Updates says Pursae X did not start, so the site went back to Y. If re-executing fails outright, the previous binary is put back at once.

Run under a supervisor Without one, nothing restarts a crashed process. Migrations are forward-only: a rolled-back site keeps any migration the new version applied, which is why releases only add schema.

Keeping and reinstalling the previous version

  • Once confirmed, .update.json records confirmed (with the version the site came from) and <executable>.prev is kept for 24 hours, then removed (checked at start and every hour). A site never holds more than one extra binary, and only for a day.
  • Dashboard › Updates › Previous version offers Reinstall version Y: within 24 hours the kept .prev is checked and swapped back (no download); later the signed build of Y is downloaded again from Pursae Manager (GET /api/v1/core/{version}) and verified like an update. Without a Manager the button is hidden once .prev is gone.
  • A reinstall is recorded as a pending update, so a reinstalled binary that does not start goes back too. It never happens on its own; migrations of the newer version are not undone (the button asks for confirmation) — restore a backup when the older version cannot work with them.
  • Nothing is replaced when a check fails. The button is replaced by the reason when the executable cannot be replaced (a go run build, or a directory the server may not write). Beta releases are offered only to sites whose license includes the beta channel.

Static release builds

CGO_ENABLED=0 go build -buildmode=exe -tags nodynamic -ldflags "-X wpgo/internal/server.Version=0.2.0" ./cmd/wpgo

make build and make release do this. Static matters: Go's default Linux build asks for the build host's ELF interpreter, and nodynamic keeps the AVIF decoder off purego — such a binary built on a glibc machine does not start in the Alpine image.

Docker

The image starts with wpgo launch: it installs its binary into the bin volume (/data/bin, WPGO_BIN_DIR) and runs it from there, so an admin update survives container restarts. A newer image wins when its binary reports a higher version; a rebuilt image with the same version (development builds without VERSION) also wins when its binary differs; an installed binary with a higher version (an admin update) is kept.

git pull && make prod-up     # production from source; migrations run on start
git pull && make docker-up   # development stack

Binary

git pull
make build
systemctl restart wpgo    # or however you run it

Several instances may start at once: the migration runner takes a PostgreSQL advisory lock and applies missing migrations once. wpgo migrate applies them without serving, handy in a deploy step.

Before you upgrade

  1. Back up the database and the uploads directory. Migrations are forward-only; the backup is your rollback.
  2. Read the release notes (shown on Dashboard › Updates when connected to the Hub).
  3. Check plugin compatibility: a plugin's plugin.json names the minimum core version (requires); the Plugins screen refuses to activate one that needs a newer core.

Manual rollback

Stop the new version, restore the database backup, start the previous binary. Uploads, plugin packages and theme packages are plain files and are not changed by an upgrade.

Plugins and themes

Update packages through Plugins › Add Plugin and Appearance › Add Theme (upload a newer package or install from the marketplace). Re-installing a plugin with the same slug replaces the package and keeps the granted permissions; deactivate and activate it to load the new version, and review the permissions on the activation screen.

Source: upgrading.md

Upgrade notes for recent releases

Web Builder: Theme Builder and Hello Pursae

Headers, footers and single, page, custom post type, front page, archive, search and 404 templates are designed in Web Builder › Theme Builder and shown by the new bundled theme Hello Pursae. Migration 0029_web_builder_templates.sql adds the wb_template post type; nothing existing changes.

  • Sites with the plugin already on are not switched: a one-time Switch to Hello Pursae (or Dismiss) notice appears. From now on, activating the plugin switches to Hello Pursae (with a Switch back link) and deactivating switches back.
  • Older builder pages with their own navigation or footer section keep rendering as full-page canvases; each page can choose under Header & footer in its page settings.
  • The builder's API version is now 2: an editor tab left open across the upgrade asks to reload. Published pages need no regeneration.
  • Public Pursae Custom Fields post types now have pretty permalinks (/<slug>/<post>/) and optional archives; old ?p=<id> links redirect. Check that no page or post reuses a custom post type's rewrite or archive slug.

New Pursae Web Builder (old builder data is deleted)

Back up the database first. The release that brings the new builder replaces the previous Elementor-derived builder and deletes everything it stored, with no converter (migration 0028_drop_old_builder). Restoring the backup is the only way back.

Deleted: its tables (revisions, global classes and variables, default styles, form submissions), saved templates, theme parts, popups and components, every _elementor_*/_gwe_* post meta key, its options and the themes saved with it. Pages keep their content as plain HTML; pages on the old Canvas or Full Width template go back to the theme's default template. Generated CSS, form uploads and custom icon sets are removed from uploads at the next start (local fonts stay); a site on Hello Web Builder or a theme saved with the old builder moves to its previous theme or Twenty Twenty-Five. Old builder pages open in the new builder as new documents — rebuild and publish them.

Operations

Running Pursae in production

Every environment variable, the Docker setup, proxies and TLS, caching, scheduled jobs, mail, backups, security, the Hub connection, releases, troubleshooting and AI agents over MCP.

Configuration: core and database

Pursae is configured entirely through environment variables. Everything else (site title, permalinks, mail sender, cache settings, trusted plugin keys) lives in the options table and is edited in the admin.

Core

VariableDefaultMeaning
DATABASE_URLpostgres://wpgo:wpgo@localhost:5432/wpgo?sslmode=disablePostgreSQL connection string (pgx URL format)
WPGO_ADDR:8080address the HTTP server listens on
WPGO_SITE_URLhttp://localhost:8080public URL without a trailing slash; written to the siteurl and home options by the installer
WPGO_UPLOADS_DIR./data/uploadsmedia library files. Next to it: plugins (../plugins), compiled-plugin cache (../plugin-cache), themes (../themes) and development mail (../mail)
WPGO_SECRETgenerated on first start, stored in the settingssecret for session cookies and nonces. Set it when several instances share one database
WPGO_WEB_DIRembeddedread admin/theme templates, CSS and JS from this directory, reloading per request (development)
WPGO_EMPTY_TRASH_DAYS30days trashed posts and comments are kept before the daily wp_scheduled_delete job removes them. 0 empties the trash at every daily run (Trash links stay visible)
WPGO_LOG_FORMATtextjson writes the access log as one JSON object per request (status, method, uri, duration, ip, request_id)
WPGO_BACKUPS_DIRbackups/ next to uploadsBackup Manager archives (manual, scheduled, safety snapshots). Keep it outside the publicly served uploads
WPGO_LANG_DIRlanguages/ next to uploadsinstalled language packs
WPGO_TRANSLATIONS_APIhttps://api.wordpress.org/translationswhere language packs are downloaded from (a mirror, or a fake in tests)
WPGO_BIN_DIR— (/data/bin in the image)persistent directory wpgo launch installs the binary into, so admin updates survive container restarts
WPGO_LISTEN_FD—internal: set when the socket is handed to an updated binary; do not set it yourself
WPGO_PLUGINS_DIR— (../plugins next to uploads)plugin packages directory; every instance needs the same volume (mentioned on the Docker page)

Database pool

DATABASE_URL takes pgx pool parameters as query parameters; each one left out gets the default below (pgx alone would allow only max(4, CPUs) connections).

ParameterDefaultMeaning
pool_max_conns4 × CPUs, at least 10, at most 40connections per instance. Keep the sum over all instances (plus backups and psql) under PostgreSQL's max_connections (100 by default)
pool_min_conns2connections kept open when idle
pool_max_conn_lifetime1h (+ up to 5 min jitter)a connection is replaced after this long
pool_max_conn_idle_time15midle connections above the minimum are closed after this long
pool_health_check_period30show often idle connections are checked
DATABASE_URL=postgres://wpgo:secret@db:5432/wpgo?sslmode=disable&pool_max_conns=20

Source: operations/configuration.md

Configuration: themes, plugins and the Hub

VariableDefaultMeaning
WPGO_THEMES_DIR<data>/themestheme packages (<slug>/theme.json) and overrides saved by the Theme File Editor
WPGO_THEME_LIBRARY_DIR— (library comes from the Hub)serve Add Themes › Library from a local directory of theme packages (development, offline sites; the repository's is library/themes). Hub downloads are cached in theme-library-cache/ next to uploads
WPGO_DISALLOW_FILE_EDIToff1/true makes the Theme File Editor read-only (like DISALLOW_FILE_EDIT)
WPGO_PLUGIN_KEYS—comma-separated base64 Ed25519 public keys trusted to sign plugin packages, in addition to the plugin_trusted_keys option
WPGO_MARKET_DIRexamples/plugins/dist, then /usr/share/wpgo/pluginsa directory of .zip packages offered on Plugins › Add Plugin
WPGO_TRUST_DEV_KEYunset (1 in compose)trust the dev-key.pub in the market directory. Development only
WPGO_EXPOSE_USERSunset1 lets visitors list accounts (public REST users, /?author=N, users sitemap); off because those routes disclose account names
WPGO_TRUSTED_PROXIESloopback and private rangesproxies (comma-separated IPs or CIDRs) whose X-Forwarded-For / X-Real-IP is believed; none trusts no proxy
WPGO_HUBunset (on)off switches Pursae Manager (hub.pursae.com) off in any build: nothing is sent, and no update notices, one-click updates, marketplace or licenses. Every admin page warns until removed and restarted. Not recommended
WPGO_DEV_HUB_URLunset (http://pursae-manager.test:8090 in the development compose file)devhub builds only: the Manager to use instead of https://hub.pursae.com (https, or http on localhost / *.localhost / *.test); off disables it. Production binaries ignore it
WPGO_TRUST_HUB_KEYSunset (1 in the development compose file)devhub builds only: 1 trusts every key the Manager lists, endorsed by the release root or not. Production binaries ignore it

Pursae Manager and devhub builds

Every Pursae install talks to Pursae Manager at https://hub.pursae.com. A production binary has no variable or option that changes this address or relaxes key checking: the Pursae release root key is pinned in it, and only Manager keys endorsed by that root verify core self-updates and Manager-signed plugins. The ROOT_KEYS build arg (-ldflags -X wpgo/internal/server.rootKeysLinked=…) adds release roots for a key rotation; it never removes the pinned one.

go run -tags devhub ./cmd/wpgo serve        # make dev does this
docker compose -f docker/compose.yaml up    # builds with GO_TAGS=devhub

A devhub binary reads WPGO_DEV_HUB_URL (pursae-manager.test is an extra_hosts alias for the host gateway) and WPGO_TRUST_HUB_KEYS=1, so a local Manager's throwaway key verifies releases and plugins. The production compose file builds with GO_TAGS="" and drops both variables.

Never ship a devhub binary.

Editing theme files

Appearance › Theme File Editor works without recompiling. Saving writes an override into /data/themes (or WPGO_THEMES_DIR); the template set is re-parsed and the page test-rendered. A template or render error is rolled back automatically and shown. Restore original removes the override.

Configuration: content, built-in plugins, compose and tests

Content

VariableDefaultMeaning
WPGO_POST_REVISIONS25revisions kept per post (WordPress' WP_POST_REVISIONS); older ones are deleted on save, Web Builder publishes included. Negative keeps every revision. Tools › Revisions deletes the excess of existing posts

Post search stems words in the site language (Settings › General › Site Language → the PostgreSQL text search configuration, e.g. english, turkish; simple when there is none). Changing the language rebuilds the vectors in the background.

Built-in plugins

VariableDefaultMeaning
WPGO_ADMINSEC_DISABLE_HIDE_LOGINunsetrecovery switch for Pursae Security's custom login URL: 1/true/yes brings /wp-login back while set (restart after setting). wpgo adminsec disable-hide-login turns the setting off for good
WPGO_CDN_SETTINGSunsetPursae CDN settings as one JSON object (keys of the gocdn_settings option, e.g. {"provider":"aws","bucket":"media",…}). Overrides saved settings and shows read-only, so credentials stay out of the database. Invalid JSON is ignored with a log warning

The WPGO_BUILDER_AI* variables in internal/webbuilder/contract.go belong to the Web Builder AI module, which is not shipped; setting them has no effect.

Compose only

make prod-up reads these, WPGO_SITE_URL, the mail settings and WPGO_PLUGIN_KEYS / WPGO_TRUSTED_PROXIES from docker/.env (template: docker/.env.example).

VariableDefaultMeaning
WPGO_PORT8088host port for the site
WPGO_BIND127.0.0.1host address the site is published on, with compose.prod.yaml only (the development file publishes on every interface)
WPGO_DB_PORT5432host port for PostgreSQL on 127.0.0.1, development file only; production does not publish PostgreSQL
WPGO_DB_PASSWORD— (required)database password, compose.prod.yaml only (the development file uses wpgo); applied when the pgdata volume is created

Test suite

VariableDefaultMeaning
WPGO_TEST_ADMIN_DB—connection used to drop and recreate the test database
WPGO_TEST_DB—test database URL; both unset skips the integration tests
TEST_DB (make variable)wpgo_testdatabase make test drops and recreates
WPGO_I18N_MISSES—development: append every untranslated UI string to this file (JSON lines); WPGO_I18N_MISSES_* are read by the i18n coverage tests only

Options worth knowing (database, not env)

OptionWhereMeaning
plugin_trusted_keys—newline- or comma-separated public keys, merged with WPGO_PLUGIN_KEYS
plugin_allow_unsigned—true accepts unsigned plugin packages (development only)
wpgo_cache_*, wpgo_opt_*Pursae Cache screenspage cache and page optimisation
image_output_formatSettings › Media"" (default): JPEG sizes for WebP uploads (PNG with transparency); webp: WebP sizes for WebP uploads; webp-all: WebP for JPEG, PNG and WebP uploads, the image itself saved as WebP (photo.jpg → photo.webp, or photo-scaled.webp above 2560 px). Quality 86, no cgo. Filter: image_editor_output_format. Existing images are not regenerated
pursae_license_keySettings › Licensethe license key sent to the Hub

Docker

The image

docker/Dockerfile is a two-stage build: golang:1.27-alpine compiles a static binary; the final stage is alpine:3.22 with ca-certificates and tzdata, an unprivileged user wpgo (uid 10001) and the data directories /data/uploads, /data/plugins, /data/plugin-cache, /data/mail, /data/themes, /data/wpgo-cache, /data/languages, /data/bin and /data/backups. Entrypoint wpgo launch, default command serve, exposed port 8080. Example plugin packages from examples/plugins/dist are copied to /usr/share/wpgo/plugins if they exist.

docker build -f docker/Dockerfile -t wpgo:local .
docker run --rm -p 8080:8080 \
  -e DATABASE_URL='postgres://wpgo:wpgo@db:5432/wpgo?sslmode=disable' \
  -e WPGO_SITE_URL=https://blog.example.com \
  -e WPGO_UPLOADS_DIR=/data/uploads \
  -v wpgo-uploads:/data/uploads -v wpgo-plugins:/data/plugins -v wpgo-themes:/data/themes \
  wpgo:local

compose.yaml

ServicePurpose
dbpostgres:17-alpine, database wpgo, user and password wpgo, health-checked with pg_isready, published on 127.0.0.1:${WPGO_DB_PORT:-5432}
wpgothe site, built from the Dockerfile (GO_TAGS=devhub), waits for a healthy database, restart: unless-stopped
testprofile test: runs go test ./... -p 1 in a Go container against the same database (make docker-test)
DATABASE_URL: postgres://wpgo:wpgo@db:5432/wpgo?sslmode=disable
WPGO_SITE_URL: ${WPGO_SITE_URL:-http://localhost:8088}
WPGO_UPLOADS_DIR: /data/uploads
WPGO_TRUST_DEV_KEY: ${WPGO_TRUST_DEV_KEY:-1}   # demo only
WPGO_DEV_HUB_URL: ${WPGO_DEV_HUB_URL:-http://pursae-manager.test:8090}   # devhub builds only
WPGO_TRUST_HUB_KEYS: ${WPGO_TRUST_HUB_KEYS:-1}                           # devhub builds only
WPGO_TRUSTED_PROXIES: ${WPGO_TRUSTED_PROXIES:-}
WPGO_SMTP_HOST: ${WPGO_SMTP_HOST:-}      # without a host: .eml files in /data/mail
WPGO_SMTP_PORT: ${WPGO_SMTP_PORT:-587}
WPGO_SMTP_USER: ${WPGO_SMTP_USER:-}
WPGO_SMTP_PASS: ${WPGO_SMTP_PASS:-}
WPGO_MAIL_FROM: ${WPGO_MAIL_FROM:-}

Add anything else from the configuration reference to the environment, for example WPGO_PLUGIN_KEYS.

Production changes (compose.prod.yaml)

make prod-up adds compose.prod.yaml with settings from docker/.env. It refuses to start until WPGO_DB_PASSWORD and WPGO_SITE_URL are set, and:

  • builds without the devhub tag (updates only from https://hub.pursae.com; WPGO_DEV_HUB_URL / WPGO_TRUST_HUB_KEYS removed);
  • takes the database password from WPGO_DB_PASSWORD (for POSTGRES_PASSWORD and DATABASE_URL);
  • does not publish PostgreSQL; publishes the site on 127.0.0.1:8088 only (WPGO_BIND changes the address);
  • sets WPGO_TRUST_DEV_KEY=0, passes WPGO_PLUGIN_KEYS and WPGO_TRUSTED_PROXIES through, restarts both services unless stopped and sets stop_grace_period: 35s.
Changing the DB password POSTGRES_PASSWORD only applies when the pgdata volume is first created; on an existing database change it first with ALTER USER wpgo PASSWORD '...'.

Production checklist

  • Put a TLS-terminating proxy in front and set WPGO_SITE_URL to the https:// address.
  • Finish the installer right after the site goes live.
  • For real plugins list your own signing keys in WPGO_PLUGIN_KEYS.
  • Configure SMTP (WPGO_SMTP_*, WPGO_MAIL_FROM) so password resets are delivered.
  • Back up pgdata, uploads, plugins and themes; copy the backups volume off the server.
  • Set WPGO_SECRET explicitly if you run more than one wpgo replica.
  • Update from Dashboard › Updates; pick a strong admin password.

Health checks

EndpointAnswers 200 whenUse it for
GET /healthzthe process serves HTTP (database not touched)liveness: Docker HEALTHCHECK, Kubernetes livenessProbe
GET /readyzthe database answers a ping within 2 s and every migration is applied; 503 otherwisereadiness: load balancers, Kubernetes readinessProbe

Both are unauthenticated, answer before maintenance mode, Pursae Security and the page cache, send Cache-Control: no-store and are not logged. The image's HEALTHCHECK runs wpgo healthcheck (asks /healthz on WPGO_ADDR; wpgo healthcheck ready asks /readyz), so no curl is needed.

Shutdown, timeouts and limits

  • On SIGTERM: stop accepting, let in-flight requests finish (up to 10 s), stop the job runner (up to 10 s), drain background writes — 404 log, counters, pending CDN purges (up to 5 s) — then close the pool. Docker's default grace is 10 s, hence stop_grace_period: 35s; use the same for terminationGracePeriodSeconds.
  • Request headers: 10 s; idle keep-alive: 120 s; a request body with no progress for 60 s fails. No overall read/write timeout (backups, imports, slow uploads and Headless subscription streams run for minutes) — put per-request limits in the proxy.
  • Request body limit: 512 MB (the largest upload a screen accepts is a 256 MB WXR import); the Backup Manager import takes archives up to 16 GB. Larger bodies get 413.
  • Every response carries an X-Request-ID (the proxy's when sane, else generated); the access log line ends with id=<request id>.

Logs, restarts and several instances

docker compose -f docker/compose.yaml logs -f wpgo   # production: make prod-logs
docker compose -f docker/compose.yaml restart wpgo

The wpgo service has restart: unless-stopped (it also brings back a core update that did not start); compose.prod.yaml adds it to db too. Instances sharing one database compare the plugins table with what they loaded every 10 seconds; plugin packages live in WPGO_PLUGINS_DIR, so every instance needs the same volume.

Source: operations/docker.md

Reverse proxy and TLS

Pursae serves plain HTTP. Terminate TLS in a proxy and set WPGO_SITE_URL to the public https:// address (or change Settings › General after installing). The server trusts X-Forwarded-Proto: https to treat a request as secure: it then sets Strict-Transport-Security and secure cookies, and generates https:// links.

Visitor IPs and trusted proxies

Send X-Forwarded-For so login throttling, the comment flood check, the Pursae Security IP block list, the maintenance IP whitelist and the logs see the visitor's address. It is believed only from a trusted proxy: by default loopback and private ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, ::1, fc00::/7). If your proxy has a public address, list it in WPGO_TRUSTED_PROXIES; none trusts no proxy.

Why it matters Without a trusted proxy, every visitor shares the proxy's address and five failed logins from one visitor lock everybody out for 15 minutes. Conversely, any machine on the trusted private networks that reaches the port directly could pick its own address — publish the port only where the proxy can reach it, or set WPGO_TRUSTED_PROXIES to exactly your proxy. With an https:// site URL and no WPGO_TRUSTED_PROXIES, the server logs a reminder at start-up.

Sub-requests of /batch/v1 cannot set X-Forwarded-*, X-Real-IP or Forwarded themselves; they carry the outer request's headers.

Caddy

blog.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy sets the forwarded headers, obtains certificates and passes WebSocket upgrades on its own.

nginx

server {
    listen 443 ssl http2;
    server_name blog.example.com;
    ssl_certificate     /etc/letsencrypt/live/blog.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/blog.example.com/privkey.pem;
    client_max_body_size 64m;          # media uploads

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Host              $host;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Real-IP         $remote_addr;
    }
}
server {
    listen 80;
    server_name blog.example.com;
    return 301 https://$host$request_uri;
}

Static files (/wp-includes/, /wp-admin/css/, theme and plugin assets) are served by the binary with long cache headers, so no root or try_files is needed. nginx may cache them in a proxy_cache; Pursae Cache can emit X-Accel-Expires for whole pages.

GraphQL subscriptions (Pursae Headless)

Subscriptions are delivered as server-sent events and over a WebSocket on /wp-json/headlessgo/v1/graphql. SSE needs nothing more (responses carry X-Accel-Buffering: no). A WebSocket needs the upgrade headers:

    location = /wp-json/headlessgo/v1/graphql {
        proxy_pass         http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";
        proxy_set_header   Host              $host;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;           # the server pings every 20 s
    }

Apache needs mod_proxy_wstunnel (or ProxyPass / http://127.0.0.1:8080/ upgrade=websocket on 2.4.47+). Keep the Host header: a browser WebSocket is accepted only from the site's own origin or a CORS origin of the Headless settings.

Apache

<VirtualHost *:443>
    ServerName blog.example.com
    SSLEngine on
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    ProxyPass        / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/
</VirtualHost>

systemd unit

[Unit]
Description=Pursae
After=network.target postgresql.service

[Service]
User=wpgo
EnvironmentFile=/etc/wpgo.env
ExecStart=/usr/local/bin/wpgo serve
Restart=always

[Install]
WantedBy=multi-user.target

/etc/wpgo.env holds DATABASE_URL, WPGO_SITE_URL, WPGO_UPLOADS_DIR, WPGO_SECRET and the mail settings.

Several instances

  • Run as many wpgo processes as you like against one database with a shared uploads directory (NFS or an object-storage mount). Give every instance the same WPGO_SECRET.
  • The scheduler claims jobs with FOR UPDATE SKIP LOCKED (events run once); migrations are serialised with an advisory lock.
  • Settings are cached per process; changes reach other instances via PostgreSQL LISTEN/NOTIFY within moments (one extra connection each, plus a reload every minute).
  • Side effects of saving a setting (starting a plugin, reconfiguring the cache) run only on the saving instance — restart the others after switching plugins on or off.
  • Every cache purge is broadcast on the wpgo_cache_purge channel; an instance whose listener reconnects empties its page cache.
  • Headless GraphQL subscriptions see only changes made through the instance the client is connected to; use its webhooks across instances.

Source: operations/reverse-proxy-and-tls.md

Caching (Pursae Cache)

Pursae Cache is a built-in plugin, on by default, modelled on LiteSpeed Cache but server-agnostic. It caches rendered public pages inside the Go process (memory LRU, optional disk persistence), purges them precisely by tags, and can tell a front proxy or CDN to cache them too. Admin menu: Pursae Cache (Dashboard, Cache, Page Optimization, Toolbox).

What is cached

GET requests of the public site from visitors who are not logged in and carry no comment-author cookie. Responses that set cookies, send Cache-Control: private/no-store/no-cache, have Content-Encoding, or are marked X-WPGo-Cache-Control: no-cache (forms with nonces) are never cached. Responses carry X-WPGo-Cache: hit|miss|bypass. Search results are not served from the page cache.

Settings (Pursae Cache › Cache)

OptionDefaultMeaning
wpgo_cache_enabledonthe plugin (switched on the Plugins screen)
wpgo_cache_serve—the Enable Cache switch: stops caching but keeps the plugin and its screens
wpgo_cache_ttl_public7 daysTTL of posts, pages and archives
wpgo_cache_ttl_front7 daysTTL of the front page
wpgo_cache_ttl_feed7 daysTTL of feeds
wpgo_cache_ttl_4041 hourTTL of not-found pages
wpgo_cache_mobileoffseparate entries for mobile user agents
wpgo_cache_logged_inoffcache for logged-in users too (per user)
wpgo_cache_exclude_uri—one path prefix per line that is never cached
wpgo_cache_drop_qs—query parameters ignored for the cache key (tracking parameters)
wpgo_cache_diskoffpersist entries to disk so they survive a restart
wpgo_cache_serverautoproxy headers to emit: auto, litespeed, nginx, generic, none
wpgo_cache_warm_result—last result of the crawler

Other Cache Settings: Cache Query Strings, Do Not Cache Cookies, Do Not Cache User Agents, Browser Cache TTL, 301 Redirect TTL, Memory Limit, Preload (after every purge, 30 s debounced, and daily). The crawler takes its URLs from the core sitemap providers (home, every public post type, taxonomy and author).

Page Optimization (wpgo_opt_*): lazy-load images (skipping the first ones above the fold), defer scripts / Defer All JavaScript with an exclude list, Delay JavaScript (scripts with a listed fragment load on first interaction or after a timeout), minify HTML, inline CSS minification, preload the theme's fonts, preconnect / dns-prefetch origins.

Tags and purging

Every cached page is tagged (home, post:12, term:3, author:1, media:7, feed, date:2026-10, archive:post, 404, search).

  • Publishing or editing a post purges its page, the home page, feeds, its author and term archives, its dates (and 404, since the new URL may have been cached as a 404).
  • Comments purge the post; editing or deleting a term purges pages listing or linking it; editing or deleting media purges pages showing it as a featured image.
  • Settings, theme, menu and widget changes, and saving a plugin settings page, purge everything. Plugins changing posts through the posts API trigger the same purges.
  • A render that overlaps a covering purge is sent to the visitor but not stored — the purge always wins. Concurrent misses of the same anonymous page render once; the others wait (up to 10 s) and are served from the cache.
  • The admin bar has Purge this page and Purge all; Toolbox has a crawler that warms the cache after a purge. With several instances every purge reaches all of them.

Front proxies and CDNs

wpgo_cache_serverHeaders emitted
litespeedX-LiteSpeed-Cache-Control, X-LiteSpeed-Tag
nginxX-Accel-Expires for proxy_cache / fastcgi_cache
genericCache-Control: s-maxage, Surrogate-Key and Cache-Tag (Varnish, Fastly, Cloudflare)
autoLiteSpeed headers only when the request came through LiteSpeed; nothing otherwise
nonein-process cache only

Purges reach the proxy. Set Front Server Purge URL and every purge is forwarded as a PURGE request: URL purges go to the purge URL plus the page path; tag purges carry Surrogate-Key, Cache-Tag and X-LiteSpeed-Purge listing prefixed tags (wpgo_ by default); a full purge sends X-Purge-All: 1 and X-LiteSpeed-Purge: *. Requests run in the background with a 5 s timeout. Without a purge URL, Front Server Lifetime (default 300 s) caps s-maxage, X-Accel-Expires and X-LiteSpeed-Cache-Control, and a warning is shown.

For developers: response headers the app sets

HeaderMeaning
X-WPGo-Cache-Tags: home,post:12,term:3,author:1,feedtags for purging (required for precise purges)
X-WPGo-Cache-TTL: 300TTL override in seconds; 0 = don't cache
X-WPGo-Cache-Control: no-cachedon't cache this response

All three are stripped before the response leaves the process. Do not gzip inside the cache: it compresses once at store time and negotiates Accept-Encoding itself (an outer gzip layer must skip responses that already have Content-Encoding). A janitor drops expired entries; warmup runs in-process (e.g. Concurrency: 4, RatePerSecond: 10).

Source: operations/caching.md, internal/cache/README.md

Scheduled events (cron)

WordPress runs scheduled tasks when a visitor loads a page. Pursae has a real job runner: every 15 seconds each instance publishes due scheduled posts and claims due rows of the jobs table with FOR UPDATE SKIP LOCKED, so several instances never run a job twice. No visitor, no wp-cron.php, no system crontab.

A recurring event exists once (a unique index prevents duplicates when instances start together). Runs missed while down are not caught up one by one: the event runs once, then waits for its next slot, as wp_reschedule_event() does.

Built-in events

JobRecurrenceDoes
wp_scheduled_deletedailyempties posts and comments trashed for 30 days (WPGO_EMPTY_TRASH_DAYS)
wp_scheduled_auto_draft_deletedailyremoves auto-drafts older than 7 days
delete_expired_transientsdailydrops expired transients
wp_session_gchourlyexpires login sessions and old login attempts
wpgo_cache_janitorhourlydrops expired page-cache entries
seogo_404_trimhourlykeeps Pursae SEO's 404 log at the monitor's limit
wp_mailone-offdelivers a queued e-mail
publish_future_postevery tickpublishes posts whose date has come
wpgo_backup_scheduleddaily or weeklyBackup Manager's scheduled local backup, only while a schedule is set; not recreated by ensureEvents

Plugin events

Plugins with the cron permission schedule their own hooks (cron_<name>) with an interval of at least a minute or as a one-off; those rows carry every:<seconds> as recurrence and the plugin slug in the payload.

Failures and retries

  • A failing job (error or panic) is retried after 1, 4, 9 and 16 minutes.
  • A one-off job is marked failed with the error text after the fifth failure.
  • A recurring job never fails for good: retries never pass its next regular run; after five failures in a row it waits for that run, keeping attempts and last_error for Site Health.
  • While running, locked_at is refreshed every minute; a running row with a lock older than ten minutes goes back to the queue.
  • On SIGTERM the job in hand gets a cancelled context and goes back to the queue without counting an attempt. Finished one-off jobs are kept for a week.

Inspecting

SELECT name, recurrence, status, run_at, attempts, last_error FROM jobs ORDER BY run_at;

Tools › Site Health lists scheduled events and failed jobs. A missing recurring event is recreated at the next start (ensureEvents). Tools › Scheduled Actions (/wp-admin/scheduled-actions, manage_options) lists the whole queue with status, runs, attempts and last error; a job that failed for good can be retried (clean attempt count) or deleted; running jobs cannot be deleted.

Background WXR imports

Tools › Import: upload the WXR file, assign authors and choose "Download and import file attachments"; the import runs as the wxr_import job with a progress screen and a report (kept for a week). The file sits in wxr-imports/ next to uploads (not served) and is removed afterwards. Re-importing is safe: existing posts and media are skipped.

Source: operations/cron.md

Mail

Pursae sends the same e-mails WordPress does: new-user notifications, password resets, comment moderation and "new comment" notices, admin e-mail change confirmations, personal data export links. Messages are queued in the jobs table and delivered by the scheduler, so a slow SMTP server never delays a request.

VariableDefaultMeaning
WPGO_SMTP_HOST—SMTP server; without it messages become .eml files
WPGO_SMTP_PORT587465 means implicit TLS, anything else STARTTLS when offered
WPGO_SMTP_USER, WPGO_SMTP_PASS—credentials
WPGO_MAIL_FROM<Site title> <wordpress@host>sender; the host is taken from the site URL
WPGO_MAIL_DIRmail/ next to uploads (/data/mail in Docker)where .eml files go when SMTP is off
WPGO_SMTP_HOST=smtp.example.com
WPGO_SMTP_PORT=587            # 465 = implicit TLS; other ports use STARTTLS when offered
WPGO_SMTP_USER=postmaster@example.com
WPGO_SMTP_PASS=…
WPGO_MAIL_FROM='Example Blog <no-reply@example.com>'

With Docker, docker/compose.yaml passes these through. For make prod-up put them in docker/.env and run make prod-up again to apply a change.

Deliverability Set a real WPGO_MAIL_FROM so receiving servers accept the mail, and set up SPF/DKIM for it.

Failures are retried with back-off (1, 4, 9, 16 minutes); after five attempts the job is marked failed and appears in Tools › Site Health.

Development: .eml files

docker compose -f docker/compose.yaml exec wpgo ls /data/mail

Open a file in a mail client or read it as text to see, for example, the password reset link. In the admin, Settings › General holds the administration e-mail and Settings › Discussion decides which comment events notify. Pursae never contacts Gravatar or any other third party on its own.

Source: operations/mail.md

Backups

A site is three things: the database, the uploads directory and the plugins and themes directories next to it. The binary and bundled themes need no backup.

WhatWhere (compose)Where (binary)
databasevolume pgdatayour PostgreSQL
mediavolume uploads (/data/uploads)WPGO_UPLOADS_DIR
plugin packagesvolume plugins (/data/plugins)<uploads>/../plugins
theme packages and edited theme filesvolume themes (/data/themes)WPGO_THEMES_DIR
Backup Manager archivesvolume backups (/data/backups)WPGO_BACKUPS_DIR

No backup needed for bin (the image or Dashboard › Updates puts one back), pagecache, languages (downloaded again) and mail.

Database

# dump (on a make prod-up stack add -f docker/compose.prod.yaml after -f docker/compose.yaml)
docker compose -f docker/compose.yaml exec db pg_dump -U wpgo -Fc wpgo > wpgo.dump
# restore into the same database
docker compose -f docker/compose.yaml exec -T db pg_restore -U wpgo -d wpgo --clean --if-exists < wpgo.dump
# your own PostgreSQL
pg_dump -Fc "$DATABASE_URL" > wpgo.dump
pg_restore -d "$DATABASE_URL" --clean --if-exists wpgo.dump

Files

docker run --rm -v wpgo_uploads:/data/uploads -v wpgo_plugins:/data/plugins -v wpgo_themes:/data/themes \
  -v wpgo_backups:/data/backups -v "$PWD":/backup alpine tar czf /backup/wpgo-files.tgz /data

Volume names are prefixed with the compose project name, wpgo.

Moving a site

  1. Dump the database and copy the files to the new host.
  2. Start the new instance with the same WPGO_SECRET if existing sessions should survive.
  3. Restore the dump, then update the URL under Settings › General if the address changed — once installed, the site URL lives in the database, not the environment.

Backup Manager

The built-in Backup Manager plugin (off by default) makes the same backup from the admin as one .zip (database rows as JSON lines plus the files), restores it on this or another site, and runs scheduled local backups (daily or weekly, keeping the newest N). Archives go to WPGO_BACKUPS_DIR, never inside the public uploads.

Copy archives off the server Scheduled backups stay on the same server; remote storage such as S3 or FTP is not included.

A restore keeps this site's own secret (auth_secret), address and Backup Manager settings. Secrets the built-in plugins store encrypted (SMTP passwords and tokens, CDN credentials, the Multi Language translation key, Security authenticator apps) are re-encrypted for this site; Pursae Security backup codes are stored only as hashes and must be generated again. If the source site encrypted with WPGO_SECRET, start this site with the same value.

Content export (WXR)

Tools › Export writes a WXR file with posts, pages, media references, comments and terms ("All content" also carries Pursae Custom Fields post types and taxonomies). Tools › Import reads one; items of unregistered post types are skipped and listed. It is a content transfer, not a backup: no passwords, settings, plugins or themes.

Source: operations/backups.md

Security

Built in

  • Passwords hashed with argon2id. Sessions are server-side rows tied to a random cookie (HttpOnly, SameSite=Lax, Secure behind TLS); 2 days, 14 with "Remember Me".
  • Login throttling: five failed logins from one address within 15 minutes block that address; twenty failures for one user name (from any address) block that name. Attempts are counted before the password check; REST Basic auth counts too. Unknown users cost as much time as wrong passwords, and at most twice as many password hashes as CPUs run at once.
  • Nonces protect every admin form and the REST API (X-WP-Nonce).
  • Security headers: X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy: strict-origin-when-cross-origin, a Content-Security-Policy (front end: script-src 'self' 'unsafe-inline', no remote scripts) and Strict-Transport-Security behind TLS.
  • Uploads are data, never code: /wp-content/uploads/ is served with a sandboxing CSP, so uploaded HTML or SVG cannot run scripts.
  • Content filtering: users without unfiltered_html and all plugins have their content filtered (KSES).
  • Sandboxed plugins: WebAssembly with no filesystem, no network except what the host allows, a memory cap, a per-call timeout and approved permissions. Packages are signed; only trusted keys install.
  • Multi-role users: capabilities are the union of the roles, with per-user allow and deny — deny wins.
  • No third-party calls: no Gravatar. The only service a site talks to is the Hub (see the next article).

Production checklist

  1. Terminate TLS in a proxy and set WPGO_SITE_URL to the https:// address.
  2. Start with make prod-up and settings in docker/.env; run the installer right after the site goes live.
  3. List your own plugin signing keys in WPGO_PLUGIN_KEYS or plugin_trusted_keys; leave plugin_allow_unsigned off; WPGO_TRUST_DEV_KEY must stay 0.
  4. Set WPGO_SECRET yourself when running several instances, and keep it secret.
  5. Set WPGO_DISALLOW_FILE_EDIT=1 (or Pursae Security › Hardening › Disable file editors) if nobody should edit theme files; it covers the admin editors and the REST theme-file routes.
  6. Let clients reach the server only through your proxy; set WPGO_TRUSTED_PROXIES to the proxy's address when other machines share its private network.
  7. Configure SMTP so password resets arrive.
  8. Back up the database and the data directories.
  9. Review plugin permissions on activation. A plugin is disabled automatically after five consecutive failures.
  10. Accounts are not listable by default: /?author=N answers 404, /wp/v2/users needs a login, the users sitemap is empty and the login form gives one message for unknown user and wrong password. Set WPGO_EXPOSE_USERS=1 only if you need a public author list. Author archives (/author/<nicename>) stay public and their slug comes from the login, so give publishing accounts a display name and nickname that differ from the login.
  11. Keep the core up to date and rebuild images regularly (the build uses the latest golang:1.27 image); govulncheck ./... should stay clean.

Pursae Security (built-in plugin) adds two-step login, a custom login URL, lockouts and an activity log on top.

Reporting a vulnerability Open a private security advisory on the GitHub repository rather than a public issue.

Source: operations/security.md

What Pursae sends to hub.pursae.com

Every production build talks to Pursae Manager at https://hub.pursae.com for updates, the theme and plugin marketplace and licenses.

WhenWhat
Once a day (and a minute after a core update)site URL, Pursae version, language, OS and CPU architecture, license key (if entered), active theme, and installed plugins and themes with versions, active state and origin (built in, Hub, uploaded)
As it happens (batched)package actions: plugin installed/updated/activated/deactivated/deleted; theme installed/updated/activated/previewed/deleted; demo imported; core updated — each with slug, version and time
On every request to the Hubsite URL and license key as headers; the Hub also sees the server's IP address

It never receives your content, users, e-mail addresses, passwords, visitors, orders or anything else from your database. In return the site gets signed core updates (every binary signed by a Hub key endorsed by the release key built into Pursae), signed Wasm plugins, the theme library (checked against SHA-256), licenses for pro and beta packages and the product logo.

Turning it off

Set WPGO_HUB=off (with Docker: in docker/.env) and restart; the site sends nothing to hub.pursae.com. Remove it and restart to get updates again.

Not recommended With the Hub off the site gets no update notices or one-click updates — security fixes included — no marketplace, no signed plugins and no licenses; you replace the binary yourself for every release, and every admin page says so.

Source: README.md

Publishing a release

A release is a set of static binaries, one per platform, published as a GitHub release. Pursae Manager imports it, signs each binary's hash with its endorsed key, and every site sees the version under Dashboard › Updates. The Manager never compiles and keeps no copy; sites download from GitHub.

1. Build and publish

make release VERSION=0.2.0                 # stable
make release VERSION=0.3.0-beta.1 BETA=1   # beta channel (a GitHub pre-release)
make release VERSION=0.2.0 DRY_RUN=1       # only build and check, into dist/release/v0.2.0

tools/release.sh:

  1. refuses uncommitted changes or untracked files, or a tag v0.2.0 that points to another commit;
  2. builds linux-amd64, linux-arm64, darwin-arm64, darwin-amd64 and windows-amd64 with CGO_ENABLED=0 go build -trimpath -buildmode=exe -tags nodynamic -ldflags "-s -w -X wpgo/internal/server.Version=0.2.0", checks that Linux binaries are static and that your machine's binary reports the version;
  3. writes SHA256SUMS;
  4. asks before publishing, then commits the version ("Pursae 0.2.0"), tags v0.2.0, pushes to the public remote and creates the GitHub release with the binaries (pursae-<os>-<arch>, .exe on Windows) and SHA256SUMS.
SettingDefaultMeaning
VERSION—version to release
BETA—1 publishes to the beta channel (GitHub pre-release)
DRY_RUN—1 only builds and checks
RELEASE_REPOpursae/pursaemust be public; sites download without credentials
RELEASE_REMOTES—release setting (not detailed in the docs)
TARGETS—release setting (not detailed in the docs)
NOTES_FILEGitHub's generated notesrelease notes
YES—1 skips the question

Needs Go, git and the GitHub CLI (gh auth login).

2. Import it in Pursae Manager

Core › Import: tag, channel (stable, or beta for beta licenses), notes, Import Release. The Manager reads the release from the GitHub API, downloads each pursae-<os>-<arch> asset once, checks it against SHA256SUMS (and that Linux binaries are static), signs pursae-core-v1\n{version}\n{os}-{arch}\n{sha256}, stores hash, signature and GitHub URL, and publishes. A platform without a binary is not offered the release.

3. What sites do

At the next update check (daily, or on Dashboard › Updates) sites see the version. Update asks the Manager for the binary, follows the redirect to GitHub, checks the SHA-256 and signature, replaces the executable and restarts.

Never replace release assets A file replaced on GitHub after import fails the check and sites refuse it. Publish a new patch version instead (and consider GitHub's immutable releases).

Source: operations/releases.md

Troubleshooting

SymptomCause and fix
Site redirects to /wp-admin/install again after a restartThe database is empty or a different one is used. Check the pgdata volume exists (docker volume ls) and DATABASE_URL points to the right database.
Docker restarted and the site is downContainers do not always come back. Run make prod-up (production) or docker compose -f docker/compose.yaml up -d (development). Use the command your stack was started with — the development file on a production server brings back development settings and the wrong DB password.
Links/assets point at an old IP or portThe site URL was stored at install time. Change it under Settings › General, or start over with the right WPGO_SITE_URL.
Port 8088 or 5432 already in use (e.g. a local WordPress)WPGO_PORT=9000 WPGO_DB_PORT=5433 WPGO_SITE_URL=http://localhost:9000 make docker-up
First build slow or module download failsMake sure Docker has network access; later builds are cached.
Login works but every admin action says the nonce is invalidInstances behind the load balancer have different WPGO_SECRETs. Set the same value everywhere.
http:// links behind a TLS proxyThe proxy must send X-Forwarded-Proto: https and WPGO_SITE_URL must be the https:// address.
Plugin: "signature could not be verified"Unsigned or untrusted key. Add the author's public key to WPGO_PLUGIN_KEYS or plugin_trusted_keys; for local development set plugin_allow_unsigned.
Plugin "disabled after 5 consecutive failures"Read its log lines on Plugins (last five shown); deactivate and activate to reset.
Scheduled posts do not publish / e-mails not sentThe scheduler runs inside wpgo serve; check the server log and Tools › Site Health for failed jobs.
"Template error" after editing a theme fileThe editor rolls back broken saves; if you edited files on disk under WPGO_THEMES_DIR, fix or delete the file to fall back to the embedded copy.
make prod-up: "Create docker/.env first" / "set WPGO_DB_PASSWORD"cp docker/.env.example docker/.env and fill in WPGO_DB_PASSWORD and WPGO_SITE_URL.
Dashboard › Updates never offers a new versionA development build does not talk to the Hub; run the production build (make prod-up).
Where are the logs?Standard output: docker compose logs -f wpgo, make prod-logs, or your service manager's journal. Every request is logged with status and duration.

Start from scratch

Destructive This deletes every volume: the database, uploads, plugins, edited themes, backups and the updated binary.
docker compose -f docker/compose.yaml down -v
make docker-up

Source: operations/troubleshooting.md

AI agents (MCP)

Pursae has a built-in Model Context Protocol server. A connected AI client (Claude, Cursor and others) can write and publish content, upload media, build menus, edit theme files, switch themes, toggle plugins, purge the cache and change the built-in plugins' settings — all through the REST API with the permissions of one credential.

  • Endpoint: https://<site>/wp-json/pursae/v1/mcp, MCP's streamable HTTP transport.
  • Sign-in: OAuth 2.1 (consent screen in the browser) or HTTP Basic with a user name and an Application Password. Every tool runs as a REST request, so capabilities and scopes apply exactly as for direct REST calls.
  • stdio: wpgo mcp bridges clients that start a local command; the site can be local or remote.
  • Resources: the developer docs (pursae-docs://developer/…), so the agent can read how themes and plugins work before changing them.

1. Sign in

OAuth (no password to copy): point the client at the endpoint. It discovers the authorization server from the 401, registers itself and opens the site's Authorize Application screen: check the name, tick scopes (default Content and Media; everything the user can do needs the explicit Full access box) and approve. Revoke under Users › Profile › Connected applications.

claude mcp add --transport http pursae https://example.com/wp-json/pursae/v1/mcp
# then run /mcp inside Claude Code and choose "Authenticate"

Application Password (for clients without OAuth, scripts and wpgo mcp): Users › Profile › Application Passwords — name it, tick the scopes it needs (or none for all your permissions) and copy it (shown once). Use an Editor for content work, an Administrator for themes, plugins and settings. Revoke on the same screen to cut the agent off at once.

JobRecommended scopes
Writing and publishingcontent, media, seo
Design workthemes, media, cache
Running the whole sitenone (full access)

2. Connect a client

Use HTTPS for remote sites: Basic auth sends the password with every request.

# Claude Code
claude mcp add --transport http pursae https://example.com/wp-json/pursae/v1/mcp \
  --header "Authorization: Basic $(printf 'admin:abcd efgh ijkl mnop qrst uvwx' | base64)"

Claude Desktop starts local commands, so use the bridge in claude_desktop_config.json (Settings › Developer › Edit Config):

{
  "mcpServers": {
    "pursae": {
      "command": "/usr/local/bin/wpgo",
      "args": ["mcp"],
      "env": {
        "PURSAE_URL": "https://example.com",
        "PURSAE_USER": "admin",
        "PURSAE_APP_PASSWORD": "abcd efgh ijkl mnop qrst uvwx"
      }
    }
  }
}

With the Docker image: "command": "docker", "args": ["run", "--rm", "-i", "-e", "PURSAE_URL", "-e", "PURSAE_USER", "-e", "PURSAE_APP_PASSWORD", "<image>", "mcp"].

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "pursae": {
      "url": "https://example.com/wp-json/pursae/v1/mcp",
      "headers": { "Authorization": "Basic YWRtaW46YWJjZCBlZmdoIGlqa2wgbW5vcCBxcnN0IHV2d3g=" }
    }
  }
}

The header is Basic + base64 of user:password. Any other MCP client works the same way.

wpgo mcp flags

FlagEnvironmentMeaning
--urlPURSAE_URLsite address
--userPURSAE_USERlogin or e-mail
--passwordPURSAE_APP_PASSWORDthe Application Password; prefer the env var (a flag shows in ps, and the bridge warns)
—PURSAE_CONFIG_DIRoverrides where OAuth tokens are stored

wpgo mcp login --url https://example.com [--scope "content media"] [--no-browser] runs OAuth 2.1 with PKCE (loopback redirect on 127.0.0.1) and stores the token pair in <user config dir>/pursae/mcp-<host>.json (mode 0600, a plain file, not the OS keychain). Afterwards wpgo mcp --url https://example.com needs no password: it sends the Bearer token and refreshes once on 401. The bridge refuses plain http:// except localhost, 127.0.0.1 and ::1; stdout carries only protocol messages, errors go to stderr.

Sessions and streaming

  • initialize returns an Mcp-Session-Id; unknown or ended ids get 404 (initialize again). Without the header the server is stateless. Sessions are per user, capped at 10 per user and expire after an hour without use.
  • POST answers application/json, or a one-event text/event-stream when Accept prefers it.
  • GET with Accept: text/event-stream opens the server→client stream: notifications and a : keep-alive every 25 seconds; the last 64 events are kept for Last-Event-ID reconnects; one stream per session; it ends when the token or password is revoked or expires.
  • DELETE ends the session (204).

Tools

AreaTools
Posts and pageslist_posts, get_post, create_post, update_post, delete_post and the same for pages
Medialist_media, upload_media (base64 or a public URL), update_media, delete_media
Termslist_terms, create_term, update_term, delete_term
Menuslist_menus, create_menu, list_menu_locations, list_menu_items, create_menu_item, update_menu_item, delete_menu_item
Styles and settingsget_global_styles (read only), get_settings, update_settings
Commentslist_comments, create_comment, moderate_comment, delete_comment
Userslist_users, get_me, create_user, update_user, delete_user
Pursae Commerce (commerce scope)commerce_list_products, commerce_get_product, commerce_create_product, commerce_update_product, commerce_update_stock, commerce_delete_product, commerce_list_orders, commerce_get_order, commerce_update_order, commerce_sales_report
Pursae Web Builder (content scope)web_builder_get_document, web_builder_save_draft
Pursae SEOseo_get_meta, seo_update_meta, seo_analyze, seo_get_settings, seo_update_settings, seo_list_redirects, seo_create_redirect, seo_delete_redirect
Pluginslist_plugins, activate_plugin, deactivate_plugin, install_plugin, delete_plugin
Site operationssite_health, list_updates, run_update, list_backups, create_backup, delete_theme, ai_activity
Themeslist_themes, activate_theme, install_theme, list_theme_files, read_theme_file, write_theme_file, restore_theme_file
Pursae Cachecache_status, cache_purge, cache_get_settings, cache_update_settings
Pursae Headless (settings scope)headless_list_types, headless_save_type, headless_update_type, headless_delete_type, headless_find, headless_get_entry, headless_create_entry, headless_save_entry, headless_publish, headless_unpublish, headless_delete_entry
Built-in plugin settingslist_option_groups, get_options, update_options (contact, cookie, gocdn, headless, maintenance, multilang, pixel, security, seo, smtp; secrets masked)
Anything elsesite_info, rest_request (any REST route, same permissions)

tools/list shows only tools the credential can use (scopes, capabilities, active plugins); notifications/tools/list_changed is sent when a plugin is toggled. Refused calls return the REST error code (rest_forbidden, rest_scope_forbidden, …). Annotations follow the MCP spec: readOnlyHint on reading tools (and seo_analyze), destructiveHint on everything that is not purely additive.

Safety

  • Every write is logged (time, user, OAuth app or Application Password name, tool, route, status; no bodies) for 90 days — read it with ai_activity, GET /pursae/v1/mcp/activity or Tools › AI Access (/wp-admin/ai-access, manage_options), which also shows the endpoint, ready client configs and every OAuth grant with Revoke.
  • An hourly job drops expired OAuth grants and codes, orphaned clients and old activity.
  • Tool answers over 400 KB are cut and carry no structuredContent.
  • write_theme_file checks templates before keeping them; restore_theme_file undoes edits; WPGO_DISALLOW_FILE_EDIT=1 forbids theme file changes entirely.
  • upload_media fetches only from public addresses; Pursae Security's lockouts and IP block list apply to the endpoint.
  • Give the agent the narrowest scopes and the least powerful user that does the job.

Source: operations/ai-mcp.md

Built-in plugins

Plugins compiled into the binary

Pursae ships the plugins a WordPress site usually buys or installs separately inside its own binary. Each one is listed under Plugins, is off on a fresh install, adds nothing (no menu, routes, output) while off, and keeps its data when deactivated.

Pursae Commerce

A clone of WooCommerce with its premium extensions built in as modules: products, cart, checkout, tax, shipping, coupons, orders, payment gateways, e-mails and both REST APIs. Internal name goocommerce, switch native_goocommerce. While off, its screens answer 404 and its REST routes rest_no_route.

Data

  • Products are posts of type product / product_variation plus a row in goo_products.
  • HPOS-like orders: goo_orders, goo_order_items, goo_order_notes; plus attributes, coupons, tax rates, shipping zones/methods, sessions, download permissions, API keys and webhooks tables.

Modules (Pursae Commerce › Extensions, all off by default)

CategoryModules
MerchandisingProduct Bundles, Pre-Orders, Product Add-Ons, Product Compare, Quick View, Dynamic Pricing
Store managementBookings, PDF Invoices & Packing Slips
Payments & checkoutSubscriptions, Gift Cards
Shipping & deliveryTable Rate Shipping
Customer engagementMemberships, Points and Rewards, Wishlists
  • Subscriptions: wc/v3/subscriptions (CRUD, batch, notes, orders), webhook topics, customer address/payment-method changes and resubscribe, manual subscriptions and "Process renewal" in the admin.
  • Gift Cards: disabled on cancel/refund, expiry reminder a week ahead, five colour designs (optional image), PDF card and signed print-at-home page; Store API and wc/v3/gift-cards.
  • Product Add-Ons: nonce-protected file uploads (20 per address per 10 minutes, orphans deleted after 24 h), conditional fields, date limits.
  • Bookings: signed .ics downloads and a private ICS feed, blocks past midnight, automatic refund of cancelled paid bookings where the gateway supports it, wc-bookings/v1 REST.
  • Memberships: lifecycle tied to orders and subscriptions, welcome / ending soon / ended e-mails, drip schedule for restricted content.

Storefront, blocks and APIs

  • Store pages render inside the active theme like WooCommerce's theme-compatibility mode, keeping WooCommerce's templates, classes and field names. Themes declare "supports": { "woocommerce": true } in theme.json.
  • Shortcodes are named goocommerce_* and answer to their woocommerce_* alias. Server-rendered blocks: products, featured product, product categories, mini cart, product search.
  • wc/store/v1 (Store API) and wc/v3 (management API) follow WooCommerce's JSON shapes, parameters, error codes and headers; wc-analytics serves revenue, orders and product reports.
  • Webhooks for coupon/customer/order/product events, module topics and action.<hook>; failed deliveries retried after 10 s and 1 min, disabled after 5 consecutive failures; delivery log with "Send test delivery".
  • Analytics reports (Overview, Products, Revenue, Orders, Variations, Categories, Coupons, Taxes, Downloads, Stock, Customers) with uncapped CSV; weekly store summary e-mail.
  • CSV product import/export with WooCommerce column names and Meta: <key> columns; batch import of 50 rows; CSV export of orders, coupons, subscriptions and customers.

Payments and concurrency

  • Gateways: direct bank transfer (BACS), check, cash on delivery, Stripe (Stripe-hosted Checkout, signed webhook, API refunds, saved cards, off-session renewals) and a Test payments gateway.
  • Order status changes are serialized per order; stock and coupon uses are taken with conditional updates, so a payment that loses the last unit puts the order on hold instead of overselling.
Limits iyzico is not built yet. BACS, check, cash on delivery and Bookings do not refund automatically. Geolocation uses CDN/proxy country headers (no GeoIP database). Cart and Checkout have no editor blocks yet; use the [goocommerce_cart] and [goocommerce_checkout] shortcodes. E-mails and module front-end texts are still English. Checkout validates stock but does not reserve it.

Source: docs/goocommerce-features.md

Pursae SEO

The union of Yoast SEO Premium and Rank Math Pro in one plugin with a WordPress-style admin. Slug seo-go, switch native_seogo, settings in one JSON option seogo_options. While off its routes answer 404, nothing is added to <head>, and core's wp-sitemap.xml and robots.txt are served.

Compatibility with imported sites

  • Writes Rank Math's %var% syntax and accepts Yoast's %%var%%, with both plugins' variable names.
  • Stores _seogo_* meta but every read falls back to Yoast's _yoast_wpseo_*, then Rank Math's rank_math_* keys, so an imported WordPress site keeps its SEO data without conversion. Tools › Import and the WXR importer also copy it.
  • Reads Yoast and Rank Math FAQ / How-to blocks and breadcrumb shortcodes; serves both plugins' REST head endpoints (yoast/v1/get_head, rankmath/v1/getHead) plus seogo/v1/get_head.

Editor and analysis

  • One SEO box: a meta box in the classic editor, a sidebar plus a document panel in Pursae Editor, an SEO tab in Pursae Web Builder's Page tools.
  • Focus keyphrase plus related keyphrases, mobile/desktop snippet preview, title and description with variables, canonical, all robots directives, breadcrumb title, primary category, Open Graph / X previews.
  • SEO analysis: all of Yoast's assessments plus Rank Math's extra tests; Yoast-style traffic lights, Rank Math's 100-point score shown alongside. Readability: Yoast's 7 assessments with Flesch and reading time as insights; Turkish gets transition words and Turkish-aware lowercasing.
  • Cornerstone (pillar) content, internal linking suggestions, link counter with orphaned content, bulk editor (50 per page) and SEO / Readability columns on post lists.
  • Schema tab: page type, article type, Product and custom JSON-LD.

Site-wide output

  • Search appearance templates per content type, taxonomy and archive (including Commerce products and Custom Fields post types), the same 14 separators, Knowledge Graph (organization or person), social settings, webmaster verification (Google, Bing, Baidu, Yandex, Pinterest, Naver), RSS before/after text, robots.txt editor, settings import/export as JSON.
  • Schema graph with Yoast's @id scheme, FAQ and How-to blocks, Product, LocalBusiness (Local SEO module) and custom JSON-LD. Breadcrumbs as a block and shortcodes with BreadcrumbList schema.
  • Sitemaps on Yoast's URL scheme (/sitemap_index.xml), 1000 URLs per file (configurable), image entries, hreflang alternates with Pursae Multi Language; /sitemap.xml and /wp-sitemap*.xml redirect 301. News sitemap (last 48 hours) and video sitemap (YouTube/Vimeo embeds and self-hosted video).
  • IndexNow with key file, automatic and manual submission and retries.

Redirections, 404s and Search Console

  • Redirects 301, 302, 307, 410, 451 with exact, contains, starts with, ends with and regex matching; categories, hit counters, CSV import/export, automatic redirects on post and term slug changes.
  • 404 monitor with hits, referer, user agent, ignore list and a "Redirect" button; optional fallback URL for every 404.
  • Search Console report with the site owner's own Google OAuth client (read-only scope): clicks, impressions, CTR, position, top 10 queries and pages for the last 28 days. Secret and tokens stored encrypted.
  • Modules can be switched individually; a role manager grants seogo_* capabilities per role. A five-step setup wizard opens on first activation.
Left out Rank Math Analytics beyond Search Console, Content AI and Yoast AI, SEMrush/Wincher, Yoast word forms and synonyms, inclusive language, the visual schema builder and templates, yoast_head fields on wp/v2, live analysis on the term screen, and the .htaccess editor (not applicable: Pursae serves every request itself).

Source: docs/seo-go-features.md

Pursae Custom Fields

A native clone of Advanced Custom Fields PRO 6.x. Internal name acfgo, switch native_acfgo. Field groups are acf-field-group posts whose content is ACF's export JSON, and values are stored exactly like ACF (name → value, _name → field key, repeater rows as name_{i}_{sub}, options as options_{name}), so ACF data imported with WXR reads back unchanged.

Field groups and field types

  • Field Groups list with views, row and bulk actions, search; drag-and-drop editor; field settings tabs (General, Validation, Presentation, Conditional Logic); ACF-style group_… / field_… keys.
  • Local JSON in <data>/acf-json and the active theme package, with "Sync available"; registration from Go code (acfgoRegisterLocalGroup).
  • Every ACF field type, including the PRO ones: text, text area, number, range, email, URL, password, image, file, WYSIWYG, oEmbed, gallery, select, checkbox, radio, button group, true/false, link, post object, page link, relationship, taxonomy, user, Google Map, date / date-time / time pickers, color picker, message, accordion, tab, group, Repeater (with pagination), Flexible Content, Clone, Icon Picker.
  • Bidirectional Relationship, Post Object and User fields mirror their value into the target field of related objects.

Where fields appear

  • Location rules (OR groups of AND rules): post type, template, status, format, category, taxonomy, page type/parent, current user and role, user form, taxonomy term, attachment, comment, menu and menu item, ACF Blocks, Options Page.
  • Presentation settings (style, position, label and instruction placement, hide on screen); boxes in both the classic editor and Pursae Editor.
  • Conditional logic live in the editor and on save; validation via ajax before submit and on the server, including REST writes.
  • Options pages created in the UI; Post Types and Taxonomies UI that registers types with admin menus, front-end routes, archives and /wp/v2/<rest_base> REST routes.
  • ACF Blocks from acf-blocks/<name>/block.json with a Go html/template render template.

Developer access

  • REST acf object on posts, pages, users, terms, comments and media (read and write, validated; ?acf_format=standard for formatted values).
  • Theme template functions get_field, the_field, get_field_object, get_fields, have_rows, get_sub_field and friends; Go helpers acfGetField, acfUpdateField; Wasm plugins get an acf object from get_post.
  • Tools: export/import of field groups, post types, taxonomies and options pages as JSON.
Differences No PHP, so no acf/* PHP filters, acf_form() or Generate PHP. Widget locations, field value revisions, moving a field between groups and CPT UI import are left out. Some pickers are native controls (browser date inputs, URL inputs instead of wpLink, address and coordinates instead of the Google Maps picker); WYSIWYG is TinyMCE only where the classic editor loads.

Source: docs/acf-go-features.md

Pursae Multi Language

A 1:1 functional clone of Polylang Pro (3.9), plus TranslatePress-style visual translation, automatic string capture, per-language media texts and machine translation. Internal name golylang, option golylang with Polylang's keys. While off there are no menus, the pll/v1 namespace is hidden and /fr/ URLs are 404.

Languages and URLs

  • Languages screen with about 100 predefined locales, RTL, flag (two-letter code shown as an emoji flag), order, default language; Activate/Deactivate per language.
  • Language from directory, subdomain, separate domains or content (?lang=); hidden default language; browser language detection; translated slugs and shared slugs.
  • Every link carries the language; queries, feeds, search and sitemaps are narrowed to it; <html lang>, dir="rtl", hreflang and per-language sitemaps.

Content and strings

  • Language columns on post, page, term and media lists; Languages box in the classic editor, Pursae Editor and Pursae Web Builder; add-translation flow that copies terms, featured image, custom fields and more.
  • Synchronization of taxonomies, custom fields, comment/ping status, sticky, date, format, parent, template, order and featured image (each translation keeps its own Pursae SEO texts).
  • Duplicate content, bulk translate, Untranslated / Outdated views, XLIFF 1.2 export/import of content, PO export/import of strings.
  • Strings screen covering site title, tagline, date/time formats, URL slugs, theme gettext and Customizer text, Wasm plugin strings and text recorded on pages.
  • One Media Library item per upload with alt text, title, caption and description translated per language.
  • Menus per language, a language switcher menu item, block and pll_the_languages template function.

Visual and machine translation

  • Visual translation screen: the page in an iframe with a string panel; click any text to translate it with live preview. Works with every theme type, needs at least two languages; not in subdomain/domain URL modes.
  • Machine translation (off by default) with DeepL, Google Cloud Translation or an OpenAI-compatible API. The key is sealed with AES-GCM and never shown again; text is sent only when a manager asks; requests go from the server to public addresses only.
  • Per-language capabilities manage_translations and translate_{lang} open the translation screens for translators without site admin rights.
Left out .mo language pack downloads and locale fallback, the setup wizard (the Languages screen does the same), synchronized posts, legacy widgets and per-widget languages, Quick/Bulk Edit language select, the WPML API and WP-CLI wp pll.

Source: docs/golylang-features.md

Pursae Contact Form

A native clone of Contact Form 7 (studied at 6.2.3) with Flamingo-style entry storage and the Really Simple CAPTCHA built in. Internal name gontact-form, switch native_gontact_form. Same post type (wpcf7_contact_form), meta keys, default templates, admin screens, form markup and JavaScript events as CF7, so CF7 forms, themes and scripts work unchanged.

Forms and embedding

  • Contact menu with list, add and edit screens; Form, Mail, Mail (2), Messages and Additional Settings tabs; tag generator; configuration validator.
  • [contact-form-7 id="…"] and [contact-form …] shortcodes (hash ids, numeric ids, title lookup) and the contact-form-7/contact-form-selector block.
  • Form-tags: text, email, url, tel, textarea, number, range, date, select (with data:countries from Commerce data), checkbox, radio, acceptance, quiz, file, submit, hidden, count, response, captchac / captchar.
  • Conditional groups ([group] with equals, contains, greater than… rules), checked again on the server.

Submission and mail

  • CF7's REST feedback, schema and refill endpoints with the same statuses and response shape; a non-JS fallback with inline errors.
  • All mail-tags and special tags; HTML mail; attachments held in memory (25 MiB per submission) and never written to disk; delivery status per entry.
  • Entries stored in gontact_entries: list, search, view, delete, formula-safe CSV export, retention in days; do_not_store: true per form.
  • Outgoing webhooks (webhook_url) signed with X-Pursae-Signature; Wasm hooks wpcf7_validate, wpcf7_before_send_mail, wpcf7_spam, wpcf7_mail_sent.

Spam protection

  • Honeypot and HMAC-signed minimum fill time (3 s) on by default; rate limit of 30 submissions and 30 refills per minute per address; disallowed keys; quiz.
  • reCAPTCHA v3 and Cloudflare Turnstile (reCAPTCHA loads only after consent when Pursae Cookie is on).
  • Built-in image CAPTCHA drawn in pure Go: 4 characters without look-alikes, single use, one-hour expiry, answer stored only as an HMAC, works behind the page cache.
Not ported Akismet, Constant Contact, Brevo, Stripe, reflection / listo, an audio CAPTCHA (the [quiz] tag is the accessible alternative) and UI translations (the UI is English).

Source: docs/gontact-form-features.md

Pursae SMTP

A native clone of WP Mail SMTP (Lite and Pro). Internal name wpgo-mail-smtp, switch native_wp_mail_smtp, settings in one JSON option with upstream's key names. While inactive, wp_mail() keeps using the WPGO_SMTP_* environment variables (or .eml files on development sites). Pro features are included without a licence.

Mailers

  • Other SMTP (native client: SSL, STARTTLS, Auto TLS, AUTH PLAIN/LOGIN), SendLayer, SMTP.com, Brevo, Mailgun, SendGrid, Postmark, SparkPost, Amazon SES, Microsoft 365 / Outlook, Google / Gmail, Zoho Mail, Elastic Email, Mailjet, MailerSend, Resend, SMTP2GO, Mandrill.
  • OAuth mailers use the site owner's own app; tokens refresh automatically. All mailers deliver Cc, Bcc and attachments.
  • Secrets (passwords, API keys, OAuth tokens) are AES-256-GCM encrypted and never printed back into forms.

Routing and reliability

  • Setup wizard with a test e-mail and a domain checker (SPF, DKIM, DMARC, MX).
  • Force From e-mail / name, Return Path, backup connection, additional connections and Smart Routing by subject, message, from, to, reply-to or initiator.
  • Rate limits per minute, hour, day, week and month; over-limit mail is re-queued.

Log, reports and alerts

  • Email Log with content, status, resend (also to other recipients), export as CSV or EML (zip), retention, optional signed open/click tracking that ignores DNT/GPC visits.
  • Reports with daily sent/failed chart, open, click and bounce rates, weekly summary e-mail; dashboard widget and Site Health row.
  • Alerts by e-mail, Slack, Discord, Microsoft Teams, Twilio SMS or a custom webhook, with a failure threshold; delivery, bounce and complaint status from Postmark, SendGrid, Mailgun and Amazon SES (SNS signature verified).
  • Email Controls to switch off individual core and Commerce notification types; Do Not Send; debug events.
  • Every upstream WPMS_* constant is read from the environment (with WPMS_ON=true).
Left out One-click Gmail/Microsoft setup (needs WPForms' relay and a licence), XLSX export, storing attachment bytes, push and WhatsApp alerts, usage tracking, importing other SMTP plugins, multisite and WP-CLI.

Source: docs/wpgo-mail-smtp-features.md

Pursae Security

A login-security plugin at the level of Wordfence Login Security, Two Factor, WPS Hide Login and the login, user and hardening parts of Solid Security. Internal name adminsecgo, switch native_adminsecgo. Deactivating keeps users' factors, settings and the log, and brings /wp-login back.

Second factors

  • MFA: e-mailed 6-digit codes (10-minute expiry, single use, 60 s resend cooldown, 5 attempts). Needs working e-mail (Pursae SMTP or WPGO_SMTP_HOST).
  • 2FA: authenticator app (TOTP, RFC 6238) with replay protection and a QR code generated server-side in pure Go; requires MFA first.
  • 10 backup codes shown once; "remember this device" (default 30 days); TOTP secrets sealed with AES-256-GCM, codes stored only as HMAC hashes.
  • Per-role requirement (MFA or 2FA) with a grace period (default 7 days); admin reset and wpgo adminsec reset-user.

Login protection

  • Custom login URL; /wp-login and /wp-admin answer 404 (or redirect) for visitors; escape hatch WPGO_ADMINSEC_DISABLE_HIDE_LOGIN=1.
  • Lockouts per IP (default 5 failures in 15 minutes → 20 minutes) and per username, progressive lockouts (default 24 h after 4), IP/CIDR allow and block lists.
  • Generic error messages, user enumeration blocking, optional Turnstile or reCAPTCHA v3 on login forms, reset-mail limits.
  • Password policy per role with a strength score, the 10,000 most common passwords refused, optional Have I Been Pwned check (k-anonymity), forced password change.
  • Active sessions list with per-session logout, idle timeout.

Hardening and audit

  • Security headers (X-Frame-Options, Referrer-Policy, Permissions-Policy, X-Content-Type-Options, HSTS), disabled file editors, hidden version, optional REST for logged-in users only, e-mail alerts.
  • File integrity scan (binary SHA-256, core web files, bundled-theme edits, server-side scripts in themes and uploads).
  • Activity log with filters, CSV export and retention (default 90 days); dashboard with a 0–100 % security score.
  • CLI: wpgo adminsec disable-hide-login, reset-user, unlock-all, deactivate.
Firewall The per-IP rate limit (900 requests a minute by default) and basic WAF rules on the URL and User-Agent are part of the core and on by default, also without this plugin; Settings › Firewall tunes them and WPGO_FIREWALL=off disables them.
Not included A malware signature scanner, passkeys (WebAuthn), password expiry and XML-RPC (Pursae has no XML-RPC endpoint).

Source: docs/adminsecgo-features.md

Pursae Pixel

Ad and analytics tracking in the class of PixelYourSite Pro, Pixel Manager for WooCommerce and GTM4WP, written from scratch. Internal name pixelgo, switch native_pixelgo, version 0.1.

Platforms

PlatformBrowserServer-side
Meta PixelYesConversions API
Google Analytics 4YesMeasurement Protocol, Purchase (and refund) only
Google AdsConversions, remarketing, enhanced conversionsNo
TikTokYesEvents API
PinterestYesConversions API
Microsoft Advertising (UET)YesNo
Google Tag ManagerContainer and GA4 e-commerce dataLayerNo

Events

  • One event model for every platform: page view, search, scroll, time on page, tel/mailto clicks, outbound links, downloads, forms, comments, registrations, HTML5, YouTube and Vimeo video.
  • Store events from Pursae Commerce: ViewContent, ViewCategory, AddToCart, RemoveFromCart, ViewCart, InitiateCheckout, AddPaymentInfo, Purchase (once per order and browser).
  • Custom events by page visit, CSS selector click, scroll, time or form submit; advanced matching with hashed customer data (opt-in); UTM and click-id attribution cookie (90 days).

Consent and delivery

  • With Pursae Cookie and "Require consent" (default) tags stay inert until consent; without Pursae Cookie no tag is printed.
  • Browser and server events share one event id for deduplication; Purchase is also sent on payment_complete, so off-site payments count. Retries after 2 s, 15 s and 90 s, an hourly sweep for unaccepted Purchases and a delivery log with Retry.
  • Product catalog feed (RSS 2.0 for Google Merchant / Meta) at a token URL, streamed in pages of 500, optional per-variation items.
  • Role exclusions, debug mode, window.pixelgo.track(), settings export/import, test events per platform.
Not in 0.1 Google Ads and Microsoft Advertising server-side events, Snapchat, Reddit and X tags, subscription/booking-specific events, single-page-app page-view deduplication.

Source: docs/pixelgo-features.md

Pursae Analytics

Privacy-friendly site statistics and real-user Core Web Vitals, in the class of Plausible, Jetpack Stats and the MonsterInsights dashboard. Switch native_pursae_analytics, version 0.1.

Privacy

  • No cookies, no browser storage, no fingerprinting script; no IP address stored. A visitor is a SHA-256 of a daily random salt, IP, user agent and host; the salt is deleted the next day.
  • Signed-in users, Do Not Track / Global Privacy Control and excluded IP ranges are settings. No consent banner is needed.

Collection

  • A 2.3 KB script (1.2 KB gzipped), identical for every visitor so it works behind the page cache.
  • Page views (path, UTM source/medium/campaign, referrer host, viewport), events (outbound, download, form, 404) and end-of-view data (visible time, LCP, INP, CLS, FCP, TTFB).
  • Device, browser, OS, source (known services such as Google, Bing, ChatGPT, Perplexity), country from CDN/proxy headers. Bots, prefetches, admin paths and over 300 requests a minute per address are dropped.

Analytics screen

  • Periods: today (hourly), 7 days, 30 days, this month, 90 days, 12 months.
  • Unique visitors, visits, page views, views per visit, bounce rate, visit duration with change against the previous period; current visitors; SVG chart.
  • Top pages, entry pages, sources, UTM campaigns, countries, devices, browsers, OS, goals, outbound links, downloads, 404 pages.
  • Core Web Vitals at p75 with Google's thresholds and the slowest-LCP pages. Retention 30–3650 days (default 395). JSON API GET /pursae/v1/analytics.
Not in 0.1 Multi-day uniques are the sum of daily uniques (by design). No filters/drill-down, custom theme events, revenue goals, CSV export, public dashboard, e-mail reports or GeoIP database.

Source: docs/analytics-features.md

Pursae CDN

Object storage, CDN delivery and on-the-fly images: the ground of WP Offload Media, an imgix / Cloudflare Images style image CDN and CDN Enabler, with purging of Pursae Cache and several CDNs. Internal name gocdn, switch native_gocdn.

Storage and offload

  • Amazon S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, MinIO or any S3 API, through an own SigV4 client (no AWS SDK) with a step-by-step connection test.
  • Multipart uploads (from 16 MB by default), server-side encryption (SSE-S3, SSE-KMS, SSE-C), storage class, object versioning; secrets sealed with AES-GCM; configuration via WPGO_CDN_SETTINGS.
  • New uploads and all sizes copied in the background; optional removal of local files; removed files answered by redirect, presigned URL or proxy; resumable bulk offload, download-back, remove and "move to the current bucket" jobs.
  • Deactivation never breaks URLs: files that exist only in the bucket keep being served.
  • Remote storage browser and a "Remote storage" tab in the media picker (import as copy or link).

Images and assets

  • Image service /cdn-img/<path>?w=&h=&fit=&q=&fm=: JPEG, PNG, GIF, WebP and AVIF (off by default), animated GIFs, fm=auto negotiation, signed URLs, abuse limits, disk or bucket variant cache. No cgo.
  • Asset CDN for theme, plugin and core files on the front end; CDN origins added to the CSP.
  • URL rewriting on the front end, feeds, sitemaps and REST; editors keep local URLs.

Purge and private files

  • Purge Pursae Cache and one or more of Cloudflare, Amazon CloudFront, BunnyCDN, KeyCDN and Fastly, concurrently; automatic purge on changes.
  • Private files under uploads/private/, delivered only through expiring signed links; Commerce downloadable files use them.
Limits AVIF sources are not accepted, no surrogate-key / tag purges, SSE-C objects have no public or presigned URLs, presigned URLs are not written into cached page HTML.

Source: docs/gocdn-features.md

Pursae Backup Manager

Backs a whole site up into one .zip and restores it on the same or another Pursae site, like All-in-One WP Migration, without an SQL dump: rows are exported as JSON lines straight from PostgreSQL, so pg_dump / psql are not needed. Slug backup-manager, menu for administrators.

What is backed up

  • Selectable parts: posts and taxonomy, media library (with uploads), users and roles, settings, themes, plugins, page builder data, each built-in plugin's tables, other plugin data.
  • Users can be limited to all users, chosen roles or picked users; dependent tables (ON DELETE CASCADE) follow automatically.
  • Archive: manifest.json, database/<table>.jsonl and files, with a SHA-256 per entry.

Restore

  • Optional safety snapshot first; the database restore runs in one transaction and rolls back on any failure; files are staged and moved only after the database succeeds.
  • Optional rewrite of the old site URL (also JSON-escaped) to the new address; archives from a newer schema are refused.

Schedule and storage

  • Automatic local backups, keeping 1–100 scheduled archives (default 7); failures shown under Last scheduled backup.
  • Archives in WPGO_BACKUPS_DIR (default <data>/backups, outside the public uploads) with mode 0600; uploads up to 16 GB streamed to disk; one job at a time.
Note A backup holds password hashes and site secrets. Restoring users logs everyone out; restoring plugins needs a restart. Media that exists only in the Pursae CDN bucket is not included. Not yet built: archive encryption, remote storage (S3, FTP, cloud drives), restore on a site not yet installed, merge restore.

Source: docs/backup-manager-features.md

Pursae Maintenance

A clone of Maintenance by WebFactory (v4.32) with the parts of Maintenance PRO that suit a single-site install, plus a SeedProd-style Coming Soon mode and scheduled window. Switch native_maintenance, settings in maintenance_settings. The gate runs before the page cache, so a closed site never serves a cached page.

Modes and access

  • Maintenance mode (503 + Retry-After) or Coming Soon mode (200); no-cache headers always, noindex by default.
  • Admin bar indicator with toggle; scheduled start, countdown with auto-disable.
  • Bypass: logged-in users (with a role filter), crawlers, IP and CIDR whitelist, URL rules with prefixes, secret link, site password (bcrypt, rate-limited), login form on the page.
  • Anonymous REST gets a JSON 503 (403 in Coming Soon); feeds and sitemaps gated by default; ?maintenance-preview.

Page design

  • 7 built-in themes (Default, Minimal, Card, Split, Neon, Sunrise, Editorial); logo, background image/colour/gradient, blur, overlay, 7 system font stacks, custom CSS. Nothing is loaded from other servers.
  • Or a published Pursae Web Builder template as the page.
  • Modules: countdown, progress bar, subscribe form (double opt-in, consent note, CSV export, notify subscribers), social icons, custom HTML.
  • SEO title, description, favicon, og:image, GA4 (held by Pursae Cookie when active); texts translated with Pursae Multi Language.
Left out YouTube video backgrounds, maps and videos (third-party frames), a preloader, reCAPTCHA, mailing-list integrations, drag-and-drop ordering (use a Web Builder template), Force SSL and white-label.

Source: docs/maintenance-go-features.md

Pursae Headless

Turns the site into a headless CMS: a Content-Type Builder, a Content Manager and a delivery API for Next.js, Nuxt, Astro or mobile apps, following the conventions of popular open-source headless CMSs (collection and single types, components, dynamic zones, filters[field][$op], populate, documentId). Internal name headlessgo, switch native_headlessgo. No single WordPress plugin matches it.

Modelling and editing

  • Field types: text, rich text (blocks or Markdown), numbers, boolean, dates and times, email, password (argon2id), enumeration, media, relation, JSON, UID, component, dynamic zone.
  • Relations of every cardinality, to content types, WordPress posts, pages, users, any public post type or taxonomy; bidirectional relations kept in step.
  • Schema changes migrate stored data (renames, removals, type conversions); NDJSON entry export/import and JSON schema export/import.
  • Content Manager with draft & publish, i18n through Pursae Multi Language, bulk actions, content history with restore, scheduled publishing, edit locks and a review-before-publishing flow.

Delivery API

  • REST at /wp-json/headlessgo/v1: CRUD, publish, schedule, media upload, filters, full-text _q, sorting through relations, pagination, populate, fields, locale and status; openapi.json and TypeScript types generated from the model.
  • GraphQL with mutations, fragments, directives, introspection and spec validation; subscriptions over WebSocket (graphql-transport-ws) and server-sent events.
  • Public permission matrix (nothing public by default), API tokens (read-only, full, custom; SHA-256 only), optional signed-in users with JWT, CORS allow-list, rate limit, ETag/304 and CDN cache tags.
  • Signed webhooks with a durable retry queue; preview URLs with short-lived preview tokens; headless mode that stops the front end from rendering.
Limits Subscriptions see only the writes of their own process; a read may run at most 1000 queries and load 20000 related entries; REST and GraphQL are not locked and cannot review; signed-in users have no refresh tokens; admin strings are translated only into Turkish.

Source: docs/headlessgo-features.md

Pursae Forum

Discussion boards in the class of bbPress, written from scratch (0.2.5). Switch native_pursae_forum. Every view renders as a page of the active theme; four library themes ship with forum demo content: Campfire, Devboard, Guild Hall and Study Circle.

Forums and posting

  • Categories holding forums, pinned and closed topics, posting without JavaScript, basic HTML sanitized twice, PostgreSQL full-text search, profiles and a member list.
  • Topic tags, views, sort tabs (latest, popular, unanswered, solved), likes, accepted answers, who is online, similar topics, drafts and preview, follow by e-mail, post reports.
  • Shortcodes [pursae_forum] and theme functions such as forum_user_menu; public read-only forum/v1 REST.

Members

  • E-mail sign-up with a 48-hour confirmation link, login with Pursae Security's rules, "Continue with Google" (OAuth 2.0 with PKCE, OpenID Connect).
  • Profile photos (up to 2 MB, cropped to 512 px), initials avatars, no Gravatar.
  • Points, six default levels (Newcomer to Legend, up to 30) and rule-based or hand-awarded badges (up to 100).
  • Spam guards: honeypot, signed time token, captcha, sign-up and posting rate limits, flood interval.

Moderation and integration

  • Front-end moderator bar, an admin queue, first-post moderation, blocking, an edit window (30 minutes by default).
  • Admin tabs: Overview, Forums, Moderation, Members, Badges & Levels, Settings, Google sign-in.
  • Language prefixes and hreflang with Pursae Multi Language; cacheable visitor pages tagged forum.
Not in 0.2.5 Per-language forums, guest posting, private forums, reply threading, topic merge/split, the weekly digest mail, forum RSS and sitemap entries, Web Builder widgets and bbPress importers.

Source: docs/forum-features.md

Web Builder

Pursae Web Builder

A section-based visual page builder that ships inside the binary. Visitors never load React: a published page is a static HTML/CSS snapshot with a small optional script.

What it is

Pursae Web Builder is a built-in plugin (slug golementor, option native_golementor). The editor is a React app built from github.com/pursae/Builder. With the Theme Builder it also designs the site's header, footer and content templates, shown by the bundled Hello Pursae theme.

  • It is off on a fresh install. Plugins › Pursae Web Builder › Activate turns it on and switches the site to Hello Pursae; the previous theme is remembered (web_builder_previous_theme) and a notice offers Switch back.
  • While the plugin is off there are no menu entries, "Edit with" links, routes, assets or front-end output; built pages show their readable fallback inside the theme.
  • Web Builder › Settings (manage_options) picks the post types the builder edits (pages and posts by default) and lists pages to Regenerate.
  • The editor UI is English, with Turkish included (picked from the user's language).

Overview: docs/developer/web-builder.md

Editor concepts and editing flow

  1. Open a page with Edit with Pursae Web Builder (block editor toolbar, classic editor, row action, or the site toolbar). The URL is /wp-admin/post?post={id}&action=web-builder; it needs edit_post and takes the WordPress post lock.
  2. Build from sections: navigation, hero, banner, features, media, steps, quote, FAQ, call to action, footer, text, image, form, layout and custom, or a saved section from the library. Switch between desktop, tablet and mobile.
  3. Changes autosave every few seconds as your own draft; the live page is untouched.
  4. Publish renders the page in the browser and sends the document plus snapshot; the server validates and sanitizes both. Users who may not publish get Pending Review. A concurrent publish shows a conflict instead of overwriting.
  5. Every publish is also a core revision; the builder keeps the document of each one (newest 50 per page).
  6. Preview (?preview=true) shows the last published snapshot.
Detached pages Editing a built page elsewhere (block or classic editor, Quick Edit, REST) detaches it: the site shows the edited content inside the theme, and the builder offers to publish again (discarding outside edits) or leave the page to the other editor.

Site settings and design tokens

  • While the builder is on the Customizer is hidden; Site settings in the editor's menu edits title, tagline, logo, site icon, homepage and Additional CSS (edit_theme_options).
  • Design tokens: five colours (primary, secondary, accent, text, background) and two fonts (heading, body) as --wb-color-* / --wb-font-* on :root. A snapshot using var(--wb-color-primary) follows a change without republishing.

What visitors get

  • Page CSS is inlined up to 24 KiB (a cached file above that); fonts are local @font-face; images go through the core image filters.
  • The runtime (runtime.<hash>.js, under 8 KB gzipped) loads only when the page uses menus, FAQ/accordions, tabs, dismissible bars, forms, motion or embeds. Content is readable with JavaScript off.
  • Forms post to web-builder/v2/forms/{page}/{section} with a honeypot, minimum fill time, per-IP rate limit and the Pursae Contact Form captcha; messages go to the admin e-mail.
  • Everywhere else (REST content.rendered, Headless, feeds, search, sitemaps, exports) the page is the fallback HTML generated from the document into posts.content.
  • Popups are templates of type popup: triggers on load, scroll depth, exit intent or click; frequency every view, per session, once, or every N days; up to five per page; state kept in localStorage / sessionStorage (wb-popup:<id>), not a cookie.
Not yet AI (stubbed out; no AI request leaves the site), fold-out drop-down menus, form integrations and payments, global classes and kits, a setup wizard.

Theme Builder

Web Builder › Theme Builder (edit_theme_options) lists the site's templates. A template is a builder document designed with dynamic widgets and post loops, filled with real content at request time. Templates show only while Hello Pursae is active; a template is active when published, a draft or disabled template never shows.

TypeFillsDefault condition
Headertop of every pageEntire Site
Footerbottom of every pageEntire Site
Single Postmain content of postsAll posts
Single Pagemain content of pagesAll pages
Singleentries of one custom post typeAll entries of that type
Front Pagethe front pageFront Page
Archiveblog, category, tag, author, date and post type archivesAll Archives
Search Resultssearch resultsSearch Results
404 Pagethe "not found" page404 Page
Single Product / Product ArchivePursae Commerce product and shop views (only while Commerce is on)—

Dynamic widgets

GroupWidgets
SiteSite logo, Site title, Tagline, Menu, Search form, Copyright
PostPost title, Post content, Post excerpt, Featured image, Post info, Post terms, Post date, Post author, Author box, Post navigation, Comments, and Posts (a loop)
ArchiveArchive title, Archive description, Pagination
SearchSearch query

The editor draws widgets with real content chosen in Preview as; it never invents sample content. The Posts loop repeats one designed card with a source of Posts of the page (the only one with pagination), Custom query (1–24 posts, order, terms, author, offset, exclude current) or Related posts.

Display conditions

Each rule is Include or Exclude plus a place: Entire Site, Singular (…), Archives (…), 404 Page. Any matching Exclude removes a template; otherwise the most specific rule wins:

  1. a specific item, term or author;
  2. Front Page and 404 Page;
  3. In a term, Child of, By author;
  4. a post type; Posts Page, Date Archives, Search Results, Author Archives, a post type archive, all terms of a taxonomy;
  5. All Singular, All Archives;
  6. Entire Site.

Ties go to the higher Priority (−100 to 100, default 0), then the more recently changed template. A Search Results template beats an Archive template with the same rule on a search page.

How a page is assembled

With Hello Pursae active every page is Header + Main + Footer. Main is the page's own builder design, else the matching main template, else the theme default. A builder page chooses Site templates or This page only (canvas). ?wb_template_preview=<id> forces a template for preview; publishing, disabling, trashing or changing conditions clears Pursae Cache.

Guide: docs/developer/web-builder-theme-builder.md

Theme library in the builder

The builder's theme library offers market themes as ready-made full-site designs. Open it from Web Builder › Theme Library or the editor's Studio › Items › Components › Browse theme library. One import creates the Theme Builder templates (Header, Footer, Front Page, Single Post, Single Page, Archive, Search Results, 404 Page) with conditions, the theme's demo pages and images, and its menus on the primary and footer locations.

ChoiceResult
Replace themthe theme's templates go live; yours are disabled (drafts, never deleted)
Keep boththe theme's templates are saved as drafts; nothing changes on the site (no menus)

Your posts, pages, categories, users and settings are never touched; re-importing is idempotent (post meta _wb_theme, _wb_theme_key). Needs edit_theme_options, plus edit_pages and publish_pages.

Import flow

  1. POST /web-builder/v2/themes/{slug}/import {mode: "replace" | "keep", pages: bool}: images imported, templates and pages created as drafts.
  2. The editor draws and publishes each doc through the ordinary publish route.
  3. POST /web-builder/v2/themes/{slug}/finish: in replace mode other templates of those types are set to draft, menus assigned, cache purged.

Making a library theme importable

Add "web_builder": "web-builder/parts.json" to theme.json and ship the file (format web-builder-theme, version 1):

{
  "format": "web-builder-theme", "version": 1,
  "templates": [
    {"key": "header", "type": "header", "title": "Header", "conditions": ["include/general"], "priority": 0, "doc": {"site": {}, "sections": []}}
  ],
  "pages": [
    {"key": "about", "slug": "about", "title": "Our promise", "doc": {}, "page": {"layout": "site"}}
  ]
}
  • doc is a builder DocState, validated like a publish; {{media:<id>}} is replaced by the demo image URL.
  • Menus and images come from demo/demo.json; type is any template type except single; key is a-z0-9- and unique.
  • Bind header and footer to menus (menu: "primary", logoSource: "site") and use dynamic widgets, so one theme fits any site.

The integration contract

The contract is the single source of truth for how the React editor talks to the Go server. Its two halves, internal/webbuilder/contract.go and builder/host/contract.ts, must match field for field and change in one commit.

Versions and handshake

ConstantValueMeaning
APIVersion2REST and boot schema (2 = Theme Builder)
RendererVersion1static markup + runtime attributes
APIHeaderX-WB-Apisent by the editor on every web-builder/v2 request
  • Incompatible payload changes bump APIVersion; only incompatible static-markup changes bump RendererVersion (additive data-wb-* attributes do not).
  • A missing or different X-WB-Api answers 409 wb_api_mismatch; the editor stops autosaving and offers "Reload".
  • Boot config window.__WEB_BUILDER__ never contains an AI key or secret.

Document model and publish

  • The page document (doc, JSON) is the source of truth; the snapshot and CSS from the browser are untrusted.
  • Publish runs in one transaction: API check, edit_post, lock (409 wb_locked), revision check (baseRev, 409 wb_rev_conflict), doc validation (422 wb_invalid_doc), stripping html sections and custom CSS without unfiltered_html, sanitizing, writing fallback HTML to posts.content, upserting the docs row, purging the cache. The response lists what was stripped.
  • Drift: if sha256(posts.content) != content_hash after an outside save, the page is detached; only a publish with reattach: true clears it.
  • Storage (migration 0027_web_builder.sql): web_builder_docs, web_builder_drafts, web_builder_revisions, web_builder_library. Templates are posts of type wb_template (migration 0029).

Validation rules (key limits)

RuleLimit / allowed
Request body≤ 4 MiB (413 wb_too_large)
Top-level sections / items per section / Item.sub nesting≤ 200 / ≤ 500 / ≤ 4
Ids^[A-Za-z0-9_-]{1,64}$, unique per doc
Section kindnav hero banner features media steps quote faq cta footer text image form layout html custom, and loop
Strings≤ 64 KiB; html section content ≤ 256 KiB
hrefhttp, https, mailto, tel, #…, relative
Privileged (unfiltered_html only)html sections, style.css
Snapshotexactly one root div.wb-page[data-wb-root]; ≤ 2 MiB; on* and non-data-wb-* data attributes dropped; script, style, object, embed… dropped
iframesYouTube (nocookie), Vimeo embeds, or sandbox="allow-scripts" + srcdoc from unfiltered_html authors
CSSno @import, expression(, javascript:; @font-face only from /wp-content/uploads/web-builder/fonts/; total ≤ 1 MiB; </style → 422

Runtime and Theme Builder model

  • Runtime features: menu acc tabs dismiss form motion embed, all as data-wb-* attributes; every hiding rule is scoped to .wb-js and prefers-reduced-motion is honoured.
  • Condition grammar <mode>/<scope> (e.g. include/general, include/singular/post, exclude/archive/category/12) with scores from 10 (general) to 50 (a specific item, term or author); at most 50 rules per template, 200 bytes each.
  • Snapshot placeholders (data-wb-slot, data-wb-if, data-wb-loop, data-wb-menu-loc…) are filled by the server on each request, so templates never need republishing when posts, menus or the logo change.
  • PageSettings.layout: site or canvas.

Full contract: docs/developer/web-builder-contract.md

Themes

Themes

A Pursae theme is a set of Go html/template files plus assets and a manifest. Theme packages carry no code at all: the core prepares every piece of data and the theme only decides how to print it.

Overview: bundled themes and theme packages

A theme is a set of templates and assets, plus a description of the widget areas, menu locations and Customizer options it offers and the styles and scripts it loads. There are two kinds:

Bundled Go themesTheme packages
ExamplesTwenty Sixteen, Twenty Seventeen, Twenty Twenty, Twenty Twenty-One, Twenty Twenty-Five, Classic, Hello Pursaeanything you upload
Wherecompiled into the binary (web/themes/<slug>/ + a theme_<slug>.go)<data>/themes/<slug>/ (WPGO_THEMES_DIR)
functions.php equivalentGo code: a *Theme registered at start-up with hooks for wp_head, body classes, template datatheme.json: everything a Go theme registers in code, declared as data
Installship with PursaeAppearance › Themes › Add Theme › Upload, or from the marketplace
Codeyes (Go, reviewed with the core)none: templates, CSS, JS, images. Not signed; verified by SHA-256

Everything a package can express is also what the bundled Classic theme uses, so web/themes/classic/templates is the reference implementation.

What a theme controls

  • the markup of every page kind: index, single, page, archive, search, 404 and the parts header, footer, sidebar, comments;
  • its stylesheets and scripts, editor styles and preloaded fonts;
  • widget areas and menu locations;
  • Customizer sections and settings with live preview;
  • what the block editor knows about it: colour palette, wide alignment, supports;
  • how Pursae Forum looks: the forum page wrapper, the forum's colour tokens and any forum view.

What the core does for every theme

The core builds the whole page model (document title, wp_head() output, body classes, the loop, pagination, comments, menus, widget areas, the admin bar) and the theme decides how to print it. A theme never queries the database or sanitises input, which is why packages can be code-free and safe to install.

Web Builder pages A page published from Pursae Web Builder is served as a canvas document without the theme's header, footer and stylesheet. Theme Builder templates replace a theme's output only on the bundled Hello Pursae theme; a theme package cannot receive Theme Builder parts.

Source: docs/developer/themes/index.md

Your first theme

A theme package is a directory with no code in it:

starter/
  theme.json          metadata, widget areas, menus, styles, customizer options
  templates/          Go html/template files
    index.html
    single.html
    page.html
    header.html
    footer.html
  assets/
    style.css
    screenshot.png
  readme.md           optional, shown on the marketplace page

1. theme.json

The minimum:

{
  "slug": "starter",
  "name": "Starter",
  "version": "1.0.0",
  "description": "A minimal starting point.",
  "author": "Gopher Co.",
  "screenshot": "screenshot.png",
  "menu_locations": [{"id": "primary", "name": "Primary Menu"}],
  "widget_areas": [{"id": "sidebar-1", "name": "Sidebar", "description": "Appears on the right."}],
  "styles": [{"handle": "starter-style", "src": "assets/style.css"}]
}

2. Templates

templates/index.html is the only required template; the others fall back to it along the WordPress hierarchy. A complete blog index.html:

{{template "header" .}}
<main id="main" class="site-main">
{{range .Posts}}
  <article id="post-{{.ID}}" class="{{.Class}}">
    <h2 class="entry-title"><a href="{{.Permalink}}">{{.Title}}</a></h2>
    <div class="entry-meta">{{.EntryMeta}}</div>
    <div class="entry-content">{{if .ShowExcerpt}}{{.Excerpt}}{{else}}{{.Content}}{{end}}</div>
  </article>
{{else}}
  <p>Nothing found.</p>
{{end}}
{{.Pagination}}
</main>
{{template "footer" .}}

header.html and footer.html define the parts the pages include:

{{define "header"}}<!doctype html>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{.DocumentTitle}}</title>
{{.Head}}
</head>
<body class="{{.BodyClass}}">
{{.BodyOpen}}
<header class="site-header">
  {{.CustomLogo}}
  <p class="site-title"><a href="{{.HomeURL}}" rel="home">{{.SiteName}}</a></p>
  <p class="site-description">{{.Description}}</p>
  {{with index .Menus "primary"}}<nav aria-label="Primary"><ul class="menu">
    {{range .}}<li class="menu-item{{if .Current}} current-menu-item{{end}}"><a href="{{.URL}}">{{.Label}}</a></li>{{end}}
  </ul></nav>{{end}}
</header>
{{end}}

{{define "footer"}}
{{with index .Areas "sidebar-1"}}<aside class="widget-area">{{.}}</aside>{{end}}
<footer class="site-footer">{{.PrivacyLink}}</footer>
{{.Footer}}{{.AdminBar}}
</body>
</html>
{{end}}
Keep the hooks {{.Head}} prints wp_head() (feeds, block styles, your enqueued styles, the Customizer's CSS, plugin assets) and {{.Footer}} prints wp_footer(). Without them scripts, the admin bar and plugins do not work.

3. Assets

Put style.css, scripts, fonts and images under assets/ and reference them from theme.json (styles, scripts, preload_fonts, editor_styles). screenshot.png (1200×900) is the Themes screen thumbnail.

4. Zip it

cd starter
zip -r ../starter.zip theme.json templates assets readme.md

The files sit at the zip root (a single top-level folder is also accepted and stripped). Limits: 32 MiB per package, 4 MiB per file, and only these extensions: .json .html .css .js .map .svg .png .jpg .jpeg .gif .webp .avif .ico .woff .woff2 .ttf .otf .md .txt.

5. Upload and activate

Appearance › Themes › Add Theme › Upload Theme, choose starter.zip. The package is validated (theme.json, template syntax, file types), unpacked to <data>/themes/starter/ and listed on the Themes screen. Live Preview shows it without activating; Activate switches the site. A package whose slug matches a bundled theme is rejected.

6. Iterate

Upload again, or edit in place with Appearance › Theme File Editor (the overlay directory is the same <data>/themes/starter/). During development point WPGO_THEMES_DIR at your working copy: the server loads every <dir>/<slug>/theme.json at start-up.

Hello Pursae and the Theme Builder

Hello Pursae (hello-pursae) is a bundled Go theme made for Pursae Web Builder: a blank canvas whose header, footer, single, archive, search and 404 views are designed in the builder's Theme Builder. Without templates it is a plain, usable theme: a minimal header, the content and a footer.

ItemValue
Menu locationsprimary (Primary Menu), footer (Footer Menu)
Supportscustom-logo, title-tag, post-thumbnails, menus, html5, align-wide, responsive-embeds, editor-styles, automatic-feed-links
Filesweb/themes/hello-pursae/templates/header.html, pages.html, content.html; assets/style.css, editor-style.css, screenshot.png
Codeinternal/server/theme_hellopursae.go
Body classeshello-pursae, plus wb-site when at least one Theme Builder part renders

When it becomes active

Activating Pursae Web Builder switches the site to Hello Pursae and stores the previous theme in web_builder_previous_theme; deactivating the plugin switches back while the site is still on Hello Pursae (the default theme when the previous one is gone). If the user picked another theme in between, nothing changes. Sites that had the builder on before Hello Pursae existed get a one-time "Switch to Hello Pursae" notice instead of a silent switch.

How templates replace the theme's output

Theme Builder templates are used only while Hello Pursae is the active (or previewed) theme. The check is on the slug, so a theme package or another bundled theme never receives template parts. For each request the core picks templates by their display conditions and hands the finished markup to the theme in .Data.wb:

FieldWhatWithout it
.Data.wb.Headerthe header template, filledHello Pursae's header: custom logo or site title, tagline, the primary menu
.Data.wb.Mainthe page's own builder design, else the matching Single Post, Single Page, Single, Front Page, Archive, Search Results or 404 template, filledthe theme's default view
.Data.wb.HasMainMain carries its own <main> landmark—
.Data.wb.Canvasa builder page set to canvas: print no header and no footer—
.Data.wb.Footerthe footer template, filledthe footer menu, copyright and privacy link
{{define "site-header"}}{{$wb := .Data.wb}}{{if and $wb $wb.Canvas}}{{else if and $wb $wb.Header}}<div class="wb-part wb-part-header">{{$wb.Header}}</div>{{else}}<header id="site-header" class="site-header">…</header>{{end}}{{end}}

The page always has exactly one <main> and the skip link's #content target. The core merges the fonts of all parts, prints each part's CSS as <style id="wb-css-<post id>">, adds the builder's base CSS and runtime once, and adds Edit Header / Edit Template / Edit Footer to the admin bar.

Editing Hello Pursae's templates can be changed in the Theme File Editor; keep the .Data.wb branches or the Theme Builder parts no longer show. To change a builder site's look, edit the templates in the builder rather than the theme.

Templates and the hierarchy

Templates are Go html/template files. Output is escaped by context automatically; values the core has already rendered as HTML (.Content, .Head, menus, widget areas) are template.HTML and print as-is. Only index.html is required.

RequestTemplates tried, in order
front page showing a static pagefront-page.html, the page's own template, page.html, singular.html, index.html
front page with latest posts, or the posts pagehome.html, index.html
a postsingle.html, index.html
a pagepage.html, index.html
custom post type entrysingle-<type>.html, single.html, index.html
custom post type archivearchive-<type>.html, archive.html, index.html
category archivecategory.html, archive.html, index.html
tag archivetag.html, archive.html, index.html
post format or custom taxonomy archivetaxonomy-<taxonomy>-<term>.html, taxonomy-<taxonomy>.html, taxonomy.html, archive.html, index.html
author archiveauthor.html, archive.html, index.html
date archivedate.html, archive.html, index.html
search resultssearch.html, index.html
not found404.html, index.html
Package spec The theme package spec also lists single-<format> and singular for posts, category-<slug> and tag-<slug> for term archives. A page whose _wp_page_template is set tries that template first, also on the front page.

Parts (header.html, footer.html, sidebar.html, comments.html, content*.html) are included with {{template "header" .}}. Every file is parsed into one template set, so a {{define "name"}} in any file is callable from any other.

The site view (key fields)

GroupFields
Page.Template, .Q (main query: .Q.Kind, .Q.Post, .Q.Term, .Q.Search, .Q.Paged…), .DocumentTitle, .Head, .Footer, .BodyOpen, .BodyClass, .AdminBar, .SiteName, .Description, .HomeURL, .CustomLogo, .SiteIcon, .ThemeMods, .CustomCSS, .Theme, .ThemeURI, .Data
Content.Posts, .Post, .TotalPosts, .TotalPages, .Pagination, .PostNav, .ArchiveTitle, .ArchiveDesc, .SearchQuery, .SearchAction, .SearchHidden, .Comments, .PrivacyLink, .CanPublish
Navigation and widgets.Menus (items per location: .ID, .Label, .URL, .Target, .Classes, .Children, .Current…), .HasMenus, .PrimaryMenu, .SocialMenu, .Areas, .Sidebar1, .ContentBottom
A post.ID, .Title, .Permalink, .Content, .Excerpt, .ShowExcerpt, .Class, .EntryMeta, .EditLink, .Date, .DateText, .DateISO, .AuthorName, .AuthorURL, .Categories, .Tags, .Thumbnail, .ThumbnailURL, .CommentCount, .Post (raw record)
Search forms Write them as <form role="search" method="get" action="{{.SearchAction}}">{{.SearchHidden}}…, not with .HomeURL, so the language of Pursae Multi Language travels with the query.

Functions

FunctionDoes
safe, safeURL, safeAttrmark a string as trusted HTML / URL / attribute
kses swp_kses_post() for user-written HTML
date t formatformat a time in the site's time zone with a WordPress format; "" uses the site's date format
setting, settingStr, settingBool, settingInt, settingIDread an option
plural, num, add, sub, seq, dictnumbers, ranges, maps for parts
list, split, contains, lower, ucfirst, repeat, trimSlash, texturize, query, json, versionstring and encoding helpers
__, _e, esc_html__, esc_attr__, _x, _n…translatable strings (view first: __ . "Skip to content"); listed under Languages › Translations when Pursae Multi Language is on

Package themes also get {{nav_menu . "primary"}}, {{has_nav_menu . "primary"}}, {{dynamic_sidebar . "sidebar-1"}}, {{is_active_sidebar . "sidebar-1"}} and {{theme_mod . "accent"}}, plus .Data.Settings (every Customizer setting, typed) and .Data.Nav (rendered menus by location).

Images with a focal point get object-position added by the core, so object-fit: cover crops keep the point in view without template code.

theme.json

theme.json describes what a Go theme would register in code. Unknown fields are rejected.

Metadata

FieldRequiredRules
slugyes^[a-z0-9]+(-[a-z0-9]+)*$, 2–64 characters; the directory name and the identifier (theme mods, widgets and menus are stored per slug). Bundled slugs are reserved
nameyesshown on the Themes screen
versionyessemver
description, author, author_url, theme_urlnoThemes screen and marketplace; URLs are http(s)
tagsnomarketplace filters (blog, dark, one-column, …)
requires_corenominimum Pursae version (must not be newer than the running one)
screenshotnoa file under assets/, usually screenshot.png

Structure

FieldWhat it registers
widget_areas[]register_sidebar(): id, name, description; optional before_widget, after_widget, before_title, after_title. Printed with {{index .Areas "sidebar-1"}}
menu_locations[]register_nav_menus(): id, name. Assigned under Appearance › Menus
page_templates{"<name>": "<Label>"} for the Page Attributes "Template" select. Name is a handle, not index, page, front-page or singular; templates/<name>.html must exist; label one line, max 80 characters, no markup

Assets

FieldMeaning
styles[]wp_enqueue_style(): handle, src, deps, media
scripts[]wp_enqueue_script(): handle, src, deps, in_footer
editor_styles[]add_editor_style(): loaded into the block editor and TinyMCE
preload_fonts[].woff2 files under assets/, preloaded in wp_head on every page
block_stylestrue: per-block core styles, inlined; an array of block names also leaves those blocks out; default false (whole block library)

Editor and Customizer

FieldMeaning
palette[]editor-color-palette: name, slug, color; also printed as --wp--preset--color--<slug>
supportstitle-tag, custom-logo, post-thumbnails, html5, responsive-embeds, align-wide, wp-block-styles, custom-spacing, custom-line-height
customizer.sections[]id, title, priority, settings[] (see Customizer)

Library metadata

FieldMeaning
categoryone of a fixed list (blog, magazine, portfolio, shop, restaurant, … 40 values)
styleshort phrase on the library card (max 80 characters, one line, no markup)
demodemo content file, a .json under demo/
web_builderWeb Builder parts file, a .json under web-builder/

The REST themes endpoint reports these as category, style and has_demo.

Styles and scripts

A package loads its assets through theme.json; the core prints the tags in wp_head() and wp_footer() in dependency order, with ?ver=<theme version>.

"styles": [
  {"handle": "starter-fonts", "src": "https://fonts.example.com/inter.css"},
  {"handle": "starter-style", "src": "assets/style.css", "deps": ["starter-fonts", "wp-block-library"], "media": "all"},
  {"handle": "starter-print", "src": "assets/print.css", "media": "print"}
],
"scripts": [
  {"handle": "starter-nav", "src": "assets/js/navigation.js", "in_footer": true},
  {"handle": "starter-gallery", "src": "assets/js/gallery.js", "deps": ["jquery"], "in_footer": true}
],
"editor_styles": ["assets/editor-style.css"],
"preload_fonts": ["assets/fonts/inter-var.woff2"]
FieldMeaning
handlethe tag id: <handle>-css, <handle>-js; pattern ^[a-z0-9]+([_-][a-z0-9]+)*$, unique per list
srca path in the package (served at /wp-content/themes/<slug>/<path>) or an absolute URL
depshandles loaded first; a dependency cycle is an error
mediaall (default), print, screen and (min-width: …)
in_footerprint the script before </body>
CSP Remote URLs must be allowed by the site's Content Security Policy (style-src 'self'; remote stylesheets are not allowed by default, remote scripts never). Ship fonts and scripts in the package.

Core handles

HandleWhat
wp-block-librarythe block library stylesheet, on every page unless block_styles is on
dashiconsthe icon font (loaded with the admin bar)
jqueryjQuery from /wp-includes/js/jquery/
comment-replythreaded replies; enqueued by the core on singular pages with threaded comments

What wp_head prints, in order

  1. the theme's head_top (bundled themes only),
  2. robots, feed links, admin-bar styles for logged-in users,
  3. the block library stylesheet and inline theme/global styles (with block_styles: only the used blocks' styles),
  4. your preload_fonts[], styles[] and head scripts[], then Customizer css_var properties,
  5. rel="https://api.w.org/", generator meta, canonical and shortlink,
  6. custom background, site icon, Additional CSS,
  7. plugin stylesheets and head scripts.

wp_footer prints comment-reply, the admin bar script, your footer scripts and plugin footer scripts.

Fonts, per-block styles and caching

  • Fonts go under assets/fonts/; assets/fonts/inter.woff2 is served at /wp-content/themes/<slug>/fonts/inter.woff2, which is also what url(fonts/inter.woff2) in assets/style.css resolves to. No external font service is contacted unless you add one.
  • "block_styles": true drops the 140 KB render-blocking block-library/style.min.css and inlines only the styles of blocks on the page; then also drop wp-block-library from your deps.
  • styles[] and scripts[] are served with Cache-Control: public, max-age=31536000, immutable: bump version when you ship changes. Files saved in the Theme File Editor and unversioned URLs are no-cache.
  • With Pursae Cache "Defer JavaScript" on and its handle list empty, your scripts[] are deferred too (body scripts only, so prefer in_footer).

Block editor support

The block editor asks /wp-json/wp/v2/themes?status=active what the theme supports and styles its canvas accordingly.

"supports": {
  "title-tag": true,
  "post-thumbnails": true,
  "custom-logo": {"width": 240, "height": 80, "flex-width": true, "flex-height": true},
  "html5": ["search-form", "comment-form", "gallery", "caption", "style", "script"],
  "responsive-embeds": true,
  "align-wide": true,
  "wp-block-styles": true,
  "custom-spacing": true,
  "custom-line-height": true
}
KeyEffect
title-tagthe core prints <title>; always on, kept for compatibility
post-thumbnailsFeatured Image panel; .Thumbnail is filled
custom-logologo control in Site Identity; .CustomLogo renders it (on unless set)
html5HTML5 markup for the listed parts
responsive-embedswp-embed-responsive body class and aspect-ratio CSS
align-wideWide and Full alignments; style .alignwide and .alignfull
wp-block-stylesopinionated core block styles (theme.min.css)
custom-spacing, custom-line-heightpadding/margin and line-height controls

Palette colours appear in every colour control; blocks get has-<slug>-color / has-<slug>-background-color classes and the core prints --wp--preset--color--<slug>, so use var(--wp--preset--color--accent) in your CSS. Block markup is rendered by the core: static blocks as saved, dynamic blocks (latest posts, search, archives, categories, synced patterns, shortcode) in Go.

Not in packages Block patterns and site-editor block templates are not part of theme packages in this version: /wp/v2/templates returns an empty list. Classic templates are the way to build a theme.

Customizer

Appearance › Customize offers Site Identity, Colors, Menus, Widgets, Homepage Settings, Additional CSS, plus the sections a theme declares. Values are theme mods, stored per theme, so switching themes and back keeps them.

"customizer": {
  "sections": [
    {"id": "starter_layout", "title": "Layout", "priority": 40, "settings": [
      {"id": "content_width", "label": "Content width", "type": "radio", "default": "normal",
       "choices": {"narrow": "Narrow", "normal": "Normal", "wide": "Wide"}},
      {"id": "show_sidebar", "label": "Show sidebar", "type": "checkbox", "default": true, "body_class": "has-sidebar"},
      {"id": "footer_text", "label": "Footer text", "type": "textarea", "default": ""}
    ]},
    {"id": "starter_colors", "title": "Theme colors", "settings": [
      {"id": "accent", "label": "Accent", "type": "color", "default": "#2271b1", "css_var": "--accent", "transport": "postMessage"}
    ]}
  ]
}
Setting fieldMeaning
idthe theme mod name (unique across the theme; custom_logo and custom_css are core's)
label, descriptionthe control
typecolor (#rrggbb), text, textarea, number, checkbox, select / radio (with choices), image (attachment id)
defaultused until the user saves; must match the type
transportrefresh (default) or postMessage for a live preview (not for image)
css_varprint the value as a custom property on :root (--accent: #2271b1)
body_classadd this class to <body> when truthy; with {value} the value is filled in (layout-grid)
<footer class="site-footer">{{with index .ThemeMods "footer_text"}}<p>{{.}}</p>{{end}}</footer>
  • Settings in a section named title_tagline appear under Site Identity.
  • With postMessage, the core's preview script applies css_var and body_class changes itself; for anything else enqueue a script that listens for wp.customize('setting_id', …) (see Classic's assets/js/customize-preview.js).
  • Changes are previewed through a changeset and saved together with Publish.

Theme File Editor

Appearance › Theme File Editor opens any installed theme's templates, stylesheets and scripts in the browser, bundled themes included (their Go glue is compiled and cannot be edited).

  • Files are read through an overlay: first <data>/themes/<slug>/<path> (WPGO_THEMES_DIR, the themes volume in Docker), then the embedded copy or the installed package.
  • Saving writes to the overlay, re-parses the template set and test-renders a page; a template or render error is rolled back automatically and shown in the editor.
  • Restore original deletes the overlay file (bundled themes). For a package the overlay and package directory are the same, so edits are edits of the installed files; edited assets are recorded in .edited-files and served no-cache until the package is updated.
  • WPGO_DISALLOW_FILE_EDIT=1 makes the editor read-only. It requires the edit_themes capability.
Not editable Theme glue written in Go, theme.json semantics (re-upload the package for those), and plugins (plugin code is compiled WebAssembly).

Theme package format

Installed themes live in WPGO_THEMES_DIR (default <data>/themes), one sub-directory per slug. The server loads every directory at start-up and after an upload; a package that does not validate is logged and skipped. The directory name must equal the slug.

  • assets/ is served at /wp-content/themes/<slug>/; every path in theme.json must point under assets/.
  • Limits: 32 MiB per package, 4 MiB per file, 64 MiB extracted, 2000 files; allowed extensions only. Templates must parse before anything is replaced.
  • Uploading needs install_themes; a package with an installed slug replaces it only with a higher version (theme mods and widgets are kept). Deleting needs delete_themes; the active theme cannot be deleted.
  • Themes are not signed; the Hub and the installer verify the SHA-256 of the zip.
  • A store theme declares "supports": {"woocommerce": true} and is listed under Pursae Commerce › Store Themes.

Demo content

A theme may ship demo/demo.json plus images under demo/images/ (.jpg, .jpeg, .png, .webp, each ≤ 1 MiB, ≤ 24 images). It is validated on install. Import is offered on the active theme's card, after activation, and as Install & Import Demo in the library; it needs the import capability.

  • Imported items carry _wpgo_demo = "<theme slug>", so a second import skips them and Remove Demo Content deletes exactly them and restores what it changed.
  • Sections: version (1), options (only blogname, blogdescription, posts_per_page, date_format), categories, tags, media, pages, posts, menus, widgets, customizer.
  • Tokens in content: {{media:hero}}, {{media_id:hero}}, {{page:about}}, {{post:…}}, {{category:…}}, {{tag:…}}; each must name an item of the demo.
  • Limits: 24 images, 50 pages, 100 posts, 10 menus, 20 comments per post; menus nest up to 3 levels; the import has a two-minute limit.

Live Preview with demo content

/wp-admin/theme-preview?theme=<slug> shows a theme with its demo imported, in a sandbox: a second site in the PostgreSQL schema wpgo_preview_<slug> with files in <data>/preview/<slug>/. The real site is untouched. At most 8 sandboxes are kept; only GET and HEAD are allowed, and responses carry X-Robots-Tag: noindex, nofollow.

Spec: docs/theme-package.md

Theme library

The library's sources live in library/themes/<slug>/, each a complete theme package, and are published to Pursae Manager (make publish-themes). A site reads the library from Pursae Manager (default https://hub.pursae.com, GET /api/v1/themes, cached 12 hours per license key) or, when WPGO_THEME_LIBRARY_DIR is set, from a directory. Appearance › Add Themes opens on the Library tab with category filters and search; Install uses the same installer as Upload Theme, and a higher library version offers Update.

The repository ships 67 library themes. All have demo content. "Store" marks supports.woocommerce; "Forum" marks Pursae Forum themes; "WB" marks themes with Web Builder parts.

ThemeCategoryStyle
AppNest (appnest)startupMobile app marketing site with phone mockups and store buttons
Archform (archform)architectureMonochrome, concrete texture, huge imagery, grotesk and serif italics
Atelier Nord (atelier-nord)portfolioSwiss grid, big grotesk type
Atlas Academy (atlas-academy)educationBold neo-brutalist course site in violet, coral and mint
Aurum & Pearl (aurum-and-pearl) · StoreshopQuiet luxury jewellery, ivory and gold
Bean There (bean-there)restaurantEspresso café with mint accent, menu board and brew guides
Bright Smile Dental (bright-smile)healthFresh aqua and white, rounded and playful
Byte Notes (byte-notes)technologyDark-first developer blog with code blocks
Campfire (campfire) · ForumpersonalWarm maker community forum, ember and moss on paper
Campus Commons (campus-commons)educationFriendly academic theme for schools and online courses, navy and mustard
Cloudline (cloudline)technologyCrisp blue IT services site with SLA figures and advisories
Crumb & Crust (crumb-and-crust)foodBright recipe blog, rounded cards, coral and butter yellow
Datafield (datafield)scienceChart-inspired research notebook with figures and footnotes
Devboard (devboard) · ForumtechnologyDense developer Q&A board with code styling and a stats sidebar
Dog-Ear Books (dog-ear-books) · StoreshopIndie bookshop, newspaper masthead and shelves
Driftwood Inn (driftwood-inn)hotelBoutique seaside hotel, sandy neutrals and ocean blue, airy serif
Encore (encore)musicDark stage with neon accent
Ever After (ever-after)weddingRomantic wedding site with serif and script type in blush and sage
Evergreen Care (evergreen-care)healthCalm clinic site in soft teal and white with an appointment call to action
Faithful Commons (faithful-commons)religionWelcoming place of worship in gentle stone and gold with arched windows
Fernwood (fernwood) · Store · WBhomeBotanical plant shop, forest green and terracotta
Frame by Frame (frame-by-frame)entertainmentCinematic letterbox magazine in paper, ink and festival gold
Gearhead Garage (gearhead-garage)automotiveCarbon black and racing red auto shop, angled edges, condensed caps
Glow Botanica (glow-botanica) · StoreshopSoft skincare boutique, blush tiles and arches
Good Boy Supply (good-boy-supply) · Store · WBpetsPlayful pet store, navy and sunshine yellow
Green Basket (green-basket) · StoreshopFriendly organic grocery, leaf and butter
Green Pulse (green-pulse)environmentClimate news magazine, deep forest and electric lime, data callouts
Greenleaf Market (greenleaf-market)shopOrganic farm shop on kraft paper, fresh greens and hand-lettered labels
Guild Hall (guild-hall) · Forum · WBgamingDark gaming community hub, lime and magenta on deep violet
Headline Daily (headline-daily)magazineDense news front page, red and black
Hearth & Herb (hearth-and-herb)foodRustic home cooking, herb green and wood, printable recipes
Ink & Needle (ink-and-needle)beautyBlack and bone tattoo parlour with blackletter and blood red
Inkwell (inkwell)blogClassic editorial serif with drop caps and a centered masthead
Ironbeam Construction (ironbeam)constructionSafety yellow and steel, condensed industrial type
Justitia (justitia)legalBurgundy and charcoal, Caslon serif, gold hairlines
Keystone Estates (keystone-estates)real-estateClean agency, forest green and stone, search-first hero
Kiln & Loom (kiln-and-loom) · StoreshopWarm editorial crafts market, terracotta and indigo
Kite & Crayon (kite-and-crayon) · Store · WBkidsBright kids' toy shop, cream with tomato and mint
Launchpad (launchpad)startupSaaS landing page with a gradient mesh hero and changelog
Ledger & Co. (ledger-co)businessCorporate navy and slate, serif headings, brass accent
Little Sprouts (little-sprouts)kidsCheerful primary colours, rounded shapes and wavy edges
Lumen Folio (lumen-folio)photographyDark full-bleed masonry gallery
Nest & Nook (nest-and-nook)homeAiry neutral interiors, masonry rooms, before/after and shop-the-look
Northstar Ventures (northstar-ventures)financeVenture firm in dark navy and silver with serif essays
Numera (numera)financeCalm blue-green, clear tables, friendly geometric sans
Oak & Form (oak-and-form) · StoreshopAiry Scandinavian furniture, linen and oak
Open Hands (open-hands)nonprofitWarm, hopeful charity site with impact numbers and donate buttons
Pageturner (pageturner)booksLiterary author site with Caslon type, oxblood ink and a shelf of book covers
Paper Lantern (paper-lantern)personalCosy handwritten journal on cream paper
Paws & Whiskers (paws-and-whiskers)petsFriendly vet clinic in orange and teal, rounded and playful
Peak Athletics (peak-athletics) · StoreshopEnergetic sports gear, carbon and volt
Petal & Stem (petal-and-stem)shopBotanical florist with bouquet catalogue, peony and moss
Pixel Arcade (pixel-arcade)gamingRetro-futuristic dark UI with pixel type and neon scores
Podwave (podwave)podcastBright, rounded show site with waveforms, violet and coral
Pulse Fit (pulse-fit)fitnessHigh-energy dark gym, electric lime, bold condensed type
Quiet Hours (quiet-hours)minimalMonospaced, text-only, light and dark
Roast & Ritual (roast-and-ritual) · StoreshopWarm coffee roaster, bag-label cards and stamps
Studio Fizz (studio-fizz)agencyBold, colourful and playful
Study Circle (study-circle) · Forum · WBeducationFriendly study-group forum, teal and sunshine yellow on white
Sugar & Saffron (sugar-and-saffron)foodPastel pastry blog, script and serif type, arched photos
Summit Trails (summit-trails)sportsHiking club with topographic contours, slate and alpine orange
Threadline (threadline) · StoreshopMinimal apparel boutique, serif and sand
Trattoria (trattoria)restaurantWarm terracotta trattoria, classic serif, menu with price leaders
Velvet Runway (velvet-runway)fashionEditorial serif magazine, muted luxury
Velvet Salon (velvet-salon)beautyHair and beauty salon in dusty rose and champagne, arched images
Voltage (voltage-store) · StoreshopDark gadget store, big search and glowing cards
Wanderline (wanderline)travelAdventurous travel journal with poster type and sunset colors

Sources: library/themes

Forum themes (Pursae Forum)

Pursae Forum draws every forum page (index, forums, topics, profiles, member list, login, sign-up, account) inside the active theme, so any theme shows the forum unchanged. A theme made for the forum can go further, step by step:

StepWhat you writeWhat you get
1. Nothing—the forum in your page.html chain with its own forum.css
2. Colours and type--pf-* tokens in style.cssevery forum view uses your palette, fonts and radius
3. Wrappersupports: {"pursae-forum": true} and templates/forum.htmlyour own layout for forum views; the forum prints its own title and breadcrumbs
4. Theme widgetsforum_user_menu, forum_recent_topics, forum_stats, forum_urlLog in / Join in the header, latest topics on the home page
5. View overridestemplates/forum/<view>.htmlyour own markup for a view
6. Demoa "forum" section in demo/demo.jsonmembers, forums, topics and replies in one click
  • A forum page is a synthetic page (.Q.Kind page, post ID 0) rendered via forum.html, page.html, singular.html, index.html; the body gets pursae-forum and pf-view-<view>.
  • Overrides must be self-contained, keep the root <div class="pf …" data-view="<view>">, and fall back to the plugin's template if they error.
  • Set tokens (--pf-accent, --pf-surface, --pf-text, --pf-radius, --pf-font…) on body .pf, not on :root; they fall back to Web Builder's --wb-* tokens.

Shipped references: Campfire, Devboard (packages), Guild Hall and Study Circle (package + Web Builder parts). Full guide: docs/developer/themes/forum.md

Plugin development

Plugins

A Pursae plugin is a Go program compiled to WebAssembly, packed in a signed zip and run in a wazero sandbox. It reaches the site only through a small host API, gated by permissions the administrator approves on activation.

Overview and architecture

The site runs each plugin.wasm in wazero, a WebAssembly runtime written in pure Go. The plugin talks to the core only through JSON messages and host functions; every host function and hook is gated by a permission declared in plugin.json.

┌──────────── Pursae ────────────┐      ┌──── plugin.wasm (sandbox) ────┐
│ the_content ──► hooks ───────────────┼─────►│ wpgo.AddFilter("the_content") │
│ [tag] ───────► shortcodes ───────────┼─────►│ wpgo.AddShortcode("tag")      │
│ /wp-json/<slug>/v1/… ► REST routes ──┼─────►│ wpgo.RegisterRestRoute(...)   │
│ Settings › Plugin ◄── settings page ─┼──────┤ wpgo.RegisterSettingsPage()   │
│ jobs table ───► cron_* actions ──────┼─────►│ wpgo.ScheduleEvent(...)       │
│ options, posts, users, storage,      │◄─────┤ wpgo.GetOption, GetPost, …    │
│ transients, HTTP, notices, assets    │      │ (each needs a permission)     │
└──────────────────────────────────────┘      └───────────────────────────────┘

Why WebAssembly

  • Isolation. No filesystem, no sockets, no environment. A plugin sees only JSON messages from the host and can call only the host functions its permissions allow.
  • Containment. A panic, an infinite loop or os.Exit is caught: the call times out or fails, the filter keeps its original value and the module is re-instantiated. After five consecutive failures the plugin is disabled and the admin sees why.
  • Portability. One plugin.wasm runs on every platform Pursae runs on. The SDK is Go today (wpgo/sdk/go/wpgo); the ABI is plain JSON, so other languages can follow. Test with wpgotest; scaffold and package with wpgo plugin new|build.

What a plugin can do

NeedSDKPermission
Change rendered post content and titles (the_excerpt is reserved, not fired yet)AddFilter("the_content", …), AddFilter("the_title", …)content:filter
Run code at start-up or on admin screensAddAction("init", …), AddAction("admin_notices", …)— / admin:notices
Shortcodes [tag attr="v"]…[/tag]AddShortcodecontent:filter
REST endpoints under /wp-json/<slug>/v1/RegisterRestRouterest:routes
Read and write postsGetPost, QueryPosts, InsertPost, UpdatePostposts:read, posts:write
Know who is logged inCurrentUserusers:read
Scheduled tasksScheduleEvent, AddAction("cron_…")cron
A settings page under SettingsRegisterSettingsPage, Setting*admin:settings, options:read
OptionsGetOption, UpdateOptionoptions:read, options:write
Private data and cachesStorage, Transientsstorage
Outbound HTTP GETHTTPGethttp:outbound
CSS and JS on the site or in the adminEnqueueStyle, EnqueueScript + assets/ in the packagecontent:filter
Dashboard noticesAdminNoticeadmin:notices
Admin pages, Dashboard widgets, meta boxesRegisterAdminPage, RegisterDashboardWidget, RegisterMetaBoxadmin:pages, admin:dashboard, admin:metaboxes
Dynamic blocks, Web Builder widgetsRegisterBlock, RegisterBuilderWidgetblocks:register, builder:widgets

Signing and trust

Packages are signed with Ed25519. A site installs a package only if its signature verifies against a key it trusts (WPGO_PLUGIN_KEYS or the plugin_trusted_keys option), or if the administrator explicitly allows unsigned packages for development. Plugins published through the Hub are re-signed with the Hub's key, which sites trust automatically. Files under assets/ are covered by the signature through their digests in plugin.json.

Source: docs/developer/plugins/index.md, runtime internals in internal/plugins/README.md.

Your first plugin

You need Go 1.27 and a checkout of the Pursae repository (for the SDK module and the wpgo-pkg tool). The plugin is an ordinary Go main package.

1. Create the module

The SDK lives in the repository as wpgo/sdk/go/wpgo; since the wpgo module is not published separately yet, the simplest layout is a directory inside the repository:

cd pursae
mkdir -p examples/plugins/hello-reader
cd examples/plugins/hello-reader

To keep the plugin in its own repository, point a module at your checkout:

go mod init example.com/hello-reader
go mod edit -require=wpgo@v0.0.0 -replace=wpgo=../pursae

2. Write the code (main.go)

// Command hello-reader greets readers at the end of every post.
package main

import (
	"html"

	"wpgo/sdk/go/wpgo"
)

func init() {
	// Filters receive the current value and the extra arguments the core passed.
	wpgo.AddFilter("the_content", wpgo.DefaultPriority, func(_ wpgo.Context, content string, args []any) string {
		post, _ := args[0].(map[string]any)
		if single, _ := post["is_single"].(bool); !single {
			return content
		}
		name := "reader"
		if u, _ := wpgo.CurrentUser(); u != nil { // needs users:read
			name = u.DisplayName
		}
		return content + "<p class=\"hello-reader\">Thanks for reading, " + html.EscapeString(name) + "!</p>"
	})
}

func main() {} // never called: the host drives the plugin through its exports

Hooks registered in init are queued and sent to the host when the plugin is initialised; callbacks registered with wpgo.OnInit run right after that and may already call host functions.

3. Describe it: plugin.json

{
  "slug": "hello-reader",
  "name": "Hello Reader",
  "version": "1.0.0",
  "description": "Greets readers at the end of every post.",
  "author": "You",
  "requires": "0.1.0",
  "license": "GPL-2.0-or-later",
  "permissions": ["content:filter", "users:read"],
  "hooks": ["the_content"]
}

Every subscribed hook must be in hooks, and every permission a hook or host function needs must be in permissions; the manifest is validated on pack and on install.

4. Build

GOOS=wasip1 GOARCH=wasm CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -buildmode=c-shared -o plugin.wasm .
Use c-shared. -buildmode=c-shared produces a WASI reactor whose exports can be called after initialisation. The default build mode produces a command whose runtime exits when main returns; the loader rejects it and tells you to use c-shared.

5. Pack and sign

go build -o wpgo-pkg ./internal/plugins/cmd/wpgo-pkg     # once, from the Pursae checkout
./wpgo-pkg keygen -out mykey                             # writes mykey.pub and mykey.key (keep .key private)
./wpgo-pkg pack -dir examples/plugins/hello-reader -wasm plugin.wasm -key mykey.key -out hello-reader-1.0.0.zip
./wpgo-pkg verify -pub mykey.pub hello-reader-1.0.0.zip

pack takes plugin.json, readme.md, icon.svg and the assets/ directory from -dir. tools/build-plugins.sh does steps 4 and 5 for every example plugin with a development key.

6. Install

  • Trust your key: WPGO_PLUGIN_KEYS='<contents of mykey.pub>' in the environment, or paste it into the plugin_trusted_keys option. For local hacking you can set plugin_allow_unsigned instead.
  • Plugins › Add Plugin › Upload Plugin, choose the zip, then Activate. The activation screen lists the manifest's permissions; tick the ones you grant.

Open a post: the greeting is there. The plugin's log (last lines shown on the Plugins screen) tells you when a call was refused or failed.

7. Iterate

wpgo plugin new -slug my-plugin -sdk /path/to/pursae writes plugin.json, main.go, a unit test using wpgotest, readme.md and a go.mod. wpgo plugin build -dir my-plugin [-key mykey.key] compiles to Wasm and packs in one step; wpgo plugin keygen|pack|verify are the wpgo-pkg commands, so the released wpgo binary is enough to package a plugin. Re-upload (the same slug replaces the package), deactivate and activate. Unit-test callbacks on a normal Go toolchain with wpgo.Dispatch.

Next step. The shortcode-demo example uses shortcodes, REST routes, a settings page, assets, transients and a scheduled event in about 150 lines.

The manifest: plugin.json

plugin.json sits at the root of the package. Unknown fields are rejected, so a typo cannot silently drop a permission.

{
  "slug": "gopher-facts",
  "name": "Gopher Facts",
  "version": "1.2.0",
  "description": "Random gopher facts as a shortcode and a REST route.",
  "author": "Gopher Co.",
  "author_uri": "https://example.com",
  "plugin_uri": "https://example.com/gopher-facts",
  "requires": "0.1.0",
  "license": "GPL-2.0-or-later",
  "permissions": ["content:filter", "rest:routes", "options:read", "admin:settings"],
  "hooks": ["the_content", "cron_gopher_facts_refresh"],
  "shortcodes": ["gopher-facts"],
  "assets": {"style.css": "3f1a…"}
}
FieldRequiredRules
slugyes2–64 characters, ^[a-z0-9]+(-[a-z0-9]+)*$. Identifies the plugin, owns its hooks, prefixes its REST namespace and option names. Reserved: core, built-in plugin slugs (classic-editor, wpgo-cache, goocommerce, …) and core REST namespace roots (wp, wp-admin, wp-json, wp-content, wp-includes, wp-site-health, wp-block-editor, wp-abilities, admin, oembed, batch, pursae, wpgo, wc, wc-admin, wc-analytics, wc-store, wc-telemetry, pll, contact-form-7, web-builder, elementor, gooike, headlessgo, pixelgo, seogo, rankmath, yoast); a package using one is refused at install
nameyesup to 100 characters
versionyes1.2.3 or 1.2.3-beta.1; the Hub refuses a version not newer than the last
descriptionnoup to 2000 characters, plain text
author, author_uri, plugin_urinoURIs must be absolute http(s) URLs
requiresnominimum Pursae version; a plugin needing a newer core is refused at install and activation
requires_pluginsnoslugs of plugins that must be active first (a Wasm slug or a built-in plugin's slug, e.g. contact-form-7); activation is refused and lists the missing ones
licensenoan SPDX identifier
permissionsyes (may be empty)from the permission vocabulary; no duplicates
hooksyes (may be empty)every hook the plugin may subscribe to (letters, digits, _ . : / -, max 128). Registering an unlisted hook is refused at runtime; a hook needing a permission requires it to be declared
shortcodesnoevery tag the plugin may register (^[a-z0-9_-]{1,64}$); needs content:filter
assetsfilled in by wpgo-pkg packpath → hex SHA-256 of every file under assets/; do not write it by hand

The Hub reads the same file and also understands tested_core, author_url and homepage as aliases shown on the marketplace listing.

Validation

wpgo-pkg pack and the site installer both validate and report every problem at once:

plugin.json has 2 problems:
  - hook "the_content" requires the "content:filter" permission; add it to "permissions"
  - unknown permission "posts:all" (known: admin:dashboard, admin:metaboxes, admin:notices, admin:pages, admin:scripts, admin:settings, blocks:register, builder:widgets, commerce:orders, content:filter, content:html, cron, forms:access, headless:entries, http:outbound, mail:send, options:read, options:write, posts:read, posts:write, rest:routes, storage, users:read)

On activation the administrator sees each permission with a one-line description and can grant a subset. The plugin receives the intersection of declared and granted; a call needing more returns permission_denied and is logged, but does not count as a failure.

Permissions

The plugin runs with the intersection of declared and granted permissions. A host function or hook needing a missing permission fails with permission_denied (logged, not fatal).

PermissionShown to the admin asUnlocks
options:readRead site optionsGetOption and friends: the plugin's own options (<slug>_*, plugin_<slug>_*) and the public core options; everything else (secrets, users, mail, licenses, other plugins' and built-in plugins' settings) reads as not found
options:writeCreate and change site optionsUpdateOption for <slug>_* / plugin_<slug>_*, stored in the plugin's own namespace. Core option names are refused even when they start with your slug, as are names starting with auth_, wpgo_, native_, pursae_ or another plugin's plugin_ prefix
posts:readRead posts and receive post data from post lifecycle hooksGetPost, QueryPosts; hooks save_post, save_post_*, wpgo_post_stats, plus reserved post lifecycle names
posts:writeCreate and change postsInsertPost, UpdatePost; reserved hooks wp_insert_post_data, wp_insert_attachment_data, pre_post_update, content_save_pre, title_save_pre, excerpt_save_pre
users:readSee who the current user isCurrentUser
forms:accessSee what visitors submit in contact forms and decide what counts as spamComment hooks preprocess_comment, pre_comment_approved, comment_post; privacy hooks pursae_personal_data_export / pursae_personal_data_erase; Pursae Contact Form wpcf7_* (wpcf7_mail_sent, wpcf7_spam, filters wpcf7_validate and wpcf7_before_send_mail)
headless:entriesSee Pursae Headless entries as they are saved, published and deleted, and validate or derive their valuesheadless_entry_validate, headless_entry_saved, headless_entry_published, headless_entry_unpublished, headless_entry_deleted
content:filterModify content shown to visitorsHooks the_*, comment_text, widget_text, widget_title, get_the_excerpt, wp_title, document_title_parts, body_class, post_class; AddShortcode; EnqueueStyle, EnqueueScript. Added HTML goes through KSES (wp_kses_post)
content:htmlShow unfiltered HTML and scripts to visitors (full control of the site)Unsanitised shortcode and content-filter output; EnqueueScript on the front end. Not ticked by default
admin:scriptsRun code in the admin (full control of the site)EnqueueScript with wpgo.Admin or wpgo.Both; admin styles on every admin screen. Not ticked by default
rest:routesAdd REST API endpointsRegisterRestRoute
admin:settingsAdd a settings page to the adminRegisterSettingsPage; admin EnqueueStyle (printed on the plugin's own settings page only)
admin:noticesShow notices in the admin dashboardHook admin_notices (and all_admin_notices, …); AdminNotice
cronRun scheduled tasksHooks cron_*, wpgo_cron*; ScheduleEvent, ScheduleSingleEvent, UnscheduleEvent
storageStore private plugin dataStorage, Transients
http:outboundMake outbound HTTP requestsHTTPGet, HTTPRequest
mail:sendSend e-mail from the siteSendMail
admin:pagesAdd pages to the admin menuRegisterAdminPage; output sanitised unless admin:scripts
admin:dashboardAdd widgets to the DashboardRegisterDashboardWidget
admin:metaboxesAdd boxes to the post edit screen and see what is typed into themRegisterMetaBox; fields stored as post meta plugin_<slug>_*
blocks:registerAdd blocks to Pursae Editor and render them for visitorsRegisterBlock; output sanitised unless content:html
builder:widgetsAdd widgets to Pursae Web Builder and render them for visitorsRegisterBuilderWidget
commerce:ordersSee store orders: customers' names, addresses and what they boughtHooks woocommerce_*: woocommerce_new_order, woocommerce_order_status_changed, woocommerce_payment_complete

No permission is needed for Log, init, or hooks the vocabulary does not classify.

Options a plugin can read

Its own <slug>_* (dashes as underscores) and plugin_<slug>_* options, plus these public core options: blogname, blogdescription, siteurl, home, WPLANG, timezone_string, gmt_offset, date_format, time_format, start_of_week, use_smilies, default_category, default_post_format, posts_per_page, posts_per_rss, rss_use_excerpt, show_on_front, page_on_front, page_for_posts, blog_public, default_ping_status, default_comment_status, require_name_email, comment_registration, close_comments_for_old_posts, close_comments_days_old, show_comments_cookies_opt_in, thread_comments, thread_comments_depth, page_comments, comments_per_page, default_comments_page, comment_order, show_avatars, avatar_rating, avatar_default, the image size options (thumbnail_size_w … large_size_h, thumbnail_crop), uploads_use_yearmonth_folders, permalink_structure, category_base, tag_base, template, stylesheet, sticky_posts, wp_page_for_privacy_policy, site_icon, users_can_register, blog_charset, html_type.

A plugin's options are stored as wasm:<slug>:<name> in the options table; the plugin keeps using the plain name (GetOption("hello_gopher_footer")) and the host adds the namespace.

Guidelines and enforcement

  • Ask for what the plugin needs today. A content plugin asking for posts:write and http:outbound looks suspicious on the activation screen.
  • Degrade gracefully: wpgo.IsPermissionDenied(err) lets you fall back when an optional permission was not granted.
  • Explain permissions in readme.md; the Hub shows the list on the marketplace page.
  • The check happens in the host before your request is decoded, and again when a hook is registered (add_hook is refused, so the callback never runs). The manifest validator cross-checks hooks and shortcodes against declared permissions on pack and on install.

Hooks

As in WordPress: filters receive a value and return it, actions receive arguments and return nothing. Callbacks run in ascending priority (default 10); core and plugin callbacks share one registry, so a plugin can run before or after core behaviour.

wpgo.AddFilter("the_content", 20, func(ctx wpgo.Context, content string, args []any) string { … })
wpgo.AddAction("admin_notices", wpgo.DefaultPriority, func(ctx wpgo.Context, args []any) { … })

AddFilter is generic: the value is decoded from JSON into your declared type (string, map[string]any, a struct); if decoding fails the host keeps the original value and logs it. ctx carries the plugin slug, hook name and callback id. Every hook must be listed in the manifest's hooks.

Hooks the core fires

HookTypeValue / argumentsPermission
the_contentfilterRendered post HTML (after blocks, autop and shortcodes); argument post: {"id", "type", "is_single"} (is_single is false in archives)content:filter
the_titlefilterTitle HTML (escaped, texturized); argument {"id", "type"}. Additions sanitised unless content:htmlcontent:filter
wp_head, wp_footerfilterMarkup printed so far; return it with your additions (sanitised without content:html)content:filter
admin_noticesactionNo arguments; queue notices with wpgo.AdminNoticeadmin:notices
wpgo_post_statsfiltermap[string]any of statistics in the classic editor's publish box; argument post: {"id", "title", "content"}posts:read
wpcf7_mail_sentactionOne map: contact_form_id, title, posted_data; fired after the mail was sentforms:access
wpcf7_spamfilterSpam verdict (bool); args contact_form_id, posted_data, remote_ip, user_agentforms:access
preprocess_commentfilterSubmitted comment {"post_id", "parent", "user_id", "author", "email", "url", "content", "ip", "user_agent"}; may change author, email, url, contentforms:access
pre_comment_approvedfilterVerdict approved, pending, spam or trash (or 1 / 0); argument: the commentforms:access
comment_postactionComment id, final status, the comment objectforms:access
pursae_personal_data_exportfilterList of groups {"group_id", "group_label", "group_description", "items"}; append your own group. Argument: the e-mail addressforms:access
pursae_personal_data_eraseactionThe e-mail address; erase or anonymize the data you storeforms:access
user_register, wp_loginactionUser id and the user as CurrentUser returns itusers:read
image_editor_output_formatfilterMap source MIME → output MIME (e.g. {"image/jpeg": "image/webp"}); args: file name, MIME type—
pursae_media_replacedactionAttachment id and {"id", "url", "old_url", "new_url", "file", "mime_type", "original_name"}—
pursae_media_focal_pointactionAttachment id and {"id", "url", "focal_point"}—
save_post_<type>, then save_postactionPost id and the post (as GetPost returns it); posts and pages onlyposts:read
transition_post_statusactionNew status, old status ("new" for a new post), the postposts:read
trashed_post, untrashed_post, before_delete_post, deleted_postactionPost id, the postposts:read
woocommerce_new_order, woocommerce_payment_completeactionOrder id, the order {id, status, currency, total, customer_id, payment_method, billing, shipping, items, date_created}commerce:orders
woocommerce_order_status_changedactionOrder id, old status, new status, the ordercommerce:orders
headless_entry_validatefilter{"type", "documentId", "locale", "action", "data"}; add "errors" to reject with a 400 ValidationError (max 20), or change scalar attributes in data. 5 s budgetheadless:entries
headless_entry_saved, _published, _unpublished, _deletedaction{"event", "type", "documentId", "locale", "status", "entry"}headless:entries

Lifecycle hooks

HookWhenPermission
initAfter all active plugins are loaded at start-up; after activation, update or load by another instance it fires for that plugin only—
activateWhen an administrator activates the plugin (wpgo.OnActivate)—
deactivateBefore the plugin is unloaded (wpgo.OnDeactivate); 5 s budget—
uninstallWhen the plugin is deleted (wpgo.OnUninstall); 5 s budget; then its options, transients and events are removed—
cron_<name>Fired by the scheduler with {"plugin": "<slug>", "args": {…}}cron

Reserved names

Permission rules already classify names the core will fire later, so today's manifests stay valid. Subscribing to a hook that is not fired yet is allowed; the callback just never runs.

PermissionHook names
content:filtereverything starting with the_, comment_text, widget_text, widget_title, get_the_excerpt, wp_title, document_title_parts, body_class, post_class
posts:readsave_post, save_post_<type>, wp_insert_post, publish_post, transition_post_status, before_delete_post, deleted_post, trashed_post, untrashed_post, post_updated, wpgo_post_stats
posts:writewp_insert_post_data, wp_insert_attachment_data, pre_post_update, content_save_pre, title_save_pre, excerpt_save_pre
admin:noticesadmin_notices, all_admin_notices, network_admin_notices, user_admin_notices
croneverything starting with cron_ or wpgo_cron
headless:entrieseverything starting with headless_entry_
commerce:orderseverything starting with woocommerce_

Behaviour to know

  • Timeouts: content hook or shortcode 2 s, REST handler 10 s, cron_* 30 s. An overrunning callback is killed, the filter keeps its value, the plugin is re-instantiated on the next call.
  • Failures count: five consecutive failures (panic, timeout, malformed response) disable the plugin. A call that uses 75 % of its budget (1.5 s) counts too; REST and cron are exempt from this slow-call rule. Permission errors do not count.
  • One call at a time: a busy plugin makes a request wait at most one call timeout, then the callback is skipped and logged; such a page is not stored by Pursae Cache.
  • Re-instantiation: a fresh instance runs your init functions and OnInit again, so register everything there.
  • Sanitised output: without content:html, HTML you add is passed through KSES; changes inside <script>, <style> or comments are dropped.
  • Re-entrancy: a callback that would re-enter your plugin on the same call chain is skipped instead of deadlocking.
  • Types survive: a string filter must return a string, wpgo_post_stats a JSON object. Hooks fire with the request's user attached; cron callbacks see no user.

Host API

Each host function is a JSON request to a wpgo import, wrapped by a typed SDK function. Errors are *wpgo.Error with code permission_denied (wpgo.IsPermissionDenied(err)), invalid_request or host_error. Outside the Wasm host every function returns wpgo.ErrNotInHost.

SDKHost importPermission
AddFilter, AddActionadd_hookthe hook's
OnInit(fn)—runs after registrations are sent
Log(level, msg), Logflognone (levels debug, info, warning, error)
GetOption, GetOptionJSON, OptionBoolget_optionoptions:read
UpdateOption(name, value)update_optionoptions:write
GetPost(id), QueryPosts(PostQuery)get_post, query_postsposts:read
InsertPost(PostInput), UpdatePost(id, PostInput)insert_post, update_postposts:write
CurrentUser() (nil for anonymous and cron)get_current_userusers:read
AddShortcode(tag, fn)register_shortcodecontent:filter + tag in manifest
RegisterRestRoute, RegisterRestRouteWithHeadersregister_rest_routerest:routes
RegisterSettingsPage, Setting, SettingString/Bool/Float, SettingNameregister_settings_page, get_optionadmin:settings, options:read
EnqueueStyle, EnqueueScriptenqueue_style, enqueue_scriptcontent:filter (+ admin:settings, content:html / admin:scripts)
RegisterAdminPage, RegisterDashboardWidget, RegisterMetaBox, RegisterBlock, RegisterBuilderWidgetregister_admin_page, register_dashboard_widget, register_meta_box, register_block, register_builder_widgetadmin:pages, admin:dashboard, admin:metaboxes, blocks:register, builder:widgets
ScheduleEvent, ScheduleSingleEvent, UnscheduleEvent, UnscheduleEventArgsschedule_event, unschedule_eventcron (+ hook in manifest)
Storage.Get/Set/Delete/Liststorage_get, storage_set, storage_delete, storage_liststorage
Transients.Get/Set/Deletetransient_get, transient_set, transient_deletestorage
HTTPGet(url), HTTPRequest(HTTPRequestArgs{…})http_get, http_requesthttp:outbound
SendMail(Mail{To, Subject, Body, HTML, ReplyTo})send_mailmail:send
AdminNotice(kind, message)add_admin_noticeadmin:notices
T(text), X(text, context)translatenone

Details

  • Options: readable are the plugin's own and the public core options; writable only its own, stored as wasm:<slug>:<name>. Names at most 191 characters.
  • Posts: Post has ID, Title, Content, Excerpt, Status, Type, Slug, Date, Modified, Author, Link, Terms, Meta. PostQuery: Type, Status, Search, Author, Term, OrderBy, Order, PerPage (1–100, default 10), Page. PostInput fields are pointers (wpgo.String("…")): Title (≤1000), Content (≤1 MiB), Excerpt (≤10 000), Status, Type, Slug, Meta. Meta keys starting with an underscore are refused; content goes through KSES.
  • Users: User has ID, Login, DisplayName, Roles, Caps and Can(cap). Plugins never see e-mail addresses or password hashes.
  • Storage is a private key/value table per plugin (keys ≤256 chars, values ≤1 MiB), deleted with the plugin. Transients are JSON values with a TTL (keys ≤172 chars, values ≤1 MiB), cleaned up daily.
  • HTTP: HTTPGet returns Status, Header, Body (≤1 MiB, larger is an error), 8 s timeout, private and loopback addresses blocked. HTTPRequest supports GET, POST, PUT, PATCH, DELETE, HEAD; ≤32 headers (Host, Content-Length and hop-by-hop refused), body ≤1 MiB.
  • Mail: 1–10 recipients, sender set by the site, 60 messages per plugin per hour.
  • Notices: kinds NoticeInfo/Success/Warning/Error, plain text ≤2000 chars, inside an admin_notices callback.
  • Translation: with Pursae Multi Language on, strings appear under Languages › Translations as "Plugin: name"; otherwise the text comes back unchanged. Text ≤10000 bytes, context ≤200 bytes.
p, err := wpgo.InsertPost(wpgo.PostInput{
	Title:   wpgo.String("Weekly digest"),
	Content: wpgo.String("<p>…</p>"),
	Status:  wpgo.String("publish"),
	Meta:    map[string]any{"digest_week": 43},
})

ABI (version 1)

A plugin is a WASI preview1 reactor module that speaks UTF-8 JSON over guest linear memory. Any language that compiles to wasm32-wasi and exports functions can implement it; the Go SDK is the reference. A packed value is a u64 equal to ptr<<32 | len.

Toolchains. Smaller runtimes (TinyGo, Rust, AssemblyScript) produce much smaller packages than a standard Go build, but only the standard Go toolchain is tested by the project today.
Guest exportSignaturePurpose
_initialize() -> ()language runtime init (Go: runs package inits)
wpgo_init() -> ()called once after _initialize; registers hooks via add_hook
wpgo_alloc(size i32) -> i32allocate a buffer the host writes into
wpgo_free(ptr, size i32)release a buffer returned by wpgo_handle
wpgo_handle(ptr, len i32) -> i64run a callback; returns a packed response

The host sends wpgo_handle:

{"plugin":"slug","callback":"…","hook":"the_content","type":"filter","args":[…],"value":…}

The guest replies with {"value":…} or {"error":"…"}. type is filter, action, shortcode (args = [attrs, content]) or rest (args = [request], value {"status":200,"body":…,"headers":{…}}). UI callbacks use admin_page, dashboard_widget, meta_box, meta_box_save, block and builder_widget.

Host imports live in module wpgo, all with signature (ptr, len i32) -> i64. Each returns a packed pointer to an envelope allocated with wpgo_alloc:

{"ok":true,"result":…}
{"ok":false,"code":"permission_denied|invalid_request|host_error","error":"…"}

An import returns 0 if no response could be delivered. Example requests: add_hook {"type":"filter|action","hook":"…","priority":10,"callback":"…"}; schedule_event {"hook":"cron_x","interval":3600,"at":0,"args":{…}} (interval 0 = one-off at at); register_rest_route {"namespace":"<slug>/v1","route":"/items/(?P<id>\\d+)","methods":["GET"],"callback":"…"}; register_settings_page returns {"option_prefix":"plugin_<slug>_"}. Registrations made with register_* and enqueue_* are kept by the runtime and re-sent after a re-instantiation, so repeating one is a no-op. The guest may call host imports from inside any export.

Full request/result table: docs/developer/plugins/abi.md.

REST routes

With rest:routes a plugin registers routes under its own namespace. The core authenticates the request like any REST request (cookie + X-WP-Nonce, or an Application Password) and passes a RestRequest; the plugin returns a status, a JSON body and optional headers.

  • Namespace: the plugin slug or <slug>/v<N>. Core routes are matched first and foreign namespaces are refused, so plugins never shadow core routes.
  • Route: a regular expression anchored at both ends with named groups, e.g. /items/(?P<id>\d+).
  • Methods: GET, POST, PUT, PATCH, DELETE (GET when empty). HEAD uses the GET handler; OPTIONS answers with the allowed methods.
func init() {
	wpgo.RegisterRestRoute("shortcode-demo/v1", "/facts", []string{"GET", "POST"}, facts)
	wpgo.RegisterRestRoute("shortcode-demo/v1", `/facts/(?P<id>\d+)`, nil, fact)
}

func facts(_ wpgo.Context, req *wpgo.RestRequest) *wpgo.RestResponse {
	if req.Method == "GET" {
		return wpgo.JSON(200, map[string]any{"facts": allFacts()})
	}
	if !req.User.Can("edit_posts") { // nil user → false
		return wpgo.RestError(403, "rest_forbidden", "Sorry, you are not allowed to add facts.")
	}
	var in struct{ Fact string `json:"fact"` }
	if err := req.BindJSON(&in); err != nil || in.Fact == "" {
		return wpgo.RestError(400, "rest_invalid_param", "fact is required")
	}
	// …store it…
	return wpgo.JSON(201, map[string]any{"fact": in.Fact})
}
Request fieldContent
Methodafter X-HTTP-Method-Override / _method handling
Routethe matched path, e.g. /shortcode-demo/v1/facts/7
Paramsnamed groups; req.Param("id")
QueryURL query parameters, first value each (req.QueryAll for all)
HeadersAccept, Content-Type, Accept-Language, User-Agent, Referer, Origin, X-Requested-With
BodyJSON body (req.BindJSON(&v)) or a JSON string; at most 1 MiB
User{ID, Login, DisplayName, Roles, Caps} or nil

Response and authentication

wpgo.JSON(status, v) encodes a body; wpgo.RestError(status, code, message) builds {"code","message","data":{"status"}}. Allowed response headers: Cache-Control, Expires, ETag, Last-Modified, Vary, Link, Retry-After, Content-Language, Content-Disposition, X-WP-Total, X-WP-TotalPages, Location (same-site path) and the plugin's own X-<Slug>-*; others are dropped and logged. Bodies max 1 MiB; a panic, 10 s timeout or malformed result yields 500 rest_plugin_error.

There is no permission_callback: check req.User yourself (req.User.Can("edit_posts") is safe on nil). A cookie without a nonce is anonymous.

curl http://localhost:8088/wp-json/shortcode-demo/v1/facts
curl -u admin:'xxxx xxxx xxxx xxxx xxxx xxxx' -H 'Content-Type: application/json' \
     -d '{"fact":"Gophers read JSON."}' http://localhost:8088/wp-json/shortcode-demo/v1/facts

Webhook receivers and non-JSON responses

  • RegisterRestRouteWithHeaders requests extra headers (e.g. Stripe-Signature, X-Hub-Signature-256); max 16 per route; Cookie, Authorization, Proxy-Authorization refused.
  • req.RawBodyBytes() returns the unmodified body for HMAC checks.
  • wpgo.Text(status, contentType, text) answers with text/plain, text/csv, text/html, text/xml, application/xml, application/rss+xml or application/atom+xml; sent with nosniff, HTML sandboxed by Content-Security-Policy: sandbox.

Settings pages

A plugin cannot render admin HTML for a settings page; it declares one and the core renders it under Settings › <Menu title>, validates input, saves each field as an option and shows "Settings saved." Permissions: admin:settings to register, options:read to read values.

wpgo.RegisterSettingsPage(wpgo.SettingsPage{
	PageTitle:   "Gopher Facts",
	MenuTitle:   "Gopher Facts",
	Description: "Options of the Gopher Facts plugin.",
	Fields: []wpgo.SettingsField{
		{ID: "heading", Label: "Heading", Type: "text", Default: "Did you know?", Placeholder: "Shown above the list"},
		{ID: "count", Label: "Facts per page", Type: "number", Default: 3, Min: ptr(1), Max: ptr(10)},
		{ID: "greet", Label: "Greet logged-in readers", Type: "checkbox", Default: true,
			Description: "Adds a personal greeting."},
		{ID: "style", Label: "List style", Type: "select", Default: "cards",
			Options: []wpgo.SettingsOption{{Value: "cards", Label: "Cards"}, {Value: "plain", Label: "Plain list"}}},
		{ID: "footer", Label: "Footer note", Type: "textarea", Rows: 3},
	},
})
TypeSaved asExtra
textstringPlaceholder
textareastring (CRLF normalised, ≤64 KiB)Rows, Placeholder
numberJSON numberMin, Max (clamped), Placeholder
checkboxtrue / falseDescription is the label
select, radiostring; values not in Options ignoredOptions (1–100)
emailvalid address or ""Placeholder
urlhttp(s) URL or ""Placeholder
passwordnever printed back; empty input keeps the stored valuePlaceholder
color#rgb, #rrggbb, #rrggbbaa or ""—
dateYYYY-MM-DD or ""—

Rules: ID is ^[a-z0-9_]{1,64}$ and unique; 1–50 fields per page; labels and placeholders ≤200 characters, descriptions ≤2000. Everything is escaped. Each field is stored as option plugin_<slug>_<id> (dashes → underscores), readable only by the owning plugin.

heading := wpgo.SettingString("heading", "Did you know?")
count   := int(wpgo.SettingFloat("count", 3))
greet   := wpgo.SettingBool("greet", true)
name    := wpgo.SettingName("heading") // "plugin_shortcode_demo_heading"

Saving the page purges the page cache. Custom HTML, buttons that call the plugin, uploads or pages outside Settings are not possible here; use an admin page (admin:pages) instead.

Scheduled events

With cron a plugin schedules recurring or one-off events. The core's job runner stores them in the jobs table and fires the plugin's hook as an action; no visitor is needed and an event runs once even with several server instances. The hook name must start with cron_, be listed in hooks and have an action registered. Schedule from OnInit.

const refresh = "cron_gopher_facts_refresh"

func init() {
	wpgo.AddAction(refresh, wpgo.DefaultPriority, func(_ wpgo.Context, args []any) {
		payload, _ := args[0].(map[string]any)      // {"plugin": "...", "args": {...}}
		// fetch, compute, store…
		_ = wpgo.Transients.Set("facts", fetchFacts(), 2*time.Hour)
	})
	wpgo.OnInit(func() {
		_ = wpgo.ScheduleEvent(refresh, time.Hour, map[string]any{"source": "api"})
	})
}
FunctionEffect
ScheduleEvent(hook, interval, args)Every interval (≥1 minute, ≤1 year), first run one interval from now. Same interval and args keeps the existing schedule; different ones replace it
ScheduleSingleEvent(hook, at, args)Once at at (zero = as soon as possible; at most a year ahead). Keyed by hook and args
UnscheduleEvent(hook)Removes all the plugin's runs of the hook
UnscheduleEventArgs(hook, args)Removes only runs with exactly these args
  • args (≤64 KiB JSON) arrives under "args". Runs have no request and no user; posts created from cron have no author.
  • A failed run is logged and counts as a plugin failure; the event stays scheduled. Another plugin listening on the same name never receives it.
  • A deactivated plugin's events are skipped; deleting the plugin removes its events, options and transients.
  • A cron_* callback has 30 seconds and is exempt from the slow-call rule.
SELECT name, run_at, recurrence, payload FROM jobs WHERE name LIKE 'cron_%'

Shortcodes

Shortcodes use WordPress syntax and are expanded in the_content after blocks and autop, before the the_content filters (like do_shortcode at priority 11).

[gopher-facts]                       self-closing
[gopher-facts count="3" style=plain] attributes: quoted or bare, names are lower-cased
[box title="Note"]Some *text*[/box]  enclosing: the content is passed to the callback
[[gopher-facts]]                     escaped: rendered as the literal text [gopher-facts]

List the tag in plugin.json under shortcodes (needs content:filter):

wpgo.AddShortcode("box", func(ctx wpgo.Context, attrs map[string]string, content string) string {
	title := attrs["title"]
	if title == "" {
		title = "Note"
	}
	return `<div class="box"><strong>` + html.EscapeString(title) + `</strong>` + content + `</div>`
})
  • attrs holds named attributes plus positional ones under "0", "1", …
  • content is the raw inner text, already autop'd; nested shortcodes are not expanded for you.
  • Output goes through KSES (wp_kses_post) unless the plugin holds content:html. ctx.Hook is the tag.
  • A panic or timeout renders an empty string and is logged.
  • They work in post and page content (Shortcode block and classic content), not in excerpts, widget text or the REST API's content.rendered.

Assets (CSS and JavaScript)

Files in the package's assets/ directory are served at /wp-content/plugins/<slug>/assets/<path>?ver=<version> while the plugin is active. Permission: content:filter; a script also needs content:html on the front end and admin:scripts in the admin (wpgo.Both needs both). An admin stylesheet needs admin:settings (printed on the plugin's settings page only) or admin:scripts (every admin screen).

RuleValue
Extensions.css .js .svg .png .jpg .jpeg .webp .woff2
Size2 MiB per file, 16 MiB and 256 files per package
Pathsletters, digits, ., -, _; no segment starts with a dot; sub-directories allowed
Integritywpgo-pkg pack writes each file's SHA-256 into plugin.json assets; the installer rejects unlisted, missing or modified assets
ServingCache-Control: public, max-age=604800, nosniff; SVGs get a sandboxing CSP
func init() {
	wpgo.EnqueueStyle(wpgo.Style{Handle: "gopher-facts", Src: "style.css", Where: wpgo.Front})
	wpgo.EnqueueScript(wpgo.Script{Handle: "gopher-admin", Src: "js/admin.js", Where: wpgo.Admin, InFooter: true})
	wpgo.EnqueueScript(wpgo.Script{Handle: "gopher-widgets", Src: "js/widgets.js", Deps: []string{"gopher-core"}, Where: wpgo.Both})
}
FieldMeaning
Handle^[a-z0-9_-]{1,64}$; tag id becomes <slug>-<handle>-css / -js
Srcpath inside assets/; .css for styles, .js for scripts
Wherewpgo.Front (default), wpgo.Admin, wpgo.Both
Depsthis plugin's handles of the same kind (≤10)
Mediastylesheet media, default all
InFooterprint before </body>
Strategyscripts: "", "defer", "async"; empty means defer for front-end head scripts
Modulescripts: type="module"
Datascripts: map (≤16 KiB JSON) printed as window.<handle>Data (my-plugin → myPluginData)

Call the enqueue functions from init or OnInit; they are static registrations. Reference fonts and images from CSS with relative URLs, or from HTML with /wp-content/plugins/<slug>/assets/…. The site's CSP allows scripts and styles from its own origin only, so prefer a packaged script over inline <script>.

Admin pages, meta boxes, blocks and widgets

Beyond settings pages a plugin can add five kinds of UI, each with its own permission. The plugin returns HTML; the core places and sanitises it: admin output loses scripts, event handlers and iframes (wp.KsesAdmin) unless admin:scripts; front-end output (blocks, widgets) goes through KSES unless content:html.

WhatSDKPermissionLimit
Admin menu pageRegisterAdminPage(AdminPage{…})admin:pages20
Dashboard boxRegisterDashboardWidget(id, title, cap, fn)admin:dashboard10
Post edit screen boxRegisterMetaBox(MetaBox{…})admin:metaboxes20
Pursae Editor blockRegisterBlock(Block{…})blocks:register50
Pursae Web Builder widgetRegisterBuilderWidget(BuilderWidget{…})builder:widgets50

A render callback may return 1 MiB of HTML and receives at most 256 KiB of input. Admin pages get 10 s, the others 2 s.

Admin pages

wpgo.RegisterAdminPage(wpgo.AdminPage{
	Slug: "", PageTitle: "Gopher Board", MenuTitle: "Gopher Board",
	Parent: "tools", // "" = top-level, "self" = under the plugin's main page, or a core menu
	Render: func(ctx wpgo.Context, req wpgo.AdminRequest) wpgo.AdminResponse {
		if req.Method == "POST" { /* req.Form["message"] … */ }
		return wpgo.AdminResponse{HTML: `<input name="message"> <button class="button button-primary">Save</button>`,
			Notices: []wpgo.PageNotice{{Type: "success", Message: "Saved."}}}
	},
})
  • URL: /wp-admin/admin?page=<plugin slug>, or …?page=<plugin slug>.<Slug>.
  • Parent: "" (top-level with a dashicons-* Icon), self, or dashboard, posts, media, pages, comments, appearance, plugins, users, tools, settings.
  • Capability defaults to manage_options. The core wraps your HTML in a <form method="post"> with a nonce; POSTs reach the plugin only after the nonce check. Up to 10 plain-text notices.

Dashboard widgets, meta boxes, blocks

  • Dashboard widget box id is plugin_<slug>_<id>; capability "" = read.
  • Meta boxes show in the classic editor and Pursae Editor (default post and page). Declared Fields are stored as post meta plugin_<slug>_<field id>; Render output never gets form controls; OnSave receives post id and values.
  • Blocks are named <plugin slug>/<name>, dynamic (only attributes are saved), with inspector controls from Attributes and a server preview via /wp/v2/block-renderer/<name>. An inactive plugin's block renders nothing.
wpgo.RegisterMetaBox(wpgo.MetaBox{
	ID: "notes", Title: "Gopher Notes", Context: "side", PostTypes: []string{"post"},
	Fields: []wpgo.SettingsField{{ID: "subtitle", Label: "Subtitle", Type: "text"}},
	Render: func(ctx wpgo.Context, req wpgo.AdminRequest) string { return "<p>Shown above the fields.</p>" },
	OnSave: func(ctx wpgo.Context, postID int64, values map[string]any) { /* after the fields were stored */ },
})

Web Builder widgets

The widget type is <plugin slug>/<ID>. The core exposes widgets through GET /wp-json/web-builder/v2/plugin-widgets and renders one with POST /wp-json/web-builder/v2/plugin-widgets/render (both need edit_posts).

Not finished yet. The builder's widget panel does not list plugin widgets yet; the editor side is pending, so today the widget is reachable only through these endpoints.

Full example: examples/plugins/ui-demo.

Limits and the sandbox

Plugins run inside wazero with no cgo and no process boundary; isolation comes from the module having only linear memory and the imports the host gives it.

AreaAccess
Filesystemnone: no preopens, WASI file calls fail
Networknone except HTTPGet / HTTPRequest with http:outbound (8 s, 1 MiB, loopback and private addresses blocked)
Environment, argumentsnone
Clocks and randomnessavailable (time.Now, crypto/rand)
stdout / stderrcaptured into the plugin log
Other pluginsinvisible; options, storage and transients scoped by slug
LimitDefault
Linear memory1024 pages = 64 MiB per plugin
Concurrencyone call at a time per plugin
Compiled codekept in memory, compiled again at start-up
Hook, shortcode callback2 s
REST route handler10 s
cron_* callback30 s
Instantiation + wpgo_init10 s
Message across the boundary8 MiB
Post content1 MiB; title 1000, excerpt 10 000, slug 200 characters
REST body, HTTP response body, storage/transient value1 MiB (keys 256 / 172 characters)
Admin notice2000 characters
Settings page50 fields
Cron interval60 s to 1 year
Assets2 MiB per file, 16 MiB and 256 files per package

Failure handling

A trap, timeout, os.Exit, panic or malformed response is logged; the filter keeps its value, a shortcode renders empty, a REST route answers 500. After five consecutive failures the plugin is disabled (hooks, shortcodes, routes, settings page and assets disappear), the reason is shown on the Plugins screen and survives restarts. Activate it again to reset.

For your code. Keep callbacks short and move slow work to a scheduled event; don't rely on package-level state (an instance can be replaced any time; use storage); goroutines run only while the host is inside your export; Go's runtime uses part of the 64 MiB cap, so stream and page.

Packaging and signing

File at zip rootRequiredLimit
plugin.jsonyes64 KiB
plugin.wasmyes64 MiB; WASI reactor built with -buildmode=c-shared
readme.mdno1 MiB; shown on the marketplace page
icon.svgno256 KiB; marketplace icon
assets/…no2 MiB per file, 16 MiB total
signatureif the site requires signatures1 KiB

No other files are allowed.

wpgo-pkg

wpgo plugin keygen|pack|verify|new|build   # the same tool is built into the wpgo binary
go build -o wpgo-pkg ./internal/plugins/cmd/wpgo-pkg

wpgo-pkg keygen -out mykey [-comment "My plugins key"]
#   writes mykey.pub (publish this) and mykey.key (mode 0600; keep it private); existing files are kept
wpgo-pkg pack -dir ./my-plugin -wasm plugin.wasm -key mykey.key -out my-plugin-1.0.0.zip
#   packs plugin.json, readme.md, icon.svg and assets/** from -dir; omit -key for an unsigned package
wpgo-pkg verify -pub mykey.pub my-plugin-1.0.0.zip
#   verifies the signature and prints the manifest summary

Key files are base64 with optional # comment lines. tools/build-plugins.sh [plugin-dir …] builds the example plugins into examples/plugins/dist/ with a development key; set WPGO_SIGNING_KEY=/path/to/key to sign with your own.

The signature

digest    = SHA-256("wpgo-plugin-v1\n" || u64be(len(plugin.json)) || plugin.json || u64be(len(plugin.wasm)) || plugin.wasm)
signature = base64(Ed25519.Sign(privateKey, digest)) + "\n"

Assets are covered through their SHA-256 in plugin.json; readme.md and icon.svg are not signed (display-only).

What a site accepts

Site configurationTrusted keyUnknown keyUnsigned
default (keys configured, plugin_allow_unsigned off)installsrejectedrejected
plugin_allow_unsigned on, some trusted keysinstallsrejectedinstalls
plugin_allow_unsigned on, no trusted key—installs as unverifiedinstalls
no trusted keys, plugin_allow_unsigned off—rejectedrejected
Development only. plugin_allow_unsigned has no screen; never turn it on in production.

Trusted keys come from WPGO_PLUGIN_KEYS (comma-separated), the plugin_trusted_keys option (Plugins > Trusted Keys, effective immediately), the Manager's key list (replaced on every index refresh), and in development the dev-key.pub next to the example packages when WPGO_TRUST_DEV_KEY=1.

Updates and versioning

The site records which key signed each plugin. A new version must come from the same key (any two Pursae Manager keys count as the same publisher) and must not be older: from the Manager such a package is refused; an upload offers Replace current with uploaded. Before a Manager update the previous package is kept as <slug>.zip.prev and restored if the new one fails to load. Bump version for every release; the Hub refuses an existing or lower version. Packages over 64 MiB are refused.

Testing

The SDK compiles on every platform. Outside the host, host functions return wpgo.ErrNotInHost, while hook registration and wpgo.Dispatch work, enough for go test without WebAssembly.

func TestFooterOnSinglePosts(t *testing.T) {
	wpgo.Init() // flushes registrations made in init(); safe to call more than once

	req := map[string]any{
		"plugin": "hello-reader", "hook": "the_content", "type": "filter",
		"callback": callbackFor(t, "the_content"),
		"value":    "<p>Hi</p>",
		"args":     []any{map[string]any{"id": 1, "type": "post", "is_single": true}},
	}
	raw, _ := json.Marshal(req)
	var resp struct {
		Value string `json:"value"`
		Error string `json:"error"`
	}
	if err := json.Unmarshal(wpgo.Dispatch(raw), &resp); err != nil || resp.Error != "" {
		t.Fatalf("dispatch: %v %s", err, resp.Error)
	}
	if !strings.HasSuffix(resp.Value, "Thanks for reading, reader!</p>") {
		t.Fatalf("got %q", resp.Value)
	}
}

Callback names are generated (the_content#1, shortcode:box#2, rest:ns/route#3). Shortcode requests use "type": "shortcode" with "args": [attrs, content]; REST requests "type": "rest" with "args": [request].

Faking the host: wpgotest

wpgo/sdk/go/wpgo/wpgotest fakes the host so code calling GetOption, Storage, Transients, GetPost, QueryPosts, CurrentUser, HTTPGet/HTTPRequest, SendMail or AdminNotice runs in plain go test.

func TestRates(t *testing.T) {
	h := wpgotest.New(t)
	h.SetOption("plugin_rates_currency", "EUR")
	h.StubHTTP("https://api.example.com/rates", 200, `{"eur":1.1}`)
	h.AddPost(wpgo.Post{Title: "Hello", Content: "body"})
	h.SetUser(&wpgo.User{ID: 1, Caps: []string{"edit_posts"}})

	// ... call your code, then inspect what it did:
	_ = h.Storage()  // plugin storage
	_ = h.Mails()    // queued mail
	_ = h.Notices()  // admin notices
	_ = h.Requests() // outbound HTTP requests
}

Unstubbed URLs fail like a refused request; permissions are not enforced by the fake. For UI: h.RenderAdminPage, h.RenderBlock, h.Registered("register_meta_box"). Inside the repository, internal/plugins tests run a real plugin.wasm with plugins.NewRuntime and plugins.MemoryHost.

On a site

  • Run with WPGO_WEB_DIR=web and plugin_allow_unsigned; upload, activate, read the plugin log on the Plugins screen (also in the server log with plugin=<slug>).
  • WPGO_MARKET_DIR=/path/to/zips lists your packages on Plugins › Add Plugin for one-click install.

Publishing to the Hub

The Hub is the marketplace sites read from Plugins › Add Plugin. A Hub operator publishes through the admin panel; as a developer you deliver a package and listing details.

  1. Build and pack, signed with your own key: the Hub keeps your signature as provenance and re-signs with its key, so sites install without extra configuration.
  2. Fill in plugin.json completely. The Hub reads slug, name, version, description (the card text: one or two sentences), author, author_url, homepage, requires_core, tested_core, permissions, hooks (author_uri, plugin_uri, requires are the same data).
  3. Add readme.md (the listing page) and a square icon.svg (otherwise a placeholder is generated).
  4. Test on a clean site with only the permissions you ask for.

Submit: send the zip to the Hub operator; for the public Hub, through the repository's plugin submission process. Updates are published the same way with a higher version. Details in the Hub section below.

Example plugins

In examples/plugins/ of the repository; tools/build-plugins.sh builds them into examples/plugins/dist/.

PluginShowsPermissions
hello-gopherthe_content footer on single posts when hello_gopher_footer is truthy; a gopher one-liner in admin_noticesoptions:read, content:filter, admin:notices
word-counterwpgo_post_stats filter adding word_countposts:read
shortcode-demo (Gopher Facts)[gopher-facts], [recent-gophers], REST under /wp-json/shortcode-demo/v1/, Settings › Gopher Facts, assets/style.css, transients, cron_shortcode_demo_tickoptions:read, content:filter, rest:routes, posts:read, users:read, cron, admin:settings, storage
feed-digestHourly cron_feed_digest_refresh fetches a JSON feed with HTTPGet into a transient; [feed-digest limit="5"]http:outbound, storage, cron, content:filter, options:read, options:write
publish-notifiersave_post + HTTPRequest: POSTs {"id", "title", "link"} to the publish_notifier_webhook URL on publishposts:read, http:outbound, options:read
ui-demo (Gopher Board)Admin page under Tools, Dashboard widget, Gopher Notes meta box, Gopher Badge block and Web Builder widgetstorage, admin:pages, admin:dashboard, admin:metaboxes, blocks:register, builder:widgets
Hub / Marketplace

Hub and Marketplace

The Hub (wpgo-hub) is the central service behind the plugin and theme marketplace, core updates, licenses and signing keys. Every production Pursae site talks to https://hub.pursae.com.

What the Hub is

The Hub has two faces:

  • a public JSON API under /api/v1/, read by sites and the public site: no authentication, cacheable, rate limited;
  • an admin panel under /admin/ where the operator manages the plugin and theme marketplace, core releases and signing keys.

There is no environment variable or option to point a production site elsewhere; only development builds (-tags devhub) read WPGO_DEV_HUB_URL. Sites talk to a Hub only over https (plain http only for localhost, loopback, *.localhost and *.test); redirects never downgrade to http.

FeatureEndpointWhere it shows
Plugin marketplaceGET /api/v1/pluginsPlugins › Add Plugin
Theme marketplaceGET /api/v1/themesAppearance › Themes › Add Theme
Package downloads…/{slug}/download[/{version}]one-click install; site checks SHA-256 and, for plugins, the Hub signature
Core releasesGET /api/v1/index → coreDashboard › Updates (Update to version X)
Previous core releaseGET /api/v1/core/{version}Dashboard › Updates › Reinstall version Y
Plugin updatesGET /api/v1/pluginsPlugins and Dashboard › Updates
License checkGET /api/v1/licenseSettings › License
Signing keysGET /api/v1/index → keysadded to trusted plugin keys automatically (replaced on every refresh)
Product logoGET /api/v1/index → brandreplaces the shipped logo on every screen

Catalog responses carry Cache-Control: public, max-age=300; sites cache the catalog for 12 hours. One ping per host per 10 minutes is accepted (429 otherwise).

Root of trust

A key listed in the same answer as the release it verifies proves nothing, so core self-updates need a release root key compiled into the binary: rootKeysBuiltin in internal/server/hub_trust.go (the pinned Pursae release root), plus optional extra roots via -ldflags "-X wpgo/internal/server.rootKeysLinked=…" (Docker: --build-arg ROOT_KEYS=…), which only add roots.

"keys": [{"id": "hub-2026", "public": "<base64 Ed25519>", "endorsement": "<base64 Ed25519 signature>"}]

endorsement = base64(Ed25519.Sign(rootKey, "pursae-hub-key-v1\n" + id + "\n" + public)). Plugin packages are verified only against endorsed Hub keys too (with wpgo_hub_trust_keys on). A production binary cannot relax this; a development build with WPGO_TRUST_HUB_KEYS=1 trusts every listed key. A compromised Manager key is rotated by generating a new one, having the root endorse it and no longer listing the old one.

Licenses and what a site sends

Settings › License takes the license key (option pursae_license_key, never readable by plugins), checked with GET /api/v1/license and cached 12 hours. Every Hub request carries X-Pursae-Site and, with a key, X-Pursae-License; the Hub then also lists Pro and Private packages and beta versions (badges Pro, Private, Beta).

Statistics are on by default and can be turned off under Settings › License › "Send usage statistics" (pursae_send_stats). The daily ping is POST /api/v1/sites/ping (also run by wpgo_hub_check) with url, version, locale, os, arch, license, theme, plugins, themes and contacts. Events (POST /api/v1/sites/events) include plugin_install, plugin_update, plugin_activate, plugin_deactivate, plugin_delete, theme_install, theme_update, theme_activate, theme_delete, theme_preview, demo_import and core_update.

Privacy. The site never sends user data, e-mail addresses (other than opted-in update contacts), post content, titles or visitor information. The public site count is GET /api/v1/sites/count; the site list is not public.

The Marketplace

Plugins › Add Plugin

Lists the Hub catalog (GET /api/v1/plugins, sorted by last update, searchable by name, slug, description and author) next to the built-in plugins and any packages in WPGO_MARKET_DIR. A card shows name, author, version, description, icon, the permissions the plugin asks for, download count and minimum core version; the detail view shows the package's readme.md. Cards show Requires Pursae X and Tested up to Y (requires_core, tested_core); a too-new requirement shows a disabled Incompatible button. tags are filter links (?tag=<tag>).

  1. Install Now downloads from download_url, verifies the SHA-256 against the listing's sha256 and the signature against a trusted key (Hub keys are trusted automatically), stores the plugin inactive and records the signing key.
  2. Activate opens the permission screen where you grant what the plugin may do.

The Upload Plugin tab goes through the same signature check.

Themes

Appearance › Themes › Add Theme › Library shows the Hub's theme catalog (GET /api/v1/themes). Theme packages contain no code and are not signed; Install checks size and SHA-256, validates theme.json, templates and demo, and unpacks into <data>/themes/<slug>/. Live Preview builds a sandbox with the demo content first. WPGO_THEME_LIBRARY_DIR serves the library from a local directory.

Updates

Hub-installed plugins (source = hub) show an update row on the Plugins screen and under Dashboard › Updates (Update Plugins) when the catalog lists a higher version. Updates verify SHA-256 and signature like an install; an active plugin keeps only previously granted permissions the new version still asks for. The optional changelog is shown in the update row.

Automatic updates: Enable auto-updates on the Plugins screen (option pursae_plugin_auto_updates); the daily wpgo_hub_check then updates them, but an active plugin only when the new version asks for no new permission.

Offline: without a reachable Hub only built-in plugins, bundled themes and local packages show, and uploads still work.

Publishing to the Marketplace

Publishing goes through the Hub's admin panel (Admin › Plugins, Admin › Themes): the operator uploads a zip, reviews the listing and publishes it. Developers deliver the package and listing details; for the public Hub, through the project's submission process.

Sending your plugin. Send the signed zip to the Hub operator: for the public Hub through the repository's plugin submission process, for a private Hub however your organisation agreed. The docs do not describe the public submission process in more detail.

What the Hub does on publish

  1. Parses and validates the zip and manifest; rejects a version that already exists for the slug or is lower than the latest published one.
  2. Computes digest = SHA-256("wpgo-plugin-v1\n" || u64be(len(json)) || json || u64be(len(wasm)) || wasm).
  3. Keeps the developer's signature (if any) as provenance and re-packs the zip with the Hub's own signature over the same digest.
  4. Stores the repacked zip, its SHA-256 and size.

Listing fields come from plugin.json (slug, name, version, description, author, author_url/author_uri, homepage/plugin_uri, requires_core/requires, tested_core, permissions, hooks); the operator can override description and homepage. readme.md becomes the detail page and icon.svg the icon.

After publishing

The item appears in GET /api/v1/plugins immediately (with download_url, sha256, signed_by and permissions) and on sites within their 12-hour catalog cache. Each download increments downloads; older versions stay under versions in GET /api/v1/plugins/{slug}; unpublish hides an item without deleting files.

Themes (zip with theme.json, templates/, assets/) are validated but not signed; the core theme library is published with make publish-themes PURSAE_MANAGER_DIR=/path/to/pursae-manager [PREINSTALL=slug,slug|all].

The Hub's signing key lives in WPGOHUB_DATA_DIR/keys/<id>.key; old public keys stay listed in GET /api/v1/index so installed packages keep verifying.

Running your own Hub

Production binaries always talk to https://hub.pursae.com. Run your own Manager to develop and test packages and releases against development builds (-tags devhub), or as the Hub of a fork that builds its own binaries (with its own config.DefaultHubURL and release root key).

wpgo-hub is a single binary with PostgreSQL and a data directory; in the Pursae compose stack it is on host port 8090.

VariableDefaultMeaning
WPGOHUB_ADDR:8080listen address
WPGOHUB_PUBLIC_URLhttp://localhost:8090used in download_url and links; set to the public https:// address
DATABASE_URLpostgres://wpgohub:wpgohub@localhost:5432/wpgohub?sslmode=disablePostgreSQL
WPGOHUB_DATA_DIR./datapackages and keys
WPGOHUB_SECRETrandomsession signing; set it for restarts and replicas
WPGOHUB_TEST_DB—integration tests run only when set

Put it behind TLS; GET /healthz returns ok.

First run

Open /setup to create the operator account, then /login (argon2id, login throttling).

ScreenDoes
/adminoverview: site count, plugins and themes, last pings, latest core release
/admin/siteshosts, versions, first/last seen, local flag; search; delete
/admin/plugins, /admin/themesupload a zip, publish/unpublish, versions, edit the listing, delete
/admin/releasescore releases: version, download and notes URLs, notes; publish
/admin/keyssigning keys; generate a new one
/admin/settingshub name, public URL, rate limits
Before the first plugin. Generate a signing key under /admin/keys: packages are re-signed with it, and sites add it to their trusted keys from GET /api/v1/index.

Connect sites

Only a development build connects to another Hub: build with -tags devhub (make dev, or the development compose file with GO_TAGS=devhub), set WPGO_DEV_HUB_URL=http://localhost:8090 (compose default http://pursae-manager.test:8090) and WPGO_TRUST_HUB_KEYS=1. WPGO_DEV_HUB_URL=off disconnects from every Hub. Production binaries ignore both.

API

The same public API as the public Hub: GET /api/v1/index, /plugins, /plugins/{slug}, /plugins/{slug}/download[/{version}], /plugins/{slug}/icon, the same for /themes (with /screenshot), POST /api/v1/sites/ping, GET /api/v1/sites/count.

Sources: hub/index.md, marketplace.md, publishing.md, running-your-own-hub.md.

REST API

REST API

Pursae serves the WordPress REST API at /wp-json/. The wp/v2 namespace mirrors WordPress closely enough that the block editor, mobile apps and headless clients work unchanged.

Overview and base URL

The API lives at /wp-json/ (and ?rest_route=/…).

curl -s https://blog.example.com/wp-json/ | jq .namespaces
curl -s 'https://blog.example.com/wp-json/wp/v2/posts?per_page=2&_fields=id,title,link'

Conventions

  • JSON in and out; Content-Type: application/json bodies, or form bodies and query parameters.
  • Collections paginate with page, per_page and return X-WP-Total, X-WP-TotalPages and Link: rel="next"/"prev".
  • _fields trims responses, _embed inlines linked resources, _envelope wraps body with status and headers.
  • Method overrides: X-HTTP-Method-Override on a POST, or ?_method=DELETE. PUT/PATCH fall back to POST, HEAD to GET.
  • Errors: {"code": "rest_no_route", "message": "…", "data": {"status": 404}}.
  • OPTIONS answers with the route's methods and Allow.

Namespaces

NamespaceContents
wp/v2posts, pages, blocks, media, categories, tags, users, comments, settings, types, taxonomies, statuses, themes, search, patterns, sidebars, widgets, block renderer, global styles
wp-block-editor/v1URL details for the editor's link preview
oembed/1.0the oEmbed proxy
batch/v1batched requests
web-builder/v2Pursae Web Builder (only while the builder is on)
pursae/v1site management for scripts and AI agents
forum/v1Pursae Forum (only while it is on)
<plugin-slug>/v1routes added by plugins
Differences from WordPress No wp-site-health/v1, wp/v2/plugins or wp/v2/font-families yet; wp/v2/templates returns an empty list. Block types, pattern directory and block directory searches return empty lists.

Authentication

MethodForHow
Anonymouspublic readsno credentials; published posts, pages, media, terms, public profiles, comments
Cookie + noncebrowser clientssession cookie plus X-WP-Nonce (or ?_wpnonce=) for action wp_rest; a cookie without a nonce is anonymous, a wrong nonce is 403 rest_cookie_invalid_nonce
Application Passwordsscripts, apps, CIHTTP Basic with the login and a 24-character password (shown once); wrong or missing is 401 incorrect_password
OAuth 2.1MCP clientsAuthorization: Bearer pat_… tokens from the OAuth flow; narrowed by scopes like Application Passwords
curl -u 'editor:abcd efgh ijkl mnop qrst uvwx' \
     -H 'Content-Type: application/json' \
     -d '{"title":"From the API","status":"draft"}' \
     https://blog.example.com/wp-json/wp/v2/posts
  • Admin pages expose the nonce in wpApiSettings.nonce; every authenticated response returns a fresh one in X-WP-Nonce.
  • Application Passwords are created under Users › Profile › Application Passwords, via /wp/v2/users/me/application-passwords, or through /wp-admin/authorize-application.
  • After five Basic-auth failures from one address within 15 minutes, further requests get 429 too_many_retries.
TLS only Basic authentication sends the password with every request; use Application Passwords only over TLS.

Application Password scopes

A password without scopes has all its user's capabilities. A scoped password is narrowed twice: capabilities are cut to what the scopes need, and a route of another scope returns 403 rest_scope_forbidden with data.required_scope. Scopes never add a capability.

ScopeRoutes
content/wp/v2/posts, pages, blocks, categories, tags, comments, types, taxonomies, search, block-renderer, /web-builder/v2, /pll/v1, /batch/v1
media/wp/v2/media
themes/wp/v2/templates, template-parts, global-styles, themes, menus, menu-items, menu-locations, navigation, sidebars, widgets, /pursae/v1/themes
plugins/pursae/v1/plugins, /pursae/v1/updates
cache/pursae/v1/cache
seo/seogo/v1, /pursae/v1/seo
settings/wp/v2/settings, /pursae/v1/options, /pursae/v1/headless, /pursae/v1/health, /pursae/v1/backups, /pursae/v1/mcp/activity
commerce/wc/v3
users/wp/v2/users
curl -u admin:… -H 'Content-Type: application/json' \
     -d '{"name":"Cursor","scopes":["content","media","seo"]}' \
     https://blog.example.com/wp-json/wp/v2/users/me/application-passwords

Every scoped password may also read the REST index, /wp/v2/users/me and use /pursae/v1/mcp. A scoped password cannot create, change or revoke Application Passwords.

OAuth 2.1 endpoints

EndpointPurpose
/.well-known/oauth-protected-resourceprotected-resource metadata (RFC 9728)
/.well-known/oauth-authorization-serverauthorization-server metadata (RFC 8414)
POST /oauth/registerdynamic client registration (RFC 7591), public clients only
/wp-admin/oauth-authorizeconsent screen with scope checkboxes
POST /oauth/tokenauthorization_code (PKCE) and refresh_token grants
POST /oauth/revoketoken revocation (RFC 7009)
  • PKCE with S256 is mandatory; codes live 5 minutes and work once.
  • Access tokens (pat_…) last one hour; refresh tokens (prt_…) last 30 days and rotate on every use. Only SHA-256 hashes are stored.
  • A user keeps at most 20 grants. The Headless delivery API (/wp-json/headlessgo/v1) uses its own API tokens.

Capabilities

Writes are checked like WordPress: edit_posts, edit_pages, upload_files, manage_options / edit_theme_options, manage_categories, and meta capabilities per item. Authenticated without the capability: 403 rest_forbidden; anonymous: 401.

Endpoints: posts, pages, blocks

Routes are under /wp-json/wp/v2. HEAD works wherever GET does, PUT/PATCH wherever POST does.

MethodPathPurpose
GET, POST/posts, /pages, /blockslist and create; filters page, per_page, search, author, categories, tags, tax_relation, after, before, status, orderby, slug, include, exclude, parent, sticky…; context=edit for raw content
GET, POST, DELETE/posts/{id}, /pages/{id}, /blocks/{id}read, update, trash (?force=true deletes); pages read and write template
GET, POST/posts/{id}/autosaves (and pages, blocks)the editor's autosave
GET/posts/{parent}/autosaves/{id}one autosave of the parent
GET/posts/{id}/revisions (and pages…)revisions

With Pursae Multi Language on, posts, pages and terms carry lang and translations ({"en": 12, "fr": 15}); collections take ?lang=fr.

Endpoints: media, terms, users and comments

MethodPathPurpose
GET, POST/medialist; upload with multipart/form-data (file) or a raw body with Content-Disposition; image sizes generated
GET, POST, DELETE/media/{id}title, caption, alt_text, description, post; images also focal_point ({"x": 0.3, "y": 0.2})
POST/media/{id}/post-processpost-processing
GET, POST/categories, /tagslist and create; search, parent, post, slug, hide_empty, orderby
GET, POST, DELETE/categories/{id}, /tags/{id}update/delete needs manage_categories
GET/taxonomies, /taxonomies/{taxonomy}taxonomies
GET/userspublic profiles (who=authors), or all with list_users
GET/users/{id}one user
GET, POST/users/methe current user; context=edit for the full record
POST/users/me/application-passwords, …/application-passwords/{uuid}create (plaintext returned once) or update an Application Password; scopes array or comma list
GET, POST/commentslist and create; anonymous comments honour the Discussion settings
GET, POST, DELETE/comments/{id}one comment

Endpoints: site, themes and widgets

MethodPathPurpose
GET, POST/settingssite settings (manage_options); invalid value is 400 rest_invalid_param, nothing saved
GET/types, /types/{type}post types
GET/statuses, /statuses/{status}post statuses
GET/themes, /themes/{stylesheet}status=active returns the active theme with theme_supports
GET/searchsearch, type, subtype
GET, POST/sidebars, /sidebars/{id}widget areas
GET, POST, DELETE/widgets, /widgets/{id}widgets
GET, POST/widget-types, …/{id}/encode, …/{id}/renderwidget types
GET/menu-locationsmenu locations
GET, POST/block-renderer/{name}server-side rendering of dynamic blocks
GET/block-patterns/patterns, /block-patterns/categoriescore and Twenty Twenty-Five patterns
GET/block-types, /block-directory/search, /pattern-directory/patterns, /wp_pattern_categoryempty lists
GET/templates, /templates/lookup, /template-partsempty (no site editor)
GET, POST/global-styles/{id}, /global-styles/themes/{stylesheet}, …/variationsglobal styles

Endpoints: site management (pursae/v1)

The routes AI agents and scripts use to run a site. Each checks the capability of its admin screen and belongs to an Application Password scope.

MethodPathPurpose
GET, POST/pursae/v1/pluginslist plugins; POST {"package": "<base64 zip>"} installs a signed package, inactive
GET, DELETE/pursae/v1/plugins/{slug}one plugin; remove an installed Wasm plugin
POST/pursae/v1/plugins/{slug}/activate, /deactivateactivate / deactivate (Wasm: permissions)
GET, POST/pursae/v1/themeslist themes; POST {"package": "<base64 zip>", "activate": true} installs a theme package
DELETE/pursae/v1/themes/{slug}delete an inactive theme
POST/pursae/v1/themes/{slug}/activateswitch theme
GET/pursae/v1/themes/{slug}/fileseditable files
GET, POST, DELETE/pursae/v1/themes/{slug}/file?file=…read, save like the Theme File Editor (rolled back on failure), restore
POST/pursae/v1/media/{id}/replacereplace a media file, keeping the ID
GET/pursae/v1/cachePursae Cache status, stats, crawler
POST/pursae/v1/cache/purge{"all": true}, {"url": "/about/"}, {"post": 12} or {"tags": ["home"]}
GET, POST/pursae/v1/cache/settingscache options
GET, POST/pursae/v1/headless/types, …/types/{uid}Pursae Headless content types (DELETE on {uid})
GET, POST/pursae/v1/headless/entries/{uid}, …/{uid}/{doc}list, create, update, delete entries; /publish, /unpublish
GET, POST/pursae/v1/seo/settingsPursae SEO settings (partial merge)
GET, POST/pursae/v1/seo/redirectsredirects (code 301, 302, 307, 410, 451); DELETE on /{id}
GET/pursae/v1/analyticsPursae Analytics overview (?range=today|7d|30d|month|90d|12m)
GET/pursae/v1/healthversion, database, cron queue, Site Health score, updates, last backup
GET, POST/pursae/v1/updatesavailable updates; POST {"type": "plugin"|"theme"|"core", "slug": "…"} installs one
GET, POST/pursae/v1/backupsarchives, or start a backup (202 with job)
GET/pursae/v1/mcp/activityaudit log of writing MCP tool calls
GET/pursae/v1/options, GET/POST /options/{group}built-in plugin settings (contact, cookie, forum, gocdn, headless, maintenance, multilang, pixel, security, seo, smtp); secrets read as ********
POST, GET, DELETE/pursae/v1/mcpthe MCP server (streamable HTTP)

Endpoints: forum and other namespaces

Pursae Forum (forum/v1)

Only while Pursae Forum is on. Read routes are public; lists take page and per_page (default 10, max 100).

MethodPathPurpose
GET/forum/v1/forumsthe whole forum tree, flat
GET/forum/v1/forums/{id}/topicsa forum's topics (sort=latest|popular|unanswered|solved, tag=)
GET/forum/v1/topics/{id}, /topics/{id}/repliesa topic and its replies
POST/forum/v1/topics/{id}/viewview beacon
POST / GET/forum/v1/presence / /forum/v1/onlinemark online / read online counts
GET/forum/v1/stats, /tags, /topics/similar, /levels, /badges, /weekly, /mestats, tags, similar topics, gamification, member state
POST, DELETE/forum/v1/posts/{id}/likelike / unlike
POST/forum/v1/posts/{id}/reportreport (spam abuse off_topic other)
POST, DELETE/forum/v1/topics/{id}/subscription, /topics/{id}/solutionfollow by e-mail; accept / withdraw a solution
POST/forum/v1/previewrender content as it would be posted
GET, POST, DELETE/forum/v1/draftthe member's new-topic draft

Member routes need cookie + X-WP-Nonce or an Application Password (else 401 rest_not_logged_in).

Other namespaces

MethodPathPurpose
GET/ (/wp-json/)the index: site info, namespaces, every route with its methods
POST/batch/v1up to 25 requests in one call (no nested batch)
GET/oembed/1.0/proxyurl=: the provider's oEmbed for the editor
GET/wp-block-editor/v1/url-detailsurl=: title, icon, description of a link
GET, POST, DELETE/pll/v1/languages, /pll/v1/languages/{id or code}, /pll/v1/settingsPursae Multi Language
GET, POST/pll/v1/media/{id}/i18nper-language media texts
POST/pll/v1/translate, /pll/v1/translate/testmachine translation proxy (60 calls per user per minute)
POST/pll/v1/visual/stringssave string translations (≤ 200 items)
various/web-builder/v2/…Pursae Web Builder documents, library, prefs, fonts, forms, templates, themes, site settings

Plugin routes

Plugins add endpoints under their own namespace, /wp-json/<slug>/v1/… (the version may differ). They appear in the index under routes and namespaces while the plugin is active and disappear when it is deactivated or disabled.

curl -s https://blog.example.com/wp-json/ | jq '.namespaces'
# ["batch/v1", "oembed/1.0", "shortcode-demo/v1", "wp-block-editor/v1", "wp/v2"]
curl -s https://blog.example.com/wp-json/shortcode-demo/v1/facts/1
  • Core routes are matched first, so a plugin can never take over a wp/v2 path.
  • Authentication is the core's; the plugin receives the user, if any, and applies its own checks.
  • OPTIONS returns the allowed methods; an unaccepted method is 404 rest_no_route.
  • Request bodies are limited to 1 MiB; JSON is decoded for the plugin, other types are passed as text.
  • A failing plugin answers 500 rest_plugin_error; after repeated failures it is disabled and the route returns 404 until re-activated.
  • Responses are application/json; charset=UTF-8; _fields and _envelope do not apply.
Scopes Plugin routes are covered by no Application Password scope, so a scoped password gets 403 rest_scope_forbidden on them.
Benchmarks

Performance

Pursae and WordPress measured on the same machine, content, theme and container limits on 2026-11-09. Every config and raw result is in the repository, and the tables keep the places where WordPress wins.

Headlines

  • Uncached pages: about 8× WordPress' throughput. Home 397 vs 51 req/s, single post 394 vs 58, REST posts list 1,046 vs 89, admin dashboard 627 vs 72 (stock against stock).
  • With the usual plugin stack: about 13× (single post 232 vs 19 req/s), and a product page at 194 vs 16 req/s. The six WordPress plugins cut its throughput to about a third and take a page from 32 to 139 queries; the six Pursae built-ins cost 30–40 % (13 → 16 queries on the home page).
  • Cached pages: a tie. WP Super Cache served by nginx and Pursae Cache both answer in about 0.1 ms and both run into the load generator (28–35 k req/s).
  • Memory: 95 MiB idle for the whole Pursae stack against 233 MiB (stock) and 330 MiB (with plugins); peak under load 184–202 MiB against 276–489 MiB.
  • Lighthouse (home, mobile): 100 against 96 stock, 99 tuned and 67 with the plugin stack.

Where Pursae does not win

  • Search is not page-cached (/?s= answers Cache-Control: no-cache): 105–119 req/s, while WP Super Cache caches search results and serves 5,724 req/s. Uncached it is still 2.5× stock WordPress (119 vs 48), but it is Pursae's slowest page (93 ms TTFB under load, 26 ms alone).
  • Cached pages are no faster than a well-set-up WordPress page cache.
  • Cold start is the same: about 3 s for the whole stack on both sides, about 1 s for the app alone.
  • The database is bigger: 30 MB and 92 tables against 16 MB and 59 tables, because migrations create the built-in plugins' tables whether or not they are on.
  • Pursae Cache slowed uncached routes a little (REST list 1,046 → 885 req/s, admin post list p50 27 → 70 ms).
  • WordPress "tuned" was slower than stock on uncached requests (REST list 64 vs 89 req/s, admin 43 vs 72); it was kept as configured rather than tuned after seeing the results.

Source: docs/developer/benchmarks.md

Method

Hardware and versions

  • Apple M2 Pro (32 GB), Docker Desktop 29.7.2 on macOS with 12 CPUs / 7.7 GB for Docker.
  • WordPress 7.1.4, PHP 8.3.36, MariaDB 11.4, nginx 1.27, Redis 7, WooCommerce 11.2.2, Yoast SEO 28.8, Polylang 3.9.2, ACF 6.8.11, Elementor 4.3.6, Contact Form 7 6.2.4.1, Redis Object Cache 3.0.0, WP Super Cache 3.1.5.
  • Pursae 0.1.9 (commit cb856438), PostgreSQL 17. k6 1.3.0, 10 virtual users, median of three 20 s runs.

Setups

SetupWordPressPursae
StockWordPress 7.1.4, PHP 8.3 php-fpm (official image, OPcache on, pm = dynamic, 5 children), nginx, MariaDB 11.4, no pluginsPursae Cache off, no built-in plugins (Classic Editor stays on, as on a fresh install)
Cached ("tuned")Stock plus Redis 7 with Redis Object Cache, WP Super Cache served from disk by nginx (gzip_static), static php-fpm pool of 12, innodb_buffer_pool_size = 512MPursae Cache on (defaults)
Real siteStock plus WooCommerce, Yoast SEO, Polylang, ACF, Elementor and Contact Form 7, no page cacheCommerce, SEO, Multi Language, Custom Fields, Web Builder, Contact Form; Pursae Cache off

Content, theme and limits

  • Deterministic content (bench/content/gen.py): 1000 posts with block markup, 10 categories, 60 tags, 50 pages, 200 products in 5 categories, 12 images as featured images. Permalinks /%postname%/ on both.
  • Seeding took 125.2 s on WordPress (WXR import 7.5 s) and 13.5 s on Pursae (WXR import 5.5 s).
  • Theme: Twenty Twenty-Five on both (WordPress' 1.5 and Pursae's Go-template port); Pursae's home page HTML is about half the size, mostly because WordPress inlines more block CSS.
  • Limits: app 2 CPUs / 1 GiB, database 1 CPU / 1 GiB. WordPress also gets nginx (1 CPU, 256 MiB) and, tuned, Redis (0.5 CPU, 256 MiB).
  • Endpoints: home, single post, category archive, product (real-site setups only), search (/?s=garden), REST posts list, and logged in as administrator the dashboard and post list.

Metrics

  • Load: k6 in its own container (4 CPUs), 10 virtual users in a closed loop over random sample URLs; every URL requested once first, a 5 s warm-up, then three 20 s runs. Reported: req/s, TTFB p50, latency p95/p99, median of three.
  • Cold and warm requests: first and second request after a restart on URLs the load test never touches, with TTFB and server-side database statement counts.
  • Memory: sum of docker stats of every container, idle and peak. Cold start: seconds to the first home page answer. Size: images, install on disk, database. Lighthouse: home page, mobile preset, median of three.
Fairness rules Each side runs its recommended production shape (WordPress' official image behind the WordPress.org nginx config; Pursae from its own Dockerfile, production build). WP-Cron is disabled on page views. Versions are pinned. Nothing was tuned after looking at the results.

Full results

Columns: WP stock · WP tuned · WP + 6 plugins · Pursae, no cache · Pursae, cache · Pursae + 6 built-ins. A dash means the setup has no shop.

Throughput (req/s, higher is better)

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home5131,4141939734,128273
Single post5830,2481939434,698232
Category archive5028,2931839535,168312
Product——16——194
Search485,72418119105116
REST posts list8964181,046885349
Admin dashboard (logged in)724319627478510
Admin post list (logged in)523614210178203

TTFB p50 under load (ms)

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home195.80.1505.624.20.134.3
Single post183.60.1500.915.70.127.8
Category archive197.50.1511.724.40.131.0
Product——592.7——60.7
Search202.10.8527.793.396.392.4
REST posts list106.0183.9522.78.49.014.9
Admin dashboard (logged in)107.9207.3513.58.510.211.1
Admin post list (logged in)130.2293.6709.827.369.734.2

Latency p95 under load (ms)

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home214.00.4585.935.40.554.4
Single post198.30.4574.864.80.579.1
Category archive263.60.4589.234.70.544.1
Product——669.6——85.7
Search260.51.8596.8107.2179.3157.7
REST posts list160.6196.0589.117.827.971.0
Admin dashboard (logged in)176.5291.0579.356.064.556.8
Admin post list (logged in)204.1306.3786.284.796.084.1

Latency p99 under load (ms)

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home268.00.7594.850.21.189.2
Single post208.80.7582.281.51.0104.5
Category archive286.40.7619.943.01.157.1
Product——681.3——94.6
Search271.639.5603.7166.9200.2193.0
REST posts list167.0200.0623.927.137.776.8
Admin dashboard (logged in)180.7298.5590.862.875.966.8
Admin post list (logged in)227.4378.5799.191.1171.592.1

First request after a restart (cold): TTFB · DB queries

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home49.1 ms · 32 q2.5 ms · 0 q125.5 ms · 139 q13.6 ms · 13 q2.5 ms · 0 q17.1 ms · 16 q
Single post85.1 ms · 41 q57.0 ms · 12 q120.7 ms · 156 q9.4 ms · 19 q13.6 ms · 19 q14.0 ms · 37 q
Category archive47.8 ms · 34 q59.0 ms · 12 q125.9 ms · 145 q10.7 ms · 15 q13.3 ms · 15 q17.1 ms · 24 q
Product——147.7 ms · 177 q——20.0 ms · 55 q
Search85.4 ms · 37 q71.9 ms · 8 q133.1 ms · 146 q30.1 ms · 14 q34.9 ms · 14 q38.5 ms · 17 q
REST posts list33.6 ms · 42 q36.0 ms · 28 q172.2 ms · 205 q7.0 ms · 7 q6.0 ms · 7 q9.2 ms · 37 q
Admin dashboard (logged in)58.6 ms · 47 q58.9 ms · 8 q242.5 ms · 213 q13.0 ms · 21 q13.0 ms · 21 q15.1 ms · 25 q
Admin post list (logged in)31.4 ms · 48 q34.2 ms · 10 q185.3 ms · 205 q17.4 ms · 20 q13.7 ms · 20 q16.4 ms · 25 q

Second request (warm): TTFB · DB queries

EndpointWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Home49.0 ms · 32 q2.1 ms · 0 q125.8 ms · 135 q9.2 ms · 13 q2.2 ms · 0 q16.6 ms · 16 q
Single post72.1 ms · 41 q2.2 ms · 0 q118.5 ms · 151 q8.7 ms · 19 q2.4 ms · 0 q13.3 ms · 37 q
Category archive46.1 ms · 34 q2.1 ms · 0 q120.0 ms · 140 q12.4 ms · 15 q2.2 ms · 0 q13.7 ms · 24 q
Product——138.5 ms · 172 q——15.3 ms · 55 q
Search64.1 ms · 37 q4.1 ms · 0 q128.5 ms · 146 q26.1 ms · 14 q25.8 ms · 14 q34.7 ms · 17 q
REST posts list40.8 ms · 42 q31.5 ms · 6 q141.6 ms · 155 q5.3 ms · 7 q6.4 ms · 7 q10.7 ms · 37 q
Admin dashboard (logged in)25.4 ms · 47 q29.9 ms · 8 q140.2 ms · 213 q7.0 ms · 20 q7.2 ms · 20 q9.6 ms · 24 q
Admin post list (logged in)27.3 ms · 48 q29.8 ms · 10 q170.1 ms · 205 q11.3 ms · 20 q11.3 ms · 20 q13.5 ms · 25 q

Resources

MetricWP stockWP tunedWP + 6 pluginsPursae, no cachePursae, cachePursae + 6 built-ins
Memory idle (MiB, all containers)233338330957579
Memory peak under load (MiB)276489428202184184
Cold start, whole stack (s)3.162.903.943.053.143.05
Cold start, app only (s)1.080.791.791.030.980.84
Docker images (MB)389406389171171171
Install on disk (MB, no uploads)342.0355.7342.0139.0139.0139.0
Database size (MB)16.416.416.330.130.130.1
Database tables595959929292
Lighthouse performance (home, mobile)969967100100100
Lighthouse LCP (ms)2,7052,1065,7051,8801,8801,881
Home page weight (KB)340192867171171175

Raw data: bench/results/2026-11-09/summary.md

Reproducing the benchmarks

You need Docker with Compose v2 (8 GB of memory for Docker is plenty), Python 3 and, for the Lighthouse column, Node and Chrome.

  • make bench runs everything in about an hour; results land in bench/results/<date>/.
  • make bench BENCH_ARGS="--setups wp-stock,pursae-nocache --runs 1 --duration 5s" gives a quick look.
  • bench/run.py --help lists the options: --vus, --duration, --reuse (skip seeding), --keep (leave the stacks up on ports 18081 and 18082).
  • Each setup leaves raw k6 summaries, query samples, Lighthouse scores and result.json in bench/results/<date>/<setup>/; summary.json holds everything and bench/report.py turns it into summary.md.
FileWhat
bench/run.pyOrchestration: build, seed, switch setups, measure
bench/wp/compose.yaml, bench/wp/nginx/*.conf, bench/wp/php/*The WordPress stack, nginx configs (stock and WP Super Cache), php-fpm pools, the PhpRedis image
bench/pursae/compose.yamlThe Pursae stack
bench/content/gen.pyThe WXR file and the product payloads
bench/k6/load.jsThe load test
Limits of these numbers One machine with Docker Desktop on macOS (a Linux VM): absolute numbers are lower than on bare Linux, so the ratio matters more than the values. Cache hits on both sides run into the load generator, so cached throughput says "both are fast enough", not who is faster. The themes are equivalent, not identical, and the built-ins are not feature-for-feature copies of the WordPress plugins.

What the built-ins replace

Each built-in plugin covers the core features of a WordPress plugin people usually pay for. Prices are the cheapest one-site plan billed yearly at list price (renewal), read on the vendor's pricing page on 2026-11-09, without tax.

Pursae built-inCovers the core features ofPlanPrice / year
CommerceWooCommerce (free) + premium extensions such as WooCommerce SubscriptionsSubscriptions, 1 year$279
Web BuilderElementor ProEssential, 1 site$60
SEOYoast SEO Premium (and Rank Math PRO)1 site$118.80
CacheWP RocketSingle$60 ($36 first year, offer until 2026-11-28)
CDNWP Offload MediaBronze (up to 2,000 media items)$69 ($39 first year)
CookieComplianz PremiumPersonal, 1 site$59
PixelPixelYourSite ProStarter, 1 site$199
SMTPWP Mail SMTP ProPro, 1 site$99 ($49 first year)
Custom FieldsACF PROPersonal, 1 site$49
Multi LanguagePolylang ProPro€99 (renewals 50 % off)
Backup ManagerAll-in-One WP Migration Unlimited ExtensionStandard (up to 50 sites)$69
Contact FormContact Form 7—free
SecurityThe login-security part of Wordfence / Solid Security — no firewall or malware scannerWordfence Premium($149, not comparable)
MaintenanceMaintenance PRO (WebFactory)Personalsold lifetime only ($59 once)
HeadlessA headless CMS layer; no single WordPress plugin matches——
Total Added up at list prices, the rows with a yearly price come to about $1,062 plus €99 a year for one site (Security, Maintenance, Headless and Contact Form left out). Pursae's built-ins ship in the GPL binary at no extra cost.

Source: docs/developer/benchmarks.md