Introduction
Onumia is a WordPress plugin that lets AI agents do real work on a real WordPress site without ever touching it directly. Every task an agent performs runs inside an isolated sandbox, work is reviewed through private preview URLs, and nothing reaches the live site until an administrator deliberately promotes it.
These docs explain how that workflow fits together: how sandboxes isolate changes, how capabilities decide what each user and agent can do, how agents connect over MCP, and how you review and promote finished work.
What Onumia Does
AI agents are most useful when they can see the site they are helping with. They want to read posts and options, inspect plugins and themes, search code and content, and often write changes or add functionality. Doing any of that directly against production is risky, because a single bad command or half-finished edit reaches live visitors immediately.
Onumia removes that risk by giving every task its own workspace. A sandbox has its own database state, its own editable checkout of the Agent Code plugin, and its own preview URL. An agent connected to that sandbox can inspect and change it freely, within the limits of the capabilities it has been granted, while the live site keeps serving the approved version. When the work looks right, an administrator promotes the code, the database changes, or both. When it does not, the sandbox is discarded and nothing is lost on the live site.
The result is a workflow where access can be broad but control stays tight. Many people and agents can work on the same site at once, each in their own sandbox, and the site owner remains the only party who can make anything live.
The Core Workflow
The shape of every Onumia task is the same. You create a sandbox for the work, the agent inspects and changes it, you preview the result in a browser, and an administrator promotes or discards it.
- Create a sandbox for a task.
- Let the connected agent inspect or change the sandbox.
- Open the sandbox preview URL to review it in a browser.
- Promote the approved code and database changes, or discard the sandbox.
Because changes live in the sandbox until that final step, a sandbox preview can look and behave completely differently from the live site while the public site stays untouched.
Concepts To Know
A handful of terms recur throughout these docs. Understanding them first makes everything else easier to follow.
| Concept | What it means |
|---|---|
| Sandbox | An isolated workspace for one task, user, or agent session, with its own database state and Agent Code checkout. |
| Preview | A private browser URL that shows the site exactly as a sandbox sees it. Previewing never grants command or promotion rights. |
| Promotion | The administrator-controlled step that moves approved sandbox code or database changes toward the live site. |
| Agent Code | The dedicated WordPress plugin where agents add custom functionality, kept in one predictable place rather than scattered across themes and plugins. |
| Capabilities | Onumia-specific permissions assigned per WordPress role that decide what each user and their agents can do. |
| MCP server | The agent connection endpoint Onumia exposes at /wp-json/onumia/mcp. |
| Control data | Onumia’s dedicated database tables for sandboxes, audit logs, and key-value settings, kept separate from ordinary WordPress options. |
How These Docs Are Organized
If you are setting Onumia up for the first time, begin with installation and the admin screens, then decide how capabilities map to your WordPress roles before connecting an agent. The Getting Started and Admin UI pages cover that ground, and the access and sandbox pages explain the permission model and the unit of work in detail.
Once Onumia is configured, the agent-facing material describes how a client authenticates with an Application Password, connects to the MCP server, and runs commands through the capability-aware command runtime. The review and promotion pages then cover previews, the optional Pro workspace, Agent Code, and how database isolation and the structured database merge keep promotions clean. Finally, the operations and reference pages document sandbox defaults, audit logs and control data, the configuration filters, the REST API, and troubleshooting.
The sidebar links every page in a sensible reading order, so you do not need to navigate by hand from here.
The Safety Contract
Onumia’s guarantees are structural, not advisory. Each sandbox uses its own database table prefix, and Onumia’s managed db.php drop-in transparently routes requests to those sandbox tables whenever a sandbox preview or command is active. Database writes during sandbox execution are guarded so they cannot reach live tables, and every agent command is capability-gated. The most powerful commands, wp eval and wp eval-file, require a separate eval capability and pass through additional safety checks before running.
Review and promotion are deliberately one-directional. A preview link only previews; it carries no ability to run commands or to promote. Promotion is always explicit and administrator-controlled, so unfinished or unwanted work never becomes live by accident. Settings and audit history are stored in Onumia’s own control tables rather than copied into sandbox options, which keeps configuration and logging stable no matter which sandbox is active.
This structure does not replace good operational discipline. You should still review agent work, keep backups, and think carefully about which roles receive write, eval, and promotion capabilities.
Current Surfaces And Limits
Onumia exposes a WordPress admin page for administrators with an Overview dashboard and a Settings area for role capabilities and sandbox defaults, plus the Pro Workspace when the Pro bundle is installed. Agents connect through the MCP server at /wp-json/onumia/mcp, and REST routes live under /wp-json/onumia/v1/. Host-specific behavior can be tuned through Onumia’s public WordPress filters.
Two limits are worth knowing up front. Local database cloning is capped at 250 MB of copied payload by default; sites larger than that should not use local prefix cloning without deliberately raising the limit or adopting a future external database integration. Database merge is staged visually in Workspace and also available through MCP and REST, so reviewers can scan changes, stage change groups, preflight, apply, and roll back selected promoted rows when needed.