Configuration reference

Most users should configure Perseval in Settings. TOML and environment variables exist for reproducible local setups, isolated dogfood workspaces, and MCP clients.

1. Perseval starts with centralized defaults.
2. It loads PERSEVAL_CONFIG when set; otherwise it loads the platform configuration file.
3. Environment overrides replace the corresponding TOML values.
4. Settings saves to the effective configuration path, but cannot rewrite an environment variable owned by the parent process.

The configuration directory is private and the TOML file is written atomically with user-only permissions on Unix. Settings → Workspace shows the effective configuration and workspace paths.

Runtime-owned changes such as workspace, receiver, storage policy, analysis, and MCP bounds take effect after restart. Settings marks pending restart state. Appearance/workbench preferences are stored separately and can update immediately.

Boolean environment values accept 1, true, yes, or on, and 0, false, no, or off, case-insensitively.

PERSEVAL_TRACE_FILE is a read-only development fixture mode. It cannot be combined with live OTLP and is not the normal persisted GUI path.

Perseval does not automatically load .env files. Arrange the launch environment explicitly if you use environment variables.

All fields are versioned and unknown fields are rejected.

schema_version = 1
workspace_id = "default"
workspace_dir = "<platform application-data>/Perseval/workspaces/default"
reviewer_ref = "local-human"

[otlp]
enabled = false
bind_addr = "127.0.0.1:4318"
source_id = "otlp-local"
max_wire_bytes = 16777216
max_decoded_bytes = 67108864
max_spans_per_request = 100000
max_attributes_per_span = 1024
retry_after_seconds = 1

[stream]
queue_batches = 64
queue_bytes = 268435456
microbatch_spans = 2048
microbatch_bytes = 8388608
microbatch_wait_ms = 25
projection_retry_page = 64
projection_retry_initial_ms = 100
projection_retry_max_ms = 5000
topology_chunk_rows = 2048
pipeline_metrics_flush_ms = 1000
delta_history = 4096
subscriber_capacity = 256
ui_max_deltas_per_frame = 512

[lifecycle]
idle_ms = 30000
finalization_grace_ms = 5000
sweep_ms = 1000
shutdown_drain_ms = 5000

[analysis]
feature_similarity_enabled = false
cohort_rebuild_debounce_ms = 1000
cohort_job_queue = 1024
cohort_quality_sample_size = 512
cohort_rebuild_new_percent = 10
cohort_rebuild_new_cases = 250
cohort_rebuild_novelty_percent = 25
cohort_model_history = 3
cohort_feature_cache_entries = 20000
cohort_maximum_cases = 20000
embedding_dimensions = 256
maximum_clusters = 8
minimum_findings = 3
novelty_distance_milli = 350

[analysis.openai]
enabled = false
embeddings_enabled = false
cluster_labels_enabled = false
semantic_judge_enabled = false
embedding_model = "text-embedding-3-small"
chat_model = "gpt-5-mini"
embedding_batch_size = 128
minimum_failure_confidence_milli = 800
emit_abstentions = true

[query]
max_run_page = 200
max_span_page = 500
cached_pages = 8
blob_preview_bytes = 65536
comparison_max_input_steps = 100000
comparison_max_rows = 1024
comparison_lookahead = 32

[blobs]
inline_attribute_bytes = 4096
allow_larger_local_reveal = false
maximum_local_reveal_bytes = 16777216

[mcp]
read_enabled = true
compute_enabled = false
write_enabled = false
payload_reveal_enabled = false
default_page_size = 50
maximum_page_size = 200
maximum_evidence_spans = 128
maximum_reveal_bytes = 4096
maximum_response_bytes = 2097152
cursor_ttl_seconds = 900
job_poll_interval_ms = 1000

• schema_version: must be 1.
• workspace_id: non-empty local workspace identity.
• workspace_dir: control, analytics, blobs, and workbench state root.
• reviewer_ref: durable human reviewer reference attached to decisions.

Controls the embedded loopback receiver and hard request bounds. source_id identifies this ingestion source. Non-loopback addresses are rejected. See OTLP ingestion.

Controls pre-durable queue budgets, projection microbatches, retry, topology chunks, metrics flush, retained delta history, subscriber capacity, and per-frame UI work. These values are advanced safety bounds. Increasing them can increase memory use and does not make the UI unbounded.

projection_retry_initial_ms must not exceed projection_retry_max_ms; all capacities and intervals must be greater than zero.

Controls idle-to-quiescent time, finalization grace, lifecycle sweep frequency, and coordinated shutdown drain.

Controls optional local feature similarity and bounded model rebuilds. Percentages must be 0..100; novelty_distance_milli must be at most 2000; maximum cases must be at least minimum findings.

The legacy TOML key semantic_clustering_enabled is read as an alias, but new files serialize feature_similarity_enabled.

The master opt-in must be true before any hosted subfeature. OpenAI embeddings also require local feature similarity. Cluster labels require OpenAI embeddings. Model names cannot be empty. minimum_failure_confidence_milli is 0..1000; OpenAI embedding dimensions cannot exceed 3072.

Controls service-side page ceilings, retained pages, bounded reveal, and comparison input/output limits. Callers cannot bypass these maxima by requesting a larger page.

Controls unknown-attribute externalization and local explicit reveal. Known prompt/message/reasoning/code/tool-payload keys externalize regardless of the inline threshold. allow_larger_local_reveal=false blocks the larger reveal action.

Controls read permission and bounded response/cursor behavior. Current protocol ceilings are 200 rows, 128 evidence spans, and 65,536 reveal bytes. Compute, write, and reveal capability classes are intentionally unavailable even if a stale environment tries to enable them.

These affect local development or packaging, not installed end-user behavior:

Contributor commands belong in the repository README, not in end-user installation or onboarding.