Runtime configuration (Systemplane)

Read and update Matcher’s runtime configuration through Systemplane’s key-value API — adjust rate limits, worker intervals, and the maximum tenant-pool count without restarting the service.

Systemplane lets you view and modify supported Matcher configuration without restarting the service. Application behavior varies by key: request-time settings may apply on the next request, while a configuration reload stops and restarts a running worker when its configuration changes.

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; a configuration reload reconciles the affected worker and restarts it when its running configuration changes
• Update the maximum number of tenant pools as traffic patterns change; PostgreSQL connections-per-pool settings require an environment change and restart
• 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 configuration and catalog routes are protected by the same authentication used by Matcher API routes. When authentication is enabled, these routes require the system-runtime-config:admin RBAC permission (resource system-runtime-config, action admin). GET /system/matcher/streaming/manifest is a separate route and requires streaming-manifest:read.

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	A configuration reload reconciles workers. If a running worker’s configuration changed, Matcher stops and restarts it.

Most bootstrap-only keys 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. The registered Swagger keys are an exception: they are visible in Systemplane but remain bootstrap-only (see the note below).

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:

swagger.enabled, swagger.host, and swagger.schemes are registered and visible in Systemplane, but they are not live controls. Swagger mounting and handler values are captured at bootstrap, so a runtime PUT does not change the live UI or specification behavior. Change their startup configuration and restart Matcher instead.

Key	Env variable	Description
server.body_limit_bytes	HTTP_BODY_LIMIT_BYTES	Maximum request-body size for buffered routes (positive and no greater than 128 MiB). Streaming uploads use ingestion.max_upload_bytes.
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
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	TTL basis for the distributed lock that serializes manual Fetcher discovery refreshes; the runtime lease is 2× this value
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	Toggle the archival worker created at boot. If archival was disabled at boot, Systemplane cannot create the 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, fatal)
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

Runtime application behavior varies by key, and worker changes can restart the affected worker. 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. A visible key can still be bootstrap-only when its documentation says so: the registered Swagger keys accept a runtime PUT but only take effect after a restart.

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.