Runtime configuration (Systemplane)

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
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

The running Matcher instance serves these endpoints directly. They do not sit under /v1. Use the paths above exactly as shown.

Permissions

Systemplane configuration and catalog routes use the same authentication as Matcher API routes. With authentication 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. With authentication disabled, all endpoints are accessible without restriction.

Apply behaviors

You can change only some configuration values 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.

The systemplane API does NOT register most bootstrap-only keys. You manage them 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 keys you adjust most often, organized by category. For a complete list, call GET /system/matcher.

Runtime-adjustable keys

You can change these keys without a Matcher restart:

swagger.enabled, swagger.host, and swagger.schemes are registered and visible in Systemplane, but they are not live controls. Matcher captures Swagger mounting and handler values 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 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 you can adjust them without a restart. See Multi-Tenant Mode for details.

Enabling multi-tenant mode itself (tenancy.multi_tenant_enabled / MULTI_TENANT_ENABLED) is bootstrap-only. Matcher reads it once at startup. A change to it requires a restart. The Systemplane API does not register it, and you cannot toggle it 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)

The systemplane API does not register these keys. 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 actually uses. It may differ from environment variables after previous PUT calls.

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 exception dispatch 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