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

# Runtime configuration (Systemplane)

> View and modify Matcher's operational configuration at runtime through Systemplane, without restarting the service.

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          |

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

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

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                                          |
| --------------------------------- | --------------------------------- | ---------------------------------------------------- |
| `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](/en/matcher/configuration/matcher-multi-tenant) 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

***

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Multi-tenant mode" icon="building" href="/en/matcher/configuration/matcher-multi-tenant">
    Enable and configure tenant isolation.
  </Card>

  <Card title="Exception routing" icon="route" href="/en/matcher/configuration/matcher-exception-routing">
    Configure how exceptions are dispatched to external systems.
  </Card>

  <Card title="Match rules" icon="code-compare" href="/en/matcher/configuration/matcher-match-rules">
    Configure transaction matching rules.
  </Card>

  <Card title="Security" icon="shield" href="/en/matcher/reference/matcher-security">
    Authentication, authorization, and data protection.
  </Card>
</CardGroup>