Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration Reference

Torvyn uses TOML for all configuration, consistent with the Rust ecosystem convention established by Cargo.toml. Configuration lives in Torvyn.toml at the project root.

Configuration Merging Rules

Configuration values are resolved through a layered precedence model (highest precedence first):

  1. CLI flags — --config key=value on torvyn run and other commands.
  2. Environment variables — TORVYN_ prefix + uppercase path (e.g., TORVYN_RUNTIME_WORKER_THREADS).
  3. Project manifest — Torvyn.toml in the project root.
  4. Global user config — ~/.config/torvyn/config.toml.
  5. Built-in defaults — Compiled into the binary.

Component Manifest (Torvyn.toml — per component)

[torvyn] — Project Metadata

FieldTypeRequiredDefaultDescription
namestringYes—Project name. Must be a valid identifier (lowercase, hyphens allowed).
versionstringYes—Project version (semantic versioning, e.g., "0.1.0").
contract_versionstringYes—Torvyn contract version this project targets (e.g., "0.1.0").
descriptionstringNo""Human-readable project description.
authorslist of stringsNo[]Author names and emails (e.g., ["Alice <alice@example.com>"]).
licensestringNo""SPDX license identifier (e.g., "Apache-2.0").
repositorystringNo""Source repository URL.

[capabilities.required] — Required Capabilities

Key-value pairs where keys are capability identifiers and values are booleans. Components will not link if required capabilities are not granted.

[capabilities.required]
wasi-filesystem-read = true
wasi-clocks = true

[capabilities.optional] — Optional Capabilities

Capabilities that enhance functionality but are not required. The component must handle their absence gracefully.

[capabilities.torvyn] — Torvyn-Specific Resource Requirements

FieldTypeDefaultDescription
max-buffer-sizestring"16MiB"Maximum single buffer size this component needs.
max-memorystring"64MiB"Maximum Wasm linear memory this component needs.
buffer-pool-accessstring"default"Named buffer pool to use.

Pipeline Manifest (Torvyn.toml — pipeline project)

[[component]] — Component Declarations

FieldTypeRequiredDefaultDescription
namestringYes—Component name within this project.
pathstringYes—Path to component source root (relative to project root).
languagestringNo"rust"Implementation language. Values: rust, go, python, zig.
build_commandstringNoauto-detectedCustom build command override.

[flow.<NAME>] — Flow Definition

FieldTypeRequiredDefaultDescription
descriptionstringNo""Human-readable flow description.

[flow.<NAME>.nodes.<NODE>] — Component Nodes

FieldTypeRequiredDefaultDescription
componentstringYes—Path to compiled .wasm file or registry reference.
interfacestringYes—Torvyn interface this component implements (e.g., torvyn:streaming/processor).
configstringNo""Configuration string passed to lifecycle.init(). JSON recommended.

[[flow.<NAME>.edges]] — Stream Connections

FieldTypeRequiredDescription
from.nodestringYesUpstream node name.
from.portstringYesOutput port name (usually "output").
to.nodestringYesDownstream node name.
to.portstringYesInput port name (usually "input").

[runtime] — Runtime Configuration

FieldTypeDefaultDescription
worker_threadsintegerCPU countTokio worker thread count.
max_memory_per_componentstring"64MiB"Wasm linear memory limit per component instance.
fuel_per_invocationinteger1_000_000Wasmtime fuel budget per component call. 0 = unlimited.
component_init_timeout_msinteger5000Timeout for lifecycle.init() calls.
component_teardown_timeout_msinteger2000Timeout for lifecycle.teardown() calls.

[runtime.backpressure] — Global Backpressure Defaults

FieldTypeDefaultDescription
default_queue_depthinteger64Default bounded queue capacity per stream.
backpressure_policystring"block"Default policy. Values: block, drop-oldest, drop-newest, error.
low_watermark_ratiofloat0.5Queue depth ratio at which backpressure deactivates.

[runtime.pools] — Buffer Pool Configuration

FieldTypeDefaultDescription
small_pool_sizeinteger4096Number of 256-byte buffers pre-allocated.
medium_pool_sizeinteger1024Number of 4 KiB buffers pre-allocated.
large_pool_sizeinteger256Number of 64 KiB buffers pre-allocated.
huge_pool_sizeinteger32Maximum cached 1 MiB buffers (on-demand).
exhaustion_policystring"fallback-alloc"Policy when pool is empty. Values: fallback-alloc, error.

[observability] — Observability Configuration

FieldTypeDefaultDescription
levelstring"production"Observability level. Values: off, production, diagnostic.
tracing_enabledbooleantrueEnable trace collection.
tracing_exporterstring"stdout"Trace export target. Values: otlp-grpc, otlp-http, stdout, file, none.
tracing_endpointstring""OTLP endpoint URL (for otlp-grpc and otlp-http).
sample_ratefloat0.01Head-based trace sampling rate (0.0–1.0).
error_promotebooleantruePromote errored flows to full tracing.
latency_promote_threshold_msinteger10Promote flows exceeding this latency.
metrics_enabledbooleantrueEnable metrics collection.
prometheus_enabledbooleantrueServe /metrics on inspection API.
otlp_metrics_enabledbooleanfalsePush metrics via OTLP.
otlp_metrics_interval_sinteger15OTLP metrics push interval.
ring_buffer_capacityinteger64Per-flow span ring buffer size for retroactive sampling.

[security] — Security Configuration

FieldTypeDefaultDescription
default_capability_policystring"deny-all"Default policy for ungranted capabilities.
audit_enabledbooleantrueEnable security audit logging.
audit_targetstring"file"Audit log target. Values: file, stdout, event-sink.

[security.grants.<COMPONENT>] — Per-Component Capability Grants

[security.grants.my-transform]
capabilities = [
    "wasi:filesystem/read:/data/input",
    "wasi:clocks/wall-clock",
]

[registry] — Registry Configuration

FieldTypeDefaultDescription
defaultstring""Default OCI registry URL for torvyn publish.