Getting Started

Onumia runs entirely inside WordPress and leans on the systems WordPress already provides: authentication, roles, the REST API, and Application Passwords. Getting started means installing the plugin, letting it set up its control data and database drop-in, deciding what each role can do, and connecting your first agent over MCP. This page walks through that path end to end.

Requirements

Onumia is built for WordPress sites where trusted users want agent-assisted work with review before anything goes live. Before installing, confirm your environment meets the following requirements.

Requirement	Why it matters
WordPress with the REST API available	Onumia’s admin app, agent connections, and MCP server all run over REST.
PHP 8.2 or newer	The minimum runtime Onumia supports.
A WordPress administrator account	Setup and settings require manage_options; later promotion is controlled by Onumia permissions.
Application Passwords enabled	Agents authenticate as real WordPress users through Application Passwords.
WP-CLI on the host	Required only if agents should run wp commands through Onumia.
A database within the clone limit	Local sandbox cloning is capped at 250 MB of copied payload unless you raise it deliberately.

Onumia works without the Pro bundle. Pro adds the browser-based Workspace screen for reviewing sandboxes; everything else described here is part of the core plugin.

Activation

When you activate Onumia, two things happen automatically. First, Onumia initializes its dedicated control tables, which hold sandbox records, audit logs, and a key-value store for settings. These tables are separate from ordinary WordPress options so that configuration and history stay stable regardless of which sandbox is active. On first run, activation also seeds the default role capabilities, default sandbox settings, and the control schema version.

Second, Onumia installs a managed WordPress database drop-in named db.php into your content directory. This drop-in is what makes sandbox database isolation work: when a sandbox preview or sandbox command is active, it transparently routes WordPress to the sandbox’s table prefix instead of the live tables.

If an unmanaged db.php already exists, Onumia will not overwrite it. Sandbox database routing depends on the managed drop-in, so you should resolve that conflict, by merging the existing drop-in’s behavior or removing it, before relying on sandbox previews and database changes.

First-Run Setup

Work through the setup once as a WordPress administrator. The steps build on each other: configure access, confirm defaults, then connect and smoke-test an agent.

1. Activate Onumia and open its admin page.
2. Review the Overview screen to confirm the plugin is healthy.
3. Open Settings and confirm the role capabilities match how you want to expose Onumia.
4. Confirm the sandbox defaults under the Sandbox defaults section.
5. Create an Application Password for the WordPress user the agent will connect as.
6. Point the agent at the MCP server at /wp-json/onumia/mcp using that user and Application Password.
7. Ask the agent to load Onumia’s context resource, create a sandbox, and run on help to confirm the connection works.

Who Can Access What

It helps to keep two layers of permission distinct. Settings are gated by the standard WordPress manage_options capability, so only administrators configure Onumia. The rest of the app can also open for authenticated users who have Onumia capabilities or have been invited to a sandbox, so they can reach the work they are allowed to review. What users and their connected agents can actually do is governed separately by Onumia’s own capabilities and sandbox permissions.

This separation is deliberate. You can grant an author the ability to create sandboxes and run read-only commands without giving them any WordPress admin access, and you can reserve promotion entirely for administrators. The agent inherits exactly the Onumia capabilities of the user whose Application Password it connects with, never more.

Your First Sandbox

A connected agent or client creates a sandbox with the create_sandbox tool. The response identifies the new workspace and everything needed to work in it and review it.

Field	Description
sandbox_id	The identifier every later call must target.
status	The sandbox’s current lifecycle state.
effective capabilities	The Onumia capabilities in force for this sandbox and user.
preview URL	The private browser URL that renders the sandbox.
creation time	When the sandbox was created.

From this point on, every command, preview, promotion, database merge, or discard call must reference the sandbox_id. That identifier is how Onumia knows which database state, code state, capabilities, and preview belong to the work in progress.

The Local Database Clone Limit

Sandboxes get their database state from a local clone of the live tables, and by default that clone is capped at 250 MB of copied payload. The cap exists to keep sandbox creation fast and predictable on ordinary hosting. To stay within it on content-heavy sites, Onumia can copy log-like tables as schema only and redact log-like columns during the clone, so bulky, low-value data does not count against the budget.

If Onumia cannot estimate the database size at all, it blocks local clone creation by default rather than risk an unbounded copy. You can raise the limit from the Sandbox defaults section in Settings or with a WordPress filter, but only do so once the site operator has confirmed that local prefix cloning is acceptable for that site. Sites well above the limit are better served by a future external database integration than by a large local clone.

A Good First Prompt

Before asking an agent to change anything, run a small, explicit task that exercises the whole pipeline. The following prompt confirms that the MCP server, permissions, command runtime, sandbox routing, and preview generation are all working together.

Load the Onumia context resource, create a sandbox named "Initial Onumia test",
run "on help", run "wp core version", and return the preview URL.

If the agent creates the sandbox, both commands return output, and you can open the preview URL in a browser, your installation is ready for real work.