Previews

View as Markdown

A preview lets you see your WordPress site exactly as a sandbox sees it, in a real browser, before any of the work is promoted. It is how a reviewer judges proposed changes without affecting a single live visitor: opening a preview never makes a sandbox live, it only renders the sandbox’s state for inspection.

What a preview shows

When you open a preview, Onumia serves the site against the sandbox’s isolated database and its copy of Agent Code instead of the live equivalents. So the preview reflects the sandbox’s rows and options, its posts, terms, comments, and metadata, and any frontend behavior those changes produce. It also runs the sandbox’s version of Onumia Agent Code, which means a shortcode, hook, REST endpoint, or template adjustment an agent built can be exercised end to end before promotion. Throughout, the live public site stays exactly as it was.

How preview URLs work

A preview URL carries two things: the sandbox ID and a single-use preview token. The first time the link is opened, Onumia validates the token against the sandbox, and if it is valid, stores the sandbox selection in a private cookie and immediately redirects to the same URL with the token removed.

That redirect is deliberate. After the first request the token no longer appears in the address bar, browser history, or referrer headers, while the cookie keeps the reviewer pinned to the sandbox for subsequent navigation. The cookie is HTTP-only and scoped to the site, so it is readable by the server but not by page scripts.

How Workspace previews work

The Pro Workspace uses the same sandbox preview session, but it presents it differently. Before the browser panel appears, Workspace asks Onumia for a short-lived preview session, prepares an in-admin preview frame, and lets a same-origin browser worker attach the sandbox ID and preview token to the frame’s requests. This keeps normal navigation inside the frame pointed at the sandbox without leaving a sandbox query string on every page you visit.

That distinction matters when you are reviewing from the admin app. The fixed /onumia-preview-frame page is only a bootstrap page for the in-admin browser. After it binds to the preview session, it navigates to the sandbox target and keeps the sandbox scope through same-origin clicks, reloads, back/forward navigation, and /wp-admin/ review. If the session expires, Workspace prepares a fresh session the next time the preview is opened.

Tokens and expiry

Preview tokens are deliberately short-lived. Onumia stores only a hash of each token, never the raw value, and the token is valid only until its expiry timestamp. Once a token is expired or otherwise invalid, Onumia refuses the preview rather than guessing. When you need a working link again, the preview_sandbox tool issues a fresh preview URL for an active sandbox.

What a preview does not grant

A preview token is a viewing credential and nothing more. Possessing a preview link does not give the holder any ability to act on the sandbox.

A preview lets you	A preview does not let you
Open the sandbox state in a browser	Run commands inside the sandbox
Review proposed content and code	Change Onumia settings
Exercise agent-built frontend behavior	Promote the sandbox
	Reach the WordPress admin via the token
	Use the MCP connection

Because of this separation, a preview link can be shared with a reviewer who has no Onumia capabilities at all, and they still cannot change anything.

Even though a preview grants no power to act, treat the URL as private. A preview can expose unpublished content, test data, draft settings, or functionality an agent is still building, so share it only with people who are meant to see the proposed change.

A preview is served through WordPress as an ordinary site request, so normal site rules still apply. Theme behavior, plugin behavior, login state, and frontend access control all work as they would on the live site. If a page normally requires a WordPress login to view, the reviewer will still need to log in to see it inside the preview.

Ending a preview

Preview state lives entirely in the cookie, so leaving it is straightforward. A reviewer can clear the onumia_sandbox cookie or simply open the live site in a clean browser profile to return to the normal site. Promotion and discard both invalidate a sandbox’s preview state, so once a sandbox has been resolved, its preview links stop working on their own.