---
title: Configuration Options
description: DurableStack configuration keys, meanings, and defaults for v1.0.
order: 79
---

# Configuration Options

DurableStack configuration lives under the `DurableStack` section.

Use `ConnectionStrings` only if your app prefers storing database connection strings there, then copy/bind those values into `DurableStack:Postgres:ConnectionString` (or the provider equivalent) in your startup logic.

## Top-level options (`DurableStack:*`)

- `StorageProvider`: backing store selection (`InMemory`, `Postgres`, `SqlServer`, `Sqlite`, `MySql`). Default: `InMemory`.
- `WorkerName`: unique worker identity used for leasing and diagnostics. Default: `"{HOSTNAME-or-machine}-{processId}"`.
- `DatabaseTablePrefix`: optional prefix for durable database objects. Default: `null`.
- `PollIntervalSeconds`: worker polling cadence in seconds (`<= 0` resets to default). Default: `5`.
- `PollJitterEnabled`: enables poll jitter for claim loops. Default: `true`.
- `PollJitterRatio`: jitter ratio used for poll timing when poll jitter is enabled. Default: `0.2`.
- `BatchSize`: max runs leased per poll cycle. Default: `50`.
- `LeaseDurationSeconds`: lease TTL in seconds (`<= 0` resets to default). Default: `30`.
- `RetryDelay`: base retry delay (`TimeSpan` format in config binding). Default: `00:00:05`.
- `RetryMaxDelay`: maximum retry backoff (`TimeSpan` format in config binding). Default: `01:00:00`.
- `RetryJitterEnabled`: enables retry jitter. Default: `false`.
- `RetryJitterRatio`: jitter ratio used when jitter is enabled. Default: `0.2`.
- `JobActivation`: job activation mode (`ScopedPerExecution`, `RootProvider`). Default: `ScopedPerExecution`.

## Provider connection options

Set the matching section for the selected `StorageProvider`:

- `Postgres:ConnectionString` (default: `""`)
- `SqlServer:ConnectionString` (default: `""`)
- `Sqlite:ConnectionString` (default: `""`)
- `MySql:ConnectionString` (default: `""`)

If a durable provider is selected and the corresponding connection string is empty, startup throws.

## Recurring options (`DurableStack:Recurring:*`)

- `CatchUpPolicy`: missed-slot behavior (`SkipMissed`, `CatchUp`). Default: `SkipMissed`.

### Registration sync (`DurableStack:Recurring:RegistrationSync:*`)

- `ExistingJobBehavior`: when recurring definitions already exist in storage (`KeepDatabase`, `UpdateFromCode`). Default: `KeepDatabase`.
- `OrphanedJobBehavior`: when a DB recurring definition no longer exists in code (`Disable`, `Ignore`). Default: `Disable`.

## Retention options (`DurableStack:Retention:*`)

- `Enabled`: enables terminal-run cleanup. Default: `true`.
- `RunRetentionSeconds`: run retention window in seconds. Default: `null` (effective default is `3600` for in-memory, `86400` for durable stores).
- `SweepIntervalSeconds`: cleanup sweep cadence in seconds (`<= 0` resets to default). Default: `300`.
- `DeleteBatchSize`: max rows deleted per sweep batch (`<= 0` resets to default). Default: `1000`.

## Job registration options (`DurableStack:JobRegistration:*`)

- `AutoDiscoverJobsFromAssembly`: auto-register public `IDurableJob`/`IDurableJob<TArgs>` classes from the app assembly. Default: `true`.

## Eventing options (`DurableStack:Eventing:*`)

- `TenantId`: tenant ID for hosted ingestion auth. Default: `null`.
- `ClientSecret`: client secret for hosted ingestion auth. Default: `null`.
- `IngestionApiBaseUrl`: ingestion API base URL. Default: `https://api.durablestack.com`.
- `IngestionPath`: ingestion API path. Default: `/v1/events/batch`.
- `IngestionMaxBatchSize`: max events per post. Default: `100`.
- `IngestionMaxRequestBodyBytes`: max request body size. Default: `1000000`.
- `IngestionMaxRetryAttempts`: max retries for failed ingestion posts. Default: `5`.
- `IngestionFlushIntervalSeconds`: flush cadence in seconds (`<= 0` resets to default). Default: `5`.
- `IncludeErrorDetail`: includes captured error details in event payloads. Default: `false`.
- `MaxErrorDetailLength`: max captured error-detail length (`<= 0` resets to default). Default: `4096`.

Event ingestion is automatically enabled when both `TenantId` and `ClientSecret` are set.
When enabled, the runtime includes runtime information in posted ingestion data.

## Example

```json
{
  "DurableStack": {
    "StorageProvider": "Postgres",
    "WorkerName": "orders-api-1",
    "DatabaseTablePrefix": "prod_",
    "PollIntervalSeconds": 5,
    "BatchSize": 50,
    "LeaseDurationSeconds": 30,
    "RetryDelay": "00:00:05",
    "RetryMaxDelay": "01:00:00",
    "PollJitterEnabled": true,
    "PollJitterRatio": 0.2,
    "RetryJitterEnabled": false,
    "RetryJitterRatio": 0.2,
    "JobActivation": "ScopedPerExecution",
    "Postgres": {
      "ConnectionString": "Host=localhost;Port=5432;Database=durable_stack;Username=postgres;Password=postgres"
    },
    "Recurring": {
      "CatchUpPolicy": "SkipMissed",
      "RegistrationSync": {
        "ExistingJobBehavior": "KeepDatabase",
        "OrphanedJobBehavior": "Disable"
      }
    },
    "Retention": {
      "Enabled": true,
      "RunRetentionSeconds": 86400,
      "SweepIntervalSeconds": 300,
      "DeleteBatchSize": 1000
    },
    "JobRegistration": {
      "AutoDiscoverJobsFromAssembly": true
    },
    "Eventing": {
      "TenantId": "tenant_...",
      "ClientSecret": "secret_...",
      "IngestionApiBaseUrl": "https://api.durablestack.com",
      "IngestionPath": "/v1/events/batch",
      "IngestionMaxBatchSize": 100,
      "IngestionMaxRequestBodyBytes": 1000000,
      "IngestionMaxRetryAttempts": 5,
      "IngestionFlushIntervalSeconds": 5,
      "IncludeErrorDetail": false,
      "MaxErrorDetailLength": 4096
    }
  }
}
```