a Loom with some feature Ideas.

[wpeasy]

Hey. Thank you for such a great little application, and for being so responsive to fixes and updates. It is becoming a brilliant system.

I have a few small suggestions that was easier to put in a Loom: https://www.loom.com/share/9941d8f4accf4f92824b11792c8fe51c

[wpeasy]

You've gone quiet :)

[tts-empire]

Hello, thank you for the ideas! At the moment, I’m going through the deploy plugin approval process for the official WordPress repository. As soon as it’s approved, I’ll get back to coding. :)

[wpeasy]

Hey man.. in about a week I will need to set up automated test sites for users to try an environment.

This is the idea I proposed with an API to automate deployment from a blueprint to a random site name, with a set expiry to self destroy.

I can do this on InstaWP. I just wanted to check in to ask if you are considering implementing this, before I head down the Insta path.

[tts-empire]

Hey @wpeasy — yes, this is now live in SpawnWP 0.5.29.

It implements the flow you described: provision from a blueprint, generate a random site name by default, choose an expiry for automatic destruction, and receive the WordPress URL and credentials. The API connection is explicitly paired and limited to provisioning, and requests are signed, replay-protected, quota-controlled and idempotent.

There is also a small official client, so you do not need to implement the signing protocol yourself. The shortest path is:

spawnwp-api pair "spawnbp1:..." --label "My integration"
spawnwp-api status
spawnwp-api provision --blueprint development --expires 1h --json

The response includes the project, URL, expiry timestamp, username, password and a short-lived magic login link when available. Administrator is the default role, with narrower roles available per request.

Full setup, client usage, CI examples, lifecycle and raw API details are here:
https://spawnwp.com/docs/provisioning-api/

When you have a chance, could you try it with the workflow you are planning and let us know how it feels in real use? Feedback on the pairing process, client ergonomics, response format and anything that creates friction would be especially useful.

[wpeasy]

Hey an. I created a WP Plugin so I could deploy sandbox accounts.

It fails to create new sites from blueprints that otherwise work from the 'Cockpit'. The error feedback was lacking so I could not troubleshoot. After a Claude session to diagnose. Here it determined.

SpawnWP — Bug Report

Date: 2 August 2026
Reported by: Alan Blair (WPEasy)
Host: dev-wp (self-hosted SpawnWP)
Context: Integrating the Provisioning API with a public-facing WordPress plugin. Four issues found, one of which makes a blueprint permanently unusable and another which made diagnosing it take roughly an hour longer than it should have.

---

Environment

SpawnWP release	0.5.29 (/opt/spawnwp/current → /opt/spawnwp/releases/0.5.29)
Cockpit	/srv/wp-cockpit, uvicorn on 127.0.0.1:9393, single worker
OS	Ubuntu 24.04.4 LTS, kernel 6.8.0-136-generic
Python	3.12.3
Docker	29.6.1 (build 8900f1d)
Blueprint under test	bricks-2-4-beta v1.0.2 — PHP 8.4, WordPress 7.0.2

---

Issue 1 — Blueprint import fails permanently when the captured site has orphaned tables

Severity: Critical — the affected blueprint can never provision, on any host.
Component: scripts/import-database.php (invoked via apply-content-blueprint.sh:92)

Symptom

Every POST /api/provision using blueprint bricks-2-4-beta fails. Site creation runs to completion — containers healthy, WordPress installed, plugins/themes/uploads applied — and then dies at the database import, rolling the whole site back:

==> Applying resolved blueprint...
==> Applying content blueprint Bricks 2.4-beta 1.0.2...
==> Verifying payload integrity...
==> Extracting payload...
==> Installing captured plugins...
==> Installing captured themes...
==> Installing captured uploads...
==> Importing captured database...
Error: Unable to determine the source table prefix from the export.

Reproducible 100% of the time. creates_failed on this host is now 7.

Root cause

import-database.php derives the source table prefix from the export by finding every table ending in options that has a sibling posts table, then requires exactly one candidate:

// scripts/import-database.php:52-62
$candidates = array();
foreach ( array_keys( $tables ) as $name ) {
    if ( str_ends_with( $name, 'options' ) ) {
        $prefix = substr( $name, 0, -strlen( 'options' ) );
        if ( isset( $tables[ $prefix . 'posts' ] ) ) {
            $candidates[] = $prefix;
        }
    }
}
if ( 1 !== count( $candidates ) ) {
    WP_CLI::error( 'Unable to determine the source table prefix from the export.' );
}

The site this blueprint was captured from carries two complete-looking table sets:

Prefix	Tables	Notes
pdtnqy_wp_	25	The live set — includes users, usermeta, spawnwp_deploy_*
wp_	19	Orphaned — no users, no usermeta

Both sets contain options and posts, so both satisfy the heuristic, count($candidates) === 2, and the import aborts.

The orphaned wp_* set is the ordinary residue of a table-prefix rename — a security plugin, a migration, or the wp-reset plugin (which is itself bundled in this blueprint's payload). The absence of wp_users/wp_usermeta is the tell: prefix-rename tooling routinely leaves the originals behind. This is a common state on a real production site, not an exotic one.

Evidence

Run against the payload on the host, using the same logic as the importer:

import zipfile, json
z = zipfile.ZipFile("/var/lib/spawnwp/blueprints/bricks-2-4-beta/payload-1c554d5b.zip")
tables = []
with z.open("database.jsonl") as fh:
    for raw in fh:
        if raw.startswith(b'{"type":"table"'):
            tables.append(json.loads(raw)["name"])
cands = [t[:-7] for t in tables if t.endswith("options") and (t[:-7] + "posts") in tables]
print(len(tables), cands)

44 ['pdtnqy_wp_', 'wp_']

Orphaned tables in the export:

wp_options  wp_posts  wp_postmeta  wp_comments  wp_commentmeta
wp_terms  wp_termmeta  wp_term_taxonomy  wp_term_relationships  wp_links
wp_bricks_filters_element  wp_bricks_filters_index  wp_bricks_filters_index_job
wp_mb_relationships  wp_novamira_chat_sessions
wp_novamira_oauth_access_tokens  wp_novamira_oauth_auth_codes
wp_novamira_oauth_clients  wp_novamira_oauth_refresh_tokens

Same audit across all blueprints on this host:

Blueprint	Tables	Candidates	Imports?
bricks-2-4-beta	44	pdtnqy_wp_, wp_	No
bricks-basics	13	wp_	Yes
wpeasy-blurprint	15	wp_	Yes

Suggested fixes

Ordered by robustness:

1. Record the prefix at capture time. The capturing side knows $wpdb->prefix for certain. Writing it into the manifest removes the guesswork entirely and is backward-compatible (fall back to the heuristic when absent).
2. Disambiguate on evidence rather than failing. When several candidates exist, prefer the one whose options table actually contains a siteurl / home row, or the one with a sibling users table. Either would have selected pdtnqy_wp_ here unambiguously.
3. Improve the error message. If it must fail, name the candidates it found — Ambiguous source prefix: pdtnqy_wp_, wp_ — so the cause is obvious instead of requiring the operator to unzip and parse the payload.

---

Issue 2 — Every site-creation failure is reported as the rollback notice, hiding the real error

Severity: High (diagnosability)
Component: app.py:910-916, run_project_creation()

Symptom

Every failed creation surfaces the same useless message to the API caller and stores it in provision_requests.error:

!! Creation failed; rolling back partial resources...

The actual error is never shown, never logged, and never persisted.

Root cause

The full subprocess output is captured, then all but the last line is discarded:

# app.py:910-916
if proc.returncode != 0:
    detail = next(
        (line.strip() for line in reversed(output.splitlines()) if line.strip()),
        "Site creation failed",
    )
    status = 409 if "another site operation" in output.lower() else 500
    raise HTTPException(status, detail[:500])

new-project.sh installs an EXIT trap (line ~59) that prints:

echo "!! Creation failed; rolling back partial resources..." >&2

Because the trap runs last, that notice is always the final line of output. So detail is that notice on every single failure, and output — which contains the real error — is thrown away without ever reaching the log.

Practically: journalctl -u wp-cockpit showed only POST /api/provision → 500, and the database recorded only the rollback notice. The genuine error (Unable to determine the source table prefix from the export.) was only obtainable by running new-project.sh by hand and capturing stdout.

Suggested fix

Log the whole output, and skip trap/progress noise when picking the summary line:

if proc.returncode != 0:
    # new-project.sh's EXIT trap prints its rollback notice last, so the final
    # output line is almost never the real error.
    print(f"[provision] site creation failed for {name} (rc={proc.returncode}):", flush=True)
    print(output, flush=True)
    lines = [line.strip() for line in output.splitlines() if line.strip()]
    noise = ("==>", "->", "!! creation failed", "rolling back")
    detail = next(
        (line for line in reversed(lines) if not line.lower().startswith(noise)),
        lines[-1] if lines else "Site creation failed",
    )
    status = 409 if "another site operation" in output.lower() else 500
    raise HTTPException(status, detail[:500])

Logging the full output is the important half — the heuristic is a convenience. Consider also persisting a truncated tail into provision_requests.error rather than a single line.

Status: patch applied and validated on this host

We have applied exactly the above patch to /srv/wp-cockpit/app.py on dev-wp. It parses cleanly, the service restarted without issue, and it is what allowed Issue 1 to be identified at all — the real error (Unable to determine the source table prefix from the export.) became visible immediately instead of the rollback notice.

Offered as a tested change rather than a theoretical one. A backup of the original is at /srv/wp-cockpit/app.py.bak-20260801-222102 should you want the exact diff.

---

Issue 3 — Blueprint capture does not validate that the result can be imported

Severity: Medium
Component: blueprint capture

bricks-2-4-beta captured successfully and presents as entirely healthy:

• blueprint.py resolve bricks-2-4-beta returns valid JSON with no warning
• The payload exists, is 72,507,758 bytes, and its SHA-256 matches the manifest
• It is offered in the cockpit UI and accepted by POST /api/provision

…yet it is structurally incapable of ever being imported. The failure only appears minutes later, after a full site has been built and must be torn down.

Suggested fix: run the importer's prefix detection at capture time and fail (or warn loudly) there, where the operator still has the source site in front of them. A capture that cannot be restored is not a successful capture.

---

Issue 4 — spawnwp-site-expiry.service is in a failed state

Severity: Low–Medium (depending on how long it has been failing)

● spawnwp-site-expiry.service   loaded failed failed   SpawnWP destruction of expired temporary sites

Expired sandboxes may not be being reclaimed. For API connections this matters more than it looks: the provisioning quota is concurrent sites, so sites that outlive their expiry silently consume quota until POST /api/provision starts returning 409 Provisioning quota reached. Not investigated further, but flagging it as it directly affects API-driven provisioning.

---

Issue 5 — /var/lib/spawnwp/VERSION missing, so the API reports its version as unknown

Severity: Trivial

GET /api/provision/status returns spawnwp_version via:

# ingest.py:68-72
def _spawnwp_version() -> str:
    try:
        return Path(os.environ.get("SPAWNWP_VERSION_FILE", "/var/lib/spawnwp/VERSION")).read_text().strip()
    except OSError:
        return "unknown"

That file does not exist on this host, so integrations reading spawnwp_version get "unknown" even though /opt/spawnwp/current clearly resolves to 0.5.29. May be specific to how this host was installed/upgraded, but worth confirming the installer writes it.

---

What is working well

For balance — the parts we exercised heavily and found solid:

• Ed25519 request signing is precisely specified and behaved exactly as documented (method \n path \n timestamp \n nonce \n sha256(body)), including the ±300 s window and single-use nonces.
• Idempotency semantics are well designed: 409 on key reuse with a different body, replay of the stored response on a repeat, and the atomic BEGIN IMMEDIATE reservation in _reserve() is genuinely careful concurrency work.
• Rollback is clean. Every failed creation we triggered left no project directory, no orphaned containers, no stale provision_sites rows, and no leaked nginx config. That is the hard part, and it works.
• Schema validation via pydantic gives precise, actionable 422 bodies — see the note below.

---

Documentation note

Two constraints cost us real debugging time because they are enforced but not documented at https://spawnwp.com/docs/provisioning-api/:

1. name is the project slug, not a display name. It must match ^[a-z0-9][a-z0-9-]{0,30}$ and doubles as the site identifier, returning 409 Project already exists on reuse. Our first integration passed the end user's name ("Alan Blair") and got a 422 on the capitals and space. Worth stating explicitly that it is a slug, that omitting it yields a generated name, and that reuse collides.

2. Optional fields must be omitted, not sent empty. group: "" is a 422, since the schema has no empty case. Documenting the full constraint set would help:

   Field	Constraint
   blueprint	required, ^[a-z0-9][a-z0-9-]{0,30}$
   expires_seconds	300 … 31536000 (default 3600)
   role	administrator | editor | author | contributor | subscriber
   group	^[A-Za-z0-9][A-Za-z0-9 ._\-]{0,31}$ (default API)
   name	optional, ^[a-z0-9][a-z0-9-]{0,30}$

3. Errors are returned in detail, never message — a string for HTTPException, or pydantic's [{loc, msg, type}] array for a 422. Clients written against a message field silently fall back to a generic error. A short "error format" section would prevent that.

Also: GET /api/provision/status returns quota as active_sites plus limits.concurrent_sites, with no remaining field. Documenting the response shape would remove the guesswork.

---

Reproduction

On a host with a blueprint captured from a site carrying orphaned tables:

sudo bash /srv/wp-dev/scripts/new-project.sh testsite bricks-2-4-beta "" "" \
  > /tmp/create.log 2>&1; echo "rc=$?"
tail -20 /tmp/create.log

Expected: Error: Unable to determine the source table prefix from the export. followed by rollback.

Via the API the same failure returns 500 with detail: "!! Creation failed; rolling back partial resources..." — which is Issue 2.

To check any blueprint payload for the condition:

sudo python3 - <<'EOF'
import zipfile, json, glob, os
for d in sorted(glob.glob("/var/lib/spawnwp/blueprints/*")):
    for z in sorted(glob.glob(os.path.join(d, "*.zip"))):
        zf = zipfile.ZipFile(z)
        if "database.jsonl" not in zf.namelist():
            continue
        tables = []
        with zf.open("database.jsonl") as fh:
            for raw in fh:
                if raw.startswith(b'{"type":"table"'):
                    tables.append(json.loads(raw)["name"])
        c = [t[:-7] for t in tables if t.endswith("options") and (t[:-7] + "posts") in tables]
        print(f"{os.path.basename(d):<30} {len(tables):>4} tables  candidates={c}  "
              f"{'OK' if len(c)==1 else 'WILL FAIL'}")
EOF

---

Priority suggestion

#	Issue	Severity	Notes
2	Creation errors masked by rollback notice	High	Fix first — it hides every other failure, including Issue 1
1	Prefix ambiguity breaks import permanently	Critical	Blueprint unusable; capture-time prefix recording is the durable fix
3	Capture doesn't validate importability	Medium	Would have caught Issue 1 at capture
4	spawnwp-site-expiry.service failed	Low–Med	Silently consumes API quota
5	VERSION file missing	Trivial	API reports unknown

Issue 2 is listed first deliberately: with it fixed, Issue 1 would have been a two-minute diagnosis instead of an extended investigation, and any future failure becomes self-describing.

[tts-empire]

Hey Alan — thank you for the exceptionally thorough report. The diagnosis was correct, and the reproduction details materially improved the implementation.

The fixes are now live in SpawnWP 0.5.31, together with SpawnWP Deploy 0.3.5 on WordPress.org. The updated API documentation is at https://spawnwp.com/docs/provisioning-api/ and the blueprint compatibility notes are at https://spawnwp.com/docs/blueprints/.

Here is what changed, including where we deliberately chose a different implementation from the suggestions:

1. The active database prefix is now captured exactly. Deploy 0.3.5 sends $wpdb->prefix as authenticated transport metadata. The SpawnWP server verifies that the matching options and posts tables are present before completing the capture, then stores the verified prefix beside the immutable payload.

   We kept this metadata out of the public schema-v2 manifest. That avoids changing an established manifest/rollback contract for a transport concern while still making every new database capture deterministic.

   Legacy captures remain compatible when they contain exactly one candidate. If they contain several, SpawnWP now names every candidate and asks for a re-capture instead of guessing.

   We did not adopt the users/usermeta or siteurl/home tie-breakers. The exporter intentionally excludes the current WordPress user tables, so they are not a dependable signal; and an abandoned but complete options table can still contain apparently valid siteurl and home rows. Importing the wrong database state would be worse than refusing an ambiguous legacy capture.

2. Provisioning now returns the actual creation failure. Progress lines and the final rollback notice are skipped when selecting the error detail, so the database-prefix error in your example is surfaced directly.

   We intentionally did not log the complete subprocess transcript. Successful portions of site creation can print generated WordPress credentials and other secrets. Instead, the journal receives one bounded diagnostic line with password/token/secret-like values redacted. This preserves the diagnostic benefit of your tested patch without creating a credential-leak path.

3. An unusable prefix declaration is rejected during capture finalization. The server checks the declared active prefix against the exported table metadata before registering the blueprint as complete. New captures containing orphaned table sets therefore remain restorable; a mismatched declaration never becomes a healthy-looking blueprint.

4. The expiry scan no longer stops at a permanent site. We found a pipefail interaction where a normal .env without SPAWNWP_EXPIRES could terminate the scan before later temporary sites were processed. The parser now skips permanent sites and continues, including when the final .env line has no newline.

5. Version reporting now has a real fallback. Both the API and updater first use /var/lib/spawnwp/VERSION; if it is missing or invalid, they resolve /opt/spawnwp/current and accept its target directory only when the name is a stable semantic version. This final correction is in 0.5.31.

We also documented every provisioning request constraint, the meaning and collision behavior of name, omission of empty optional fields, all three detail error shapes, and the complete status/capacity response.

For the affected bricks-2-4-beta blueprint, the safe recovery path is to update the SpawnWP host, update SpawnWP Deploy to 0.3.5, and capture it again. The existing ambiguous payload does not contain enough authoritative information for the server to know which table set was active without guessing.

When you have a chance, please retry the WordPress-plugin workflow that exposed this. Feedback on the new failure detail and re-captured blueprint flow would be especially useful.

[tts-empire]

First, the big one: SpawnWP Deploy was officially approved on WordPress.org today. It's live in the plugin directory: https://wordpress.org/plugins/spawnwp-deploy/ — so it now updates through the standard WordPress update system like any other plugin. Full details in #12.

And sorry for the radio silence otherwise — I was heads-down shipping the things in your Loom. All four are done.

The stale Deploy plugin (0:33). You were right: the installer was deploying 0.3.3 while 0.3.4 was already out, which is why the settings weren't there. Fixed in 0.5.21 — spawning now fetches the newest published release from spawnwp.com, verifies its SHA-256 and Ed25519 signature, and only installs it if it's strictly newer than the bundled copy. The deploy log tells you which version went in and where it came from.

Naming and deleting snapshots (1:10). In 0.5.22. Double-click a snapshot (or hit ✏️) to name it, 🗑 to delete it — the DB dump, the uploads tarball and the name all go. Deleting asks for the same Passkey confirmation as a restore, since it destroys a restore point. The files keep their timestamp filenames and the names live in a small sidecar; the timestamp is what the restore path validates, and I didn't want that check depending on whatever got typed into a text box. Existing snapshots just show up unnamed until you name them.

Magic login (2:12). Also 0.5.22, and in 0.5.23 it's on by default for new sites — shipping it opt-in was a mistake on my part, a one-click sign-in you have to enable per site isn't much of a one-click sign-in. Existing sites don't need recreating: hit Enable magic login once on any of them.

It doesn't need the Deploy plugin. You said you'd be fine with that dependency, but Deploy ships through WordPress.org and a login bypass has no business going through a public plugin directory, so it's a small must-use plugin the cockpit writes on request. Links are single-use and die after two minutes; the server only ever stores their SHA-256, and the plugin invalidates a link before it signs you in, so the same link can't be used twice even by two simultaneous requests. Turning it off deletes the plugin from the site rather than flagging it off somewhere.

One thing worth knowing up front: Deploy packages exclude mu-plugins, so magic login doesn't travel with a published site — you'll re-enable it on the destination. That's deliberate, but it'll look like a bug if you're not expecting it.

Folder and zip uploads (2:44). In 0.5.22. "⬆ Upload folder" takes a whole tree and rebuilds it; any .zip gets a 📦 button that extracts it in place. Archives get read before anything is written — if an entry would land outside the target folder, the whole archive is refused and it names the offending entry.

Docs for all of it are up: using the cockpit and security.

Thanks for taking the time to record the Loom. It was genuinely more useful than a bug list. Give it a spin and tell me what still feels wrong.