Access And Capabilities
Onumia separates the question of who you are from the question of what you may do. WordPress answers the first question through its normal authentication, and Onumia answers the second through a small set of explicit capabilities mapped onto WordPress roles. Because the two layers are independent, you can let many roles connect to Onumia while still keeping powerful actions like writing code or promoting changes in the hands of a few trusted users.
How Authorization Works
Every interaction with Onumia begins with an authenticated WordPress user. The MCP transport and any user-scoped state will not respond to an anonymous request, so the first thing Onumia establishes is a real WordPress identity. Agents reach that identity the same way a person would: through a WordPress Application Password issued for the user the agent is meant to act as. The agent inherits exactly that user’s roles, and therefore exactly that user’s Onumia capabilities. There is no separate agent account system and no privilege escalation path around WordPress roles.
Once the user is known, Onumia resolves the capabilities granted to their roles and checks them on every operation. A user with read access can inspect a sandbox but cannot mutate it; a user without promotion capabilities can prepare and preview changes but cannot push them toward the live site. The same checks apply whether the request comes from a human in the admin app or an agent over MCP, because both resolve to the same WordPress user.
Admin Page Access
Access to the Onumia admin screen is broader than access to Onumia settings. Administrators and multisite super admins can always open the app. Other authenticated users can open it when their roles grant Onumia capabilities or when a sandbox has been shared with them, so they can reach the work they are allowed to review.
Settings remain reserved for WordPress users with manage_options. This keeps configuration in the hands of site administrators while still letting invited reviewers and agent users reach their own Onumia workspaces.
The Capability Set
Onumia defines seven capabilities. Each one names a single, concrete action, which makes it possible to grant precisely the access a role needs and nothing more.
| Capability | Allows |
|---|---|
create_sandbox |
Create new sandboxes and manage the lifecycle of sandboxes you own. |
execute_read |
Run read-only commands inside sandboxes you can access. |
execute_write |
Mutate sandbox files and sandbox database rows through allowed command surfaces. |
execute_eval |
Run wp eval and wp eval-file inside accessible sandboxes. |
promote_code |
Promote sandbox Agent Code changes to the live Agent Code repository. |
promote_database |
Promote sandbox database changes through the database merge path. |
manage_all_sandboxes |
Access, inspect, preview, and discard sandboxes owned by other users. |
These capabilities are layered rather than flat. Running any command at all requires execute_read, so it is the baseline for doing useful work in a sandbox. Mutating commands additionally require execute_write, and the wp eval and wp eval-file commands additionally require execute_eval. A user can therefore inspect a site freely, prepare ordinary content and option changes once write access is granted, and only reach the most powerful eval surface when eval is explicitly allowed.
Default Role Mapping
Onumia ships with sensible defaults so a fresh install behaves reasonably before you customize anything. Administrators receive every capability, editors can create sandboxes and run both read and write commands, authors and contributors can create sandboxes and run read commands, and subscribers receive nothing.
| WordPress role | Default Onumia capabilities |
|---|---|
| Administrator | All capabilities. |
| Editor | create_sandbox, execute_read, execute_write. |
| Author | create_sandbox, execute_read. |
| Contributor | create_sandbox, execute_read. |
| Subscriber | None. |
On multisite, super admins are always treated as having every Onumia capability, independent of the stored role mapping. The defaults reflect a common shape for editorial teams: writers and editors can explore the site and prepare changes, while the ability to run eval or promote anything stays with administrators. You are free to redraw these lines for your own site in Settings.
Sandbox Ownership
A sandbox belongs to the user who created it, and ownership is what normally grants access. You can always work with your own active sandboxes: inspect them, run commands against them, preview them, and discard them. Reaching into a sandbox owned by someone else requires the manage_all_sandboxes capability, which lets administrators and other trusted users access, inspect, preview, discard, and target any sandbox on the site. This is what makes shared review and cleanup possible without giving everyone broad control by default.
Activity status is a hard precondition for all of this. An inactive sandbox, such as one that has been discarded, cannot be executed against, previewed, or treated as active work, regardless of who owns it or which capabilities they hold.
Sandbox Sharing
Onumia Pro also lets administrators share a specific sandbox without changing global role capabilities. Sharing is useful when one task needs review from a person or role that should not permanently gain broad Onumia access.
Sharing can target either a WordPress role or a specific WordPress user. Role grants are combined for users who match those roles. A user-specific grant is more precise: when one exists for a user on that sandbox, it becomes that user’s sandbox permission set for the sandbox, rather than merely adding to the role grant. This gives administrators a clean way to narrow or widen access for one reviewer without changing the whole role.
The presets in the Share screen are intentionally task-oriented: Viewer can see the sandbox, Reviewer can also review tasks, Contributor can execute sandbox work and inspect merge data, and Manager can stage merge changes and manage sharing. Promotion remains separate. Moving database changes live requires an explicit promote permission, so sharing a sandbox for review does not accidentally grant production write access unless you deliberately include that permission in a custom grant.
Promotion Rules
Promotion is the deliberate step that moves approved sandbox changes toward the live site, and it is checked carefully. To promote, you must first be able to access the sandbox, and then hold the capability matching the kind of change being promoted: promote_code for Agent Code changes and promote_database for database changes. A single promotion request can include code, database, or both, and Onumia evaluates each requested type independently. Asking to promote both code and database without holding both capabilities is rejected rather than partially applied, so promotion never advances further than the user is authorized to take it.
Settings Stay Out Of Reach
Role capability assignments are kept in Onumia’s own control storage, separate from ordinary WordPress options. Because a sandbox can shadow the options table, keeping the capability map outside it ensures that an agent working inside a sandbox cannot reach the permission settings that govern it.
Overriding Capabilities In Code
For cases that the Settings UI does not cover, you can adjust the effective role capability map programmatically through the onumia/access/role_capabilities filter:
add_filter('onumia/access/role_capabilities', function (array $capabilities): array {
$capabilities['editor'][] = 'promote_code';
return $capabilities;
});
The filter changes the capabilities Onumia actually enforces at runtime. It does not rewrite stored settings, so the Settings UI continues to show the values saved in the control store. Treat the filter as a way to express policy in code that should always apply, and use Settings for the configuration you want site administrators to manage directly.