Configuration Reference

View as Markdown

Onumia is configured in three layers. The admin Settings UI covers the day-to-day choices a site owner makes, WordPress constants handle host and deployment wiring that belongs in wp-config.php, and the onumia/* public filters let you drive any of it from code when configuration should come from your deployment pipeline rather than the database. As a rule, reach for the admin UI for ordinary settings and for constants or filters when behavior depends on the host, the environment, or an integration.

Admin Settings

Administrators manage the everyday configuration from the Onumia settings screen, which is gated behind the standard manage_options capability. From there you assign Onumia capabilities to each WordPress role, set the default sandbox TTL, cap the number of active sandboxes a single user may own, set the local clone size limit, and choose how long inactive sandboxes are retained before cleanup. These values are persisted in the database, so they travel with the site rather than living in code.

Constants

Constants are the right tool for values that belong in wp-config.php: paths, binaries, and credentials that differ between environments and should never be committed alongside application code. Define them before WordPress loads Onumia.

Constant	Purpose
`ONUMIA_HOST_TABLE_PREFIX`	Overrides the live WordPress table prefix Onumia treats as the host prefix.
`ONUMIA_WP_BIN`	Sets the WP-CLI binary or wrapper used by `wp` commands.
`ONUMIA_AGENT_CODE_REPOSITORY`	Absolute path to the live Agent Code repository.
`ONUMIA_AGENT_CODE_LIVE_BRANCH`	Live branch used for Agent Code promotion. Defaults to `main`.
`ONUMIA_MERQL_DSN`	PDO DSN for MerQL database promotion and merge tools.
`ONUMIA_MERQL_USER`	PDO username for the MerQL connection.
`ONUMIA_MERQL_PASSWORD`	PDO password for the MerQL connection.
`ONUMIA_UI_APP_DEV_SERVER`	Vite dev server URL for the Onumia admin app.
`ONUMIA_UI_APP_DEV_SERVER_AVAILABLE`	Enables dev server loading when set to `1`, `true`, or `yes`.

Public Filters

Everything a constant can configure, and a good deal more, is also exposed as a documented onumia/* filter. Filters are the preferred extension point when configuration is computed at runtime or provided by deployment tooling, because they let you derive a value rather than hard-code it. The table below is the canonical list of stable filters; the sections that follow group them by purpose and show how to use each one. Every filter validates its result, so returning an empty or malformed value leaves Onumia on its previous default rather than breaking.

Hook	Category	Summary
`onumia/access/role_capabilities`	Access	Filters effective Onumia role capability mappings.
`onumia/admin/menu_location`	Admin	Filters where Onumia appears in the WordPress admin menu.
`onumia/admin/app_entrypoint`	Admin	Filters the Vite entrypoint used for the Onumia admin app.
`onumia/admin/app_asset_directory`	Admin	Filters the built asset directory used for the Onumia admin app.
`onumia/agent_code/repository_path`	Agent Code	Filters the canonical Onumia Agent Code repository path.
`onumia/agent_code/live_branch`	Agent Code	Filters the live branch used for Onumia Agent Code promotion.
`onumia/data/merql_pdo`	Data	Filters the PDO connection used for MerQL database promotion.
`onumia/data/merql_capture_snapshot`	Data	Filters whether an integration captured a MerQL snapshot itself.
`onumia/data/merql_snapshot_dir`	Data	Filters the directory used for MerQL database snapshots.
`onumia/data/merql_tables`	Data	Filters the database tables included in MerQL promotion snapshots.
`onumia/database/local_clone_max_bytes`	Database	Filters the maximum copied database payload allowed for local clones.
`onumia/database/allow_unknown_size_local_clone`	Database	Filters whether local clones may proceed when database size is unknown.
`onumia/database/size_table_exclusions`	Database	Filters database tables excluded from local clone size and cloning.
`onumia/database/schema_only_table_patterns`	Database	Filters table-name patterns copied as schema-only local clone tables.
`onumia/database/schema_only_tables`	Database	Filters explicit full table names copied as schema-only local clone tables.
`onumia/database/redacted_columns`	Database	Filters column names whose source content is redacted during local clones.
`onumia/runtime/headers_sent`	Runtime	Filters whether Onumia should treat HTTP headers as already sent.
`onumia/sandbox/base_dir`	Sandbox	Filters the base directory used for Onumia sandbox files.
`onumia/wp/bin`	WordPress	Filters the wp-cli binary used by Onumia’s native WordPress command.

WordPress And Runtime

Use onumia/wp/bin when Onumia should dispatch WP-CLI through a specific binary or wrapper instead of relying on wp being on the process path. The runtime filter onumia/runtime/headers_sent exists for host-specific preview cookie and redirect behavior, and for tests that need to force header handling into a known state; returning true stops Onumia from setting preview cookies or issuing preview redirects for that request.

add_filter('onumia/wp/bin', fn (string $default): string => '/usr/local/bin/wp');
add_filter('onumia/runtime/headers_sent', fn (bool $sent): bool => $sent);

Sandbox Location And Lifecycle

The sandbox base directory determines where Onumia keeps sandbox files, logs, temporary state, and Agent Code checkouts. Point it somewhere persistent and writable when the default content or system temporary directory is not appropriate for your host. The lifecycle filters mirror the admin sandbox defaults, which is useful when you would rather pin those values in code than in the database.

add_filter('onumia/sandbox/base_dir', fn (string $dir): string => '/srv/site/onumia-sandboxes');
add_filter('onumia/sandbox/default_ttl_seconds', fn (int $seconds): int => 7200);
add_filter('onumia/sandbox/max_active_per_user', fn (int $count): int => 25);
add_filter('onumia/sandbox/inactive_retention_days', fn (int $days): int => 14);

Access

The access filter supplies role capabilities from code in addition to whatever is stored in the control table. This is the right hook when capability policy is owned by a deployment or governed centrally rather than edited per site. Onumia normalizes the returned map before any policy check, so you can safely merge into the existing values.

add_filter('onumia/access/role_capabilities', function (array $capabilities): array {
    $capabilities['editor'] = array_values(array_unique([
        ...($capabilities['editor'] ?? []),
        'execute_eval',
    ]));

    return $capabilities;
});

Agent Code

When the live Agent Code repository path or branch comes from deployment configuration rather than constants, set them through filters. Onumia validates the branch name after the filter runs and falls back to main for anything unsafe or empty.

add_filter('onumia/agent_code/repository_path', fn (?string $path): string => '/srv/repos/onumia-agent-code');
add_filter('onumia/agent_code/live_branch', fn (string $branch): string => 'main');

MerQL Database Merge

MerQL is the engine behind structured database promotion. These filters let you supply the connection, the snapshot directory, and the exact set of tables that participate in a merge, which is how you keep promotion snapshots focused on the content that matters.

add_filter('onumia/data/merql_pdo', fn (?PDO $pdo): PDO => $customPdo);
add_filter('onumia/data/merql_snapshot_dir', fn (string $dir): string => '/srv/site/onumia-merql-snapshots');
add_filter('onumia/data/merql_tables', fn (?array $tables): array => ['wp_posts', 'wp_postmeta', 'wp_options']);

If your integration captures snapshots through its own mechanism, the capture filter lets you signal that the named snapshot already exists. Return true only after you have successfully captured the snapshot named by $name; returning false lets Onumia fall back to its own table snapshot.

add_filter(
    'onumia/data/merql_capture_snapshot',
    function (bool $captured, string $name, string $role, ?object $sandbox): bool {
        return $captured;
    },
    10,
    4
);

For custom tables that need merge identity rules of their own, the identity rules filter accepts a map keyed by canonical table name, each value using the MerQL identity shape of a type and the columns that establish a row’s identity.

add_filter('onumia/data/merql_identity_rules', function (array $rules): array {
    $rules['wp_custom_table'] = [
        'type' => 'natural',
        'columns' => ['external_id'],
    ];

    return $rules;
});

Local Clone Policy

Local cloning is governed by a size budget. By default Onumia caps the copied row payload at 250 MB and refuses to clone when it cannot estimate the size at all. The clone filters let you raise or lower that budget, decide whether unknown-size clones may proceed, and exclude tables from cloning entirely. The size budget is measured against the row data Onumia will actually copy, so schema-only tables do not count against it.

add_filter('onumia/database/local_clone_max_bytes', fn (int $bytes): int => 250 * 1024 * 1024);
add_filter('onumia/database/allow_unknown_size_local_clone', fn (bool $allowed): bool => false);
add_filter('onumia/database/size_table_exclusions', fn (array $tables): array => $tables);

To keep clones lean without losing schema, mark noisy tables as schema-only so their structure is copied but their rows are not, and redact specific columns so rows still exist while their sensitive or bulky contents are dropped. Schema-only tables can be matched by pattern against the unprefixed name or named explicitly, and redacted columns are matched case-insensitively by exact column name.

add_filter('onumia/database/schema_only_table_patterns', function (array $patterns): array {
    $patterns[] = '/(^|_)sessions?(_|$)/i';

    return $patterns;
});

add_filter('onumia/database/schema_only_tables', function (array $tables): array {
    $tables[] = 'wp_custom_logs';

    return $tables;
});

add_filter('onumia/database/redacted_columns', function (array $columns): array {
    $columns[] = 'payload';

    return $columns;
});

Admin Placement And UI Bundle

By default Onumia adds a top-level admin menu entry, but you can move it under Tools or Settings and set its position. Return a placement of top-level, tools, or settings together with an integer position.

add_filter('onumia/admin/menu_location', function (array $location): array {
    return [
        'placement' => 'tools',
        'position' => 80,
    ];
});

The remaining two admin filters control which built front-end bundle the admin app loads. They exist mainly for product packaging and Pro bundle selection, and most sites never need to touch them.

add_filter('onumia/admin/app_entrypoint', fn (string $entry): string => $entry);
add_filter('onumia/admin/app_asset_directory', fn (string $dir): string => $dir);