Sandboxes

View as Markdown

A sandbox is the unit of work in Onumia. It is an isolated copy of your WordPress site, with its own database state and its own editable Agent Code checkout, where an agent can inspect, change, and demonstrate work without touching anything your live visitors see.

The rule of thumb is one sandbox per task. Whether that task is a single agent run, one proposed feature, or one content change, keeping it in a dedicated sandbox keeps unfinished work away from production and cleanly separated from whatever else is in flight. Because each sandbox carries its own database prefix and workspace, several people or agents can work on the same site at the same time without colliding.

What a sandbox holds

Each sandbox bundles everything one task needs and nothing it does not: its own database tables, kept separate from the live site by a private prefix, its own editable Agent Code checkout, its own files, and a time-limited preview link. Onumia also tracks each sandbox’s owner, its lifecycle status, and an optional label so you can tell tasks apart.

Sandbox IDs

The sandbox ID is the handle for everything that follows. Onumia generates it when the sandbox is created and uses it to identify which database state, code checkout, and preview belong to the current task. Command execution, preview generation, database merge scanning, promotion, and discard all take a sandbox ID, so an agent should hold on to the sandbox_id returned by create_sandbox and pass it to every subsequent call.

Lifecycle

Work in a sandbox follows a deliberate path, and nothing along it is implicit. A change does not reach your live site simply because it exists in a sandbox; promotion and discard are explicit, separate steps.

Create the sandbox for a task.
Run read or write commands inside it.
Generate or open a preview.
Review the result.
Promote the approved changes, keep working, reopen, or discard the sandbox.

The status field reflects where a sandbox sits on that path. Only active sandboxes can be used as live workspaces for command execution and preview; the remaining states are terminal or transitional.

Status	Meaning
`active`	The sandbox is usable for command execution and preview.
`promoting`	Promotion is in progress.
`promoted`	Promotion completed, preview state was invalidated, and database promotion history can be inspected.
`promotion_failed`	Promotion failed; the sandbox records failure metadata and can be discarded.
`discarded`	The sandbox was discarded and its preview state was invalidated. Database promotion history remains inspectable when it exists.
`expired`	The sandbox is past its lifetime and is no longer active.

Creating a sandbox

Creation is where Onumia builds the isolated environment and enforces its guardrails before any side effects occur. When create_sandbox runs, Onumia confirms the caller is authenticated and holds the create_sandbox capability, then checks that the user is under their active sandbox limit. Before cloning anything, it estimates the size of the database payload it would copy and refuses to proceed if that estimate exceeds the configured local clone limit, so a runaway clone fails early rather than half-built.

Once those checks pass, Onumia provisions the workspace: it creates the sandbox paths, checks out a fresh copy of Onumia Agent Code, and clones the WordPress tables under the sandbox’s own prefix. When MerQL database promotion is configured, it also captures a base database snapshot so later promotion can compute a structured merge. Finally it stores the sandbox record and returns a preview URL the owner can open immediately.

Ownership and access

A sandbox belongs to the user who created it, and by default users work only with their own active sandboxes. The manage_all_sandboxes capability widens that boundary: a user who holds it can see, preview, target, and discard active sandboxes owned by other users, which is how an administrator oversees a fleet of agent-created work. Access is always checked against the current user’s effective capabilities, never against the preview link alone.

Previews

Every active sandbox can produce a preview URL that renders the WordPress site using the sandbox’s database state and its copy of Agent Code. The live public site is unaffected while the preview is open.

A preview is strictly a review link. The preview token lets a reviewer see the sandbox in a browser; it does not grant command execution, promotion rights, or admin access. Treat preview URLs as private, and share them only with people who should see the proposed change.

Promotion

Promotion is the deliberate step that moves approved work out of the sandbox and toward the live site. A single promotion can carry Agent Code changes, sandbox database changes, or both. It begins with a preflight, or dry-run, pass so the operation can be validated before anything is committed, and Onumia records each promotion step in the audit log. Database changes are not blindly copied over live data; when MerQL is enabled, promotion applies a structured merge against the base snapshot captured at creation.

Database merge promotion has an explicit retention choice. The normal Workspace action moves the sandbox into promoted status after the live write, which keeps the promotion history available but stops preview and execution. Backend and MCP callers default to keeping the sandbox active, so automated workflows can apply one selected merge and continue working if they need to.

Promoted sandboxes can be reopened while their resources still exist. Reopen flips the sandbox back to active and creates a fresh preview token. Promotion history stays attached, and the next merge scan recomputes against the current live database.

Discard

Discarding ends a sandbox without keeping its working resources. After checking access, Onumia marks the sandbox discarded, invalidates its preview token data so old links stop working, and removes the sandbox’s Agent Code checkout and cloned database tables where the environment allows. The discard event is recorded. Discarded work never becomes live.

Discarding a promoted sandbox does not delete the undo trail. Database promotion events and rollback artifacts live in Onumia logs, so a discarded sandbox with promotion history can still be opened from the Promoted scope, inspected, and rolled back where live rows have not drifted.

Working in parallel

Because each sandbox has its own table prefix and workspace, Onumia supports many active sandboxes at once, including several agents working simultaneously. The practical thing to manage in that situation is clarity, not collisions: give each sandbox a descriptive label so administrators can tell at a glance which task each one represents when they come to review and promote.