Runtime configuration (Systemplane)

Systemplane lets you view and modify Matcher’s configuration at runtime — without restarting the service. In regulated financial environments, unplanned service downtime to apply configuration changes is a compliance risk and an operational disruption. Systemplane eliminates that: operational parameters can be adjusted while the service continues running, keeping reconciliation processes uninterrupted.

Why use Systemplane

In a traditional deployment, changing a configuration value means updating environment variables and restarting the service. Systemplane eliminates that downtime for many settings:

Adjust rate limits during traffic spikes without a redeploy — avoiding service disruption during peak transaction volumes
Tune worker intervals based on observed workload — optimizing reconciliation throughput without touching infrastructure
Update connection pool sizes as traffic patterns change
Inspect current runtime values to diagnose production issues without log diving

How it works

Systemplane provides a flat key-value management API. All configuration keys are in a single namespace under /system/matcher.

Endpoints

Endpoint	Method	What it does
`/system/matcher`	`GET`	List all keys and their current values
`/system/matcher/:key`	`GET`	Get a specific key’s current value
`/system/matcher/:key`	`PUT`	Update a specific key’s value

These endpoints are served directly by the running Matcher instance. They are not versioned under /v1 — use the paths above exactly as shown.

Permissions

Systemplane endpoints are protected by the same authentication used by all Matcher API routes. When authentication is enabled, all /system endpoints require the system-runtime-config:admin RBAC permission (resource system-runtime-config, action admin). When authentication is disabled, all endpoints are accessible without restriction.

Apply behaviors

Not every configuration value can be changed at runtime. Each key has an apply behavior that tells you when changes take effect:

Behavior	What happens
Bootstrap only	The value is read once at startup. You must restart the service for changes to take effect.
Live read	Changes take effect immediately on the next request.
Bundle rebuild	Changes trigger an internal state refresh. Takes effect within seconds.
Worker reconcile	Background workers pick up the new value on their next cycle.

Keys that are bootstrap-only are NOT registered in the systemplane API — they are managed exclusively through environment variables. This prevents a footgun where an admin PUT would appear to succeed but the running process would silently continue using the boot-time value.

Common configuration keys

Below are the most commonly adjusted keys, organized by category. For a complete list, call GET /system/matcher.

Runtime-adjustable keys

These keys can be changed without restarting Matcher:

Key	Env variable	Description
`server.body_limit_bytes`	`HTTP_BODY_LIMIT_BYTES`	Maximum HTTP request body size
`cors.allowed_origins`	`CORS_ALLOWED_ORIGINS`	Allowed CORS origins
`cors.allowed_methods`	`CORS_ALLOWED_METHODS`	Allowed CORS methods
`cors.allowed_headers`	`CORS_ALLOWED_HEADERS`	Allowed CORS headers
`swagger.enabled`	`SWAGGER_ENABLED`	Enable or disable Swagger UI
`swagger.host`	`SWAGGER_HOST`	Swagger host override
`swagger.schemes`	`SWAGGER_SCHEMES`	Swagger URL schemes
`rate_limit.enabled`	`RATE_LIMIT_ENABLED`	Enable or disable global rate limiting
`rate_limit.max`	`RATE_LIMIT_MAX`	Maximum requests per rate limit window
`rate_limit.expiry_sec`	`RATE_LIMIT_EXPIRY_SEC`	Rate limit window duration (seconds)
`rate_limit.export_max`	`EXPORT_RATE_LIMIT_MAX`	Export endpoint rate limit
`rate_limit.dispatch_max`	`DISPATCH_RATE_LIMIT_MAX`	Dispatch endpoint rate limit
`rate_limit.admin_max`	`ADMIN_RATE_LIMIT_MAX`	Admin plane (`/system`) rate limit
`idempotency.retry_window_sec`	`IDEMPOTENCY_RETRY_WINDOW_SEC`	Window for retrying failed idempotent requests
`idempotency.success_ttl_hours`	`IDEMPOTENCY_SUCCESS_TTL_HOURS`	How long completed idempotency keys are cached
`fetcher.discovery_interval_sec`	`FETCHER_DISCOVERY_INTERVAL_SEC`	How often Matcher polls Fetcher for new data sources
`export_worker.enabled`	`EXPORT_WORKER_ENABLED`	Enable or disable the export worker
`export_worker.poll_interval_sec`	`EXPORT_WORKER_POLL_INTERVAL_SEC`	How often the export worker checks for new jobs
`cleanup_worker.enabled`	`CLEANUP_WORKER_ENABLED`	Enable or disable the cleanup worker
`cleanup_worker.interval_sec`	`CLEANUP_WORKER_INTERVAL_SEC`	Cleanup worker interval
`scheduler.interval_sec`	`SCHEDULER_INTERVAL_SEC`	Scheduler polling interval
`archival.enabled`	`ARCHIVAL_WORKER_ENABLED`	Enable or disable the archival worker
`webhook.timeout_sec`	`WEBHOOK_TIMEOUT_SEC`	Timeout for webhook/callback dispatch
`callback_rate_limit.per_minute`	`CALLBACK_RATE_LIMIT_PER_MIN`	Maximum callbacks per external system per minute
`deduplication.ttl_sec`	`DEDUPE_TTL_SEC`	Deduplication TTL in seconds

Multi-tenant keys (runtime adjustable)

These keys control multi-tenant behavior and can be adjusted without restart. See Multi-Tenant Mode for details.

Enabling multi-tenant mode itself (tenancy.multi_tenant_enabled / MULTI_TENANT_ENABLED) is bootstrap-only — it is read once at startup and requires a restart. It is not registered in the Systemplane API and cannot be toggled at runtime. See the bootstrap-only table below.

Key	Env variable	Description
`tenancy.multi_tenant_url`	`MULTI_TENANT_URL`	Multi-tenancy service URL
`tenancy.multi_tenant_max_tenant_pools`	`MULTI_TENANT_MAX_TENANT_POOLS`	Maximum concurrent tenant pools
`tenancy.multi_tenant_idle_timeout_sec`	`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Idle timeout for tenant pool eviction
`tenancy.multi_tenant_cache_ttl_sec`	`MULTI_TENANT_CACHE_TTL_SEC`	Tenant config cache TTL

Bootstrap-only keys (require restart)

These keys are not registered in the systemplane API. Change them via environment variables and restart:

Key	Env variable	Description
`tenancy.multi_tenant_enabled`	`MULTI_TENANT_ENABLED`	Enable multi-tenant infrastructure. Read once at startup; requires a restart to change.
`app.env_name`	`ENV_NAME`	Application environment name
`telemetry.enabled`	`ENABLE_TELEMETRY`	Enable OpenTelemetry
`app.log_level`	`LOG_LEVEL`	Application log level (debug, info, warn, error)
`server.address`	`SERVER_ADDRESS`	HTTP server listen address
`postgres.primary_host`	`POSTGRES_HOST`	Primary database host
`postgres.primary_port`	`POSTGRES_PORT`	Primary database port
`postgres.primary_db`	`POSTGRES_DB`	Primary database name
`redis.host`	`REDIS_HOST`	Redis host
`rabbitmq.host`	`RABBITMQ_HOST`	RabbitMQ host
`auth.enabled`	`PLUGIN_AUTH_ENABLED`	Enable authentication middleware
`auth.host`	`PLUGIN_AUTH_ADDRESS`	Auth service address

Best practices

Inspect current values before changing

Call GET /system/matcher to see all current runtime values before making any changes. This confirms what the process is actually using, which may differ from environment variables if previous PUT calls were made.

Test changes in staging first

Even though runtime changes don’t require a restart, they take effect immediately. Test in a staging environment before applying to production.

Restart for bootstrap-only keys

If a key is not visible in GET /system/matcher, it is bootstrap-only. Update the environment variable and restart the service — there is no runtime path for those values.

Next steps

Multi-tenant mode

Enable and configure tenant isolation.

Exception routing

Configure how exceptions are dispatched to external systems.

Match rules

Configure transaction matching rules.

Security

Authentication, authorization, and data protection.

Overview

Guides

Matcher UI

MCP Server

Operations

Runtime configuration (Systemplane)

Why use Systemplane

How it works

Endpoints

Permissions

Apply behaviors

Common configuration keys

Runtime-adjustable keys

Multi-tenant keys (runtime adjustable)

Bootstrap-only keys (require restart)

Best practices

Next steps

Multi-tenant mode

Exception routing

Match rules

Security

​Why use Systemplane

​How it works

​Endpoints

​Permissions

​Apply behaviors

​Common configuration keys

​Runtime-adjustable keys

​Multi-tenant keys (runtime adjustable)

​Bootstrap-only keys (require restart)

​Best practices

​Next steps

Multi-tenant mode

Exception routing

Match rules

Security

Why use Systemplane

How it works

Endpoints

Permissions

Apply behaviors

Common configuration keys

Runtime-adjustable keys

Multi-tenant keys (runtime adjustable)

Bootstrap-only keys (require restart)

Best practices

Next steps