Skip to content
Forgeplane Docs

Forgeplane system settings

System settings are stored in the coordinator database and can be changed at runtime from the admin UI (/admin/settings). They are the runtime-tunable layer for coordinator behavior such as concurrency, timeouts, approvals, retention, notifications, and event-bus maintenance.

Most values are normalized on load: invalid or out-of-range inputs are clamped or replaced with safe defaults. Audit retention is stricter: unsupported values stop cleanup and appear as unhealthy instead of being silently replaced. Updating a system setting does not require restarting the coordinator process.

Apply a setting

Section titled “Apply a setting”
  1. Confirm that the key belongs to the runtime system-settings layer rather than process startup configuration.
  2. Check the default and allowed range or values in the table below.
  3. Change the value from /admin/settings with the required administrator permission.
  4. Recheck the effective behavior and audit record after the update.

Runtime system settings take precedence over process startup defaults. Settings that are not present keep their built-in defaults.

Core scheduler and worker limits

Section titled “Core scheduler and worker limits”
Key Default Notes
queue_max_concurrent_runs 10 Global run concurrency cap
job_timeout_default_minutes 30 Default run timeout; cannot exceed job_timeout_max_minutes
job_timeout_max_minutes 120 Hard timeout ceiling
worker_heartbeat_interval_seconds 30 Worker heartbeat interval in runtime settings
worker_offline_threshold_seconds 120 Worker considered offline after this gap
worker_max_concurrent_jobs 1 Per-worker concurrency ceiling; a worker is never scheduled beyond the lower capacity it reports (currently one)
assignment_lease_duration_seconds 30 Assignment lease before reaper reclaim
workspace_size_limit_mb 2048 Workspace disk limit per run
artifact_size_limit_mb 512 Artifact size limit per run
assembly_caps_json empty JSON limits defining assembly node sizes and concurrency

Run approval maintenance

Section titled “Run approval maintenance”
Key Default Constraints
run_approval_pending_timeout_minutes 1440 5..10080
run_approval_maintenance_interval_seconds 30 5..600
run_approval_maintenance_batch_size 200 1..2000
run_approval_maintenance_cycle_cap 1000 1..10000; always normalized to >= batch_size
run_approval_self_approval_default_enabled false Boolean (true/false, 1/0, yes/no, on/off)

Secret governance and approval maintenance

Section titled “Secret governance and approval maintenance”
Key Default Constraints / allowed values
secret_approval_self_approval_default_enabled false Boolean
secret_approval_pending_timeout_minutes 1440 5..10080
secret_approval_maintenance_interval_seconds 60 5..600
secret_approval_maintenance_batch_size 200 1..2000
secret_approval_maintenance_cycle_cap 1000 1..10000; normalized to >= batch_size
secret_floating_behavior_mode policy_controlled policy_controlled, disabled
secret_floating_drift_default_reaction informational informational, block
secret_floating_require_ack false Boolean
secret_approval_independent_min_classification high low, medium, high, critical
secret_external_health_check_interval_seconds 300 Positive integer seconds
secret_builtin_health_check_interval_seconds 86400 Positive integer seconds

Audit, logging, reaper, and webhook controls

Section titled “Audit, logging, reaper, and webhook controls”
Key Default Notes
audit_retention_days 90 Allowed: 30, 90, 365. Applies to all actions and outcomes, including authentication and authorization denials. Reloaded by daily cleanup; shortening applies to existing eligible history on the next run.
reaper_check_interval_seconds 60 Coordinator reaper sweep interval
reaper_max_retries 3 Max recovery retries before terminal failure
audit_export_max_items 5000 Max audit rows per export
audit_export_max_bytes_mb 32 Max serialized export size in MiB
audit_export_max_concurrent 2 Concurrent export cap
audit_event_payload_max_bytes_mb 4 Max payload size per audit event in MiB
http_success_log_sample_rate 0.1 Clamped to 0.0..1.0
webhook_allow_hosts empty Comma-separated hostname allowlist override
webhook_allow_private_cidrs empty Comma-separated CIDR allowlist override

The admin form warns before an audit-retention reduction is saved. The setting mutation and its audit evidence commit together. Audit cleanup removes expired history and its activity receipts in the same transaction. Non-activity receipts and execution recovery state remain. See Audit logging for receipt lifecycle details. After a change, check the read-only Runtime Health section for the audit status. Recording, retention, unresolved-outcome, and projection-retry failures include bounded remediation without exposing audit content or resource identifiers.

Usage and notification retention

Section titled “Usage and notification retention”
Key Default Notes
usage_retention_days 90 Database retention days for usage telemetry data.
usage_compute_unit_weights_json {} JSON map of milli-weight compute multipliers per tool_type:operation (e.g. {"tofu:apply": 1500}). 1000 = 1.0x.
notification_retention_days 30 Database retention days for standard notifications.
notification_protected_retention_days 180 Retention days for protected or starred notifications.
notification_retention_interval_seconds 300 Frequency of database notification cleanup sweeps.
notification_retention_batch_size 500 Max notifications deleted per cleanup batch (1..2000).

Distributed Event Bus Outbox

Section titled “Distributed Event Bus Outbox”

Coordinator event bus JetStream outbox publishing and retention settings.

Key Default Notes
event_bus_outbox_enabled true Enables transactional outbox event publishing to JetStream.
event_bus_outbox_poll_interval_seconds 2 Polling interval for publishing queued outbox messages.
event_bus_outbox_batch_size 64 Number of events published in a single NATS batch.
event_bus_claim_timeout_seconds 45 Expiry lease for locking events under processing.
event_bus_max_retries 3 Maximum attempts to deliver an event to JetStream.
event_bus_retention_days 7 Retention period for local database event bus log.
event_bus_retention_interval_seconds 300 Database cleanup sweep interval for aged event bus logs.
event_bus_retention_batch_size 500 Max event bus rows pruned per sweep batch.

Assembly capabilities configuration

Section titled “Assembly capabilities configuration”

The assembly_caps_json setting controls the maximum number of nodes and maximum parallel steps/nodes allowed in an assembly deployment. This configuration supports hierarchical overrides at the Organization and Team levels.

JSON schema

Section titled “JSON schema”
{
  "max_nodes": 100,
  "max_parallel_nodes": 10,
  "organizations": {
    "organization-uuid-1": {
      "max_nodes": 50,
      "max_parallel_nodes": 5
    }
  },
  "teams": {
    "team-uuid-1": {
      "max_nodes": 20,
      "max_parallel_nodes": 2
    }
  }
}

Hierarchy resolution

Section titled “Hierarchy resolution”

When evaluating caps for a run’s environment:

  1. Start with the root global limits (max_nodes and max_parallel_nodes).
  2. Merge with limits defined for the parent Organization, if present.
  3. Merge with limits defined for the parent Team, if present.

Configuration boundary

Section titled “Configuration boundary”

Environment variables provide process startup defaults. Use the configuration reference for environment names, Helm precedence, secrets, and deployment-level controls.