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.Documentation Index
Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
Use this file to discover all available pages before exploring further.
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:admin RBAC permission.
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. |
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 |
|---|---|---|
app.env_name | ENV_NAME | Application environment name |
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.enabled | FETCHER_ENABLED | Enable or disable the Fetcher module |
fetcher.url | FETCHER_URL | Fetcher service URL |
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 |
telemetry.enabled | ENABLE_TELEMETRY | Enable OpenTelemetry |
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.| Key | Env variable | Description |
|---|---|---|
tenancy.multi_tenant_enabled | MULTI_TENANT_ENABLED | Enable multi-tenant infrastructure |
tenancy.multi_tenant_url | MULTI_TENANT_URL | Tenant Manager 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 |
|---|---|---|
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
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
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
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.