Camel.toml schema

Camel.toml is the operator surface for rust-camel. The file is TOML, parsed by CamelConfig::from_file, and deserialized into the CamelConfig struct. Most fields live under [default] and merge with named profiles ([production], [staging], ...) per the profile rules described in Configuration.

A minimal file sets the route discovery glob and the log level. Everything else has a runtime default.

[default]
routes = ["routes/**/*.yaml"]
log_level = "INFO"

A fuller file adds supervision, tracing, and shared component defaults. Profiles override per environment.

[default]
routes = ["routes/**/*.yaml"]
log_level = "INFO"

# Optional supervision configuration
[default.supervision]
max_attempts = 5
initial_delay_ms = 1000
backoff_multiplier = 2.0
max_delay_ms = 60000

# Optional tracing configuration
[default.observability.tracer]
enabled = true
detail_level = "minimal"

[default.observability.tracer.outputs.stdout]
enabled = true
format = "json"

# Component defaults (optional) - apply to all endpoints unless overridden by URI
# Uncomment to enable global component settings:

# [default.components.http]
# connect_timeout_ms = 5000
# response_timeout_ms = 30000
# max_connections = 100
# allow_internal = false

# [default.components.kafka]
# brokers = "localhost:9092"
# group_id = "camel"
# session_timeout_ms = 45000

# [default.components.redis]
# host = "localhost"
# port = 6379

# [default.components.sql]
# max_connections = 5
# min_connections = 1
# idle_timeout_secs = 300

# [default.components.file]
# delay_ms = 500
# read_timeout_ms = 30000

# [default.components.container]
# docker_host = "unix:///var/run/docker.sock"

# Optional persistent idempotent repository (opt-in). When set under the
# active profile, registers a "redb" backend for `idempotent_consumer` steps;
# keys persist across restart. The default "memory" repo stays available.
# durability: "immediate" (default, fsync per key) | "eventual" (no fsync, faster)
# [default.idempotent_repo]
# path = ".camel/idempotent.redb"
# durability = "immediate"

[development]
log_level = "DEBUG"

[production]
log_level = "ERROR"

Top-level fields

The fields below live directly under [default]. They are the spine of the file. Every other section in this page is optional.

The watcher and the file are wired through camel-core::reload_watcher::watch_and_reload (see ADR-0004). The --watch and --no-watch CLI flags override this field at startup.

[binds."<addr>"]

Per-bind public-exposure acknowledgements (ADR-0061 Rule 4). When any route on a NON-loopback bind (http://0.0.0.0:8080, wss://0.0.0.0:9000, an MCP bind, …) compiles to a Public security plan, startup refuses unless the bind carries an explicit acknowledgement; an acknowledged exposure warns permanently on every start (ADR-0052 rule 3). Loopback binds (127.0.0.1, localhost, ::1) need no acknowledgement.

[binds."0.0.0.0:8080"]
allow_public_exposure = true

[components]

Component configuration is untyped TOML keyed by component name. Each component bundle parses its own block. The schema below is the union of fields the runtime and core components recognize.

[components.http]
connect_timeout_ms = 5000
response_timeout_ms = 30000
allow_internal = false

[components.kafka]
brokers = "localhost:9092"
group_id = "camel"

The full per-component schema lives in each component's documentation. The Kafka block is the most complex and supports a [components.kafka.brokers_named.<name>] sub-table for pre-configured clusters referenced from URIs with ?brokerName=<name>. See Kafka for the named-broker fields.

Custom component bundles follow the same convention. A bundle named echo reads its config from [components.echo]. See Custom component for the bundle contract.

[supervision]

The runtime uses these knobs to restart a failed Consumer with capped exponential backoff. Defaults match a one-second start, doubling each attempt, capped at one minute, with five attempts.

[observability]

The observability block holds five optional sub-tables. The [observability.tracer] block configures the built-in tracing layer, and [observability.metrics] gates its metric families. The other three activate optional exporters.

Span and metric enablement are independent:

• [observability.tracer] enabled gates SPAN creation only. With Prometheus (or OTel) active, an explicit enabled = false still runs the tracer pipeline so metric families keep flowing; no spans are created.
• The pipeline itself is turned off only when neither tracing nor any exporter is active. The [observability.metrics] levers below can suppress individual non-error families but never disable the pipeline.

[observability.metrics]

Metric-family levers. Unknown keys fail at load, consistent with the sibling observability tables. There is no lever for the error family: camel_errors_total is structurally non-disableable and is exported regardless of any combination of these keys.

[observability.otel]

OTLP export configuration. The protocol and sampler accept the values listed below; values not in the enum fail at load.

[observability.prometheus]

[observability.health]

[security]

The security block holds five optional sub-tables. Pick one. Most deployments choose exactly one of oidc, native, or keycloak. The permissions and policies sub-tables extend the chosen identity layer with authorization.

Placeholders in Camel.toml use ${env:VAR} and ${env:VAR:-default}. The :- separator is native: default is used when VAR is unset. An unset variable without a default aborts load, naming the field. The legacy {{...}} syntax is rejected with an error pointing at the ${env:} forms. See Environment variable interpolation.

[security.keycloak]
server_url = "https://kc.example.com"
realm = "my-realm"
client_id = "camel"
client_secret = "${env:KC_SECRET}"

[security.oidc]

[security.native]

The native block is a static credential store with no external identity provider. Set at least one credential: a scalar bearer_token or api_key, or one or more [[security.native.credentials]] entries. A config with no credential fails load.

[[security.native.credentials]] array elements:

Each credentials entry must set exactly one of secret_env or secret; setting both or neither fails at load. The block uses deny_unknown_fields, so unknown keys are rejected at load.

[security.keycloak]

[security.keycloak.validation] fields:

[security.keycloak.jwks] fields:

[security.keycloak.introspection] fields:

[security.permissions.<name>]

Named permission evaluators. A route references the name through route configuration.

[security.permissions.invoice-policy]
provider = "wasm"
path = "./policies/invoice-policy.wasm"

[security.permissions.invoice-policy.config]
mode = "enforce"

[security.permissions.invoice-policy.cache]
positive_ttl_secs = 60
negative_ttl_secs = 10

[security.permissions.<name>] cache fields:

[security.policies.wasm.<name>]

Registry of named WASM security policies. Each entry is a path plus limits plus a config map.

[security.policies.wasm.corp-auth]
path = "plugins/authz.wasm"

[security.policies.wasm.corp-auth.limits]
timeout-secs = 30

[security.policies.wasm.corp-auth.config]
ldap_url = "ldap://corp"

[runtime_journal]

The runtime event journal. When unset, runtime state is ephemeral and lost on restart. Set a path to enable a redb-backed journal.

[idempotent_repo]

Persistent idempotent repository for the Idempotent Consumer EIP. When unset, the runtime uses the in-memory MemoryIdempotentRepository, which is bounded and ephemeral.

backend selects the store. "redb" is the default. The redb repository registers under the name "redb". The redis repository registers under the name "redis", and route steps select it with repository = "redis". Redis keys survive a process restart and are shared by every process that connects to the same Redis.

In url mode the URI carries the password and the database. The password rides the userinfo and the database rides the ?db=N query parameter, as in redis://:pass@host:port?db=N. A username in the URI is not supported.

A runnable redis configuration lives in examples/redis-repositories:

[default.idempotent_repo]
backend = "redis"
url = "redis://127.0.0.1:6379"

[cache_repo]

Optional cache repository configuration. When unset, only the default "memory" cache repository is registered. With backend = "redb", a persistent "persistent" repository (redb-backed) is registered alongside "memory". With backend = "redis", a shared "redis" repository is registered alongside "memory", and route steps select it with repository = "redis".

In url mode the URI carries the password and the database. The password rides the userinfo and the database rides the ?db=N query parameter, as in redis://:pass@host:port?db=N. A username in the URI is not supported.

Fields that do not apply to the configured backend are rejected at validation (fail-closed), and a malformed cache_size, sweep_interval, stale_retention, payload_sweep_interval, or payload_max_ttl fails validation with an error naming the field. The same applies to payload fields set while payload is inline or unset.

A runnable redis configuration lives in examples/redis-repositories:

[default.cache_repo]
backend = "redis"
url = "redis://127.0.0.1:6379"
stale_retention = "30m"

[stream_caching]

The Stream Cache step buffers stream bodies past a threshold so the body can be read more than once. The cache applies to the whole runtime, not per route.

[platform]

Platform selection for leader election, readiness, and identity. Defaults to noop, which always reports leader and ready. Set type = "kubernetes" to enable leader election through a Kubernetes lease.

[platform] with type = "kubernetes" accepts:

[languages]

The languages block tunes the resource limits for the in-process scripting engines. Each sub-block is optional. Unset fields fall back to the rust-camel runtime default, never to the upstream engine's unlimited default.

[languages.rhai.limits]

Rhai sandbox limits.

[languages.js.limits]

Boa JavaScript engine limits.

[languages.minijinja.limits]

MiniJinja template engine limits.

[components.template.limits]

The external Template component's resource limits. Set any subset of fields. Unset fields fall back to the resolved defaults listed below.

[components.template.limits]
max-total-source-bytes = 16777216
max-include-count = 64
max-include-depth = 16
max-template-size = 1048576
reload-timeout-ms = 5000

Zero values are rejected. The block uses deny_unknown_fields, so a typo is caught at load.

[beans]

Named beans are WASM plugins exposed to routes as lookup targets. Each bean is keyed by name and carries a plugin path plus an optional config map and WASM limits.

[beans.auth]
plugin = "my-auth"

[beans.auth.config]
api_key = "${env:API_KEY}"

[beans.auth.limits]
timeout-secs = 600

WASM limits

WASM limits appear in three places: [beans.<name>.limits], [security.permissions.<name>.limits], and [security.policies.wasm.<name>.limits]. The struct is the same in all three. The fields use kebab-case. Unset fields fall back to the rust-camel runtime default. The defaults are finite: 50 MiB max memory, 10 MB max wasm size, 10 000 max instances, 10 000 max tables.

[datasources]

Named datasource pools. Each entry is keyed by a name that routes reference through the datasource URI parameter (for example sql:SELECT * FROM users?datasource=my-db). The block is a map of DatasourceConfig values.

[default.datasources.appdb]
db_url = "sqlite:file:memdb?mode=memory&cache=shared"
max_connections = 5

Profile overrides

[default] always applies. A named profile like [production] is selected through CAMEL_PROFILE=production or the loader API. Profile blocks deep-merge on top of [default]. The example below shows a [production] block tightening timeouts and pointing Kafka at the production cluster.

# Shared component defaults live in a separate file so they can be reused
# across deployment configs without duplication.
include = ["config/components.toml"]

[default]
routes = ["routes/**/*.yaml"]
log_level = "INFO"

# Optional supervision configuration
[default.supervision]
max_attempts = 5
initial_delay_ms = 1000
backoff_multiplier = 2.0
max_delay_ms = 60000

# Optional tracing configuration
[default.observability.tracer]
enabled = true
detail_level = "minimal"

[default.observability.tracer.outputs.stdout]
enabled = true
format = "json"

# Development profile - more verbose, local services
[development]
log_level = "DEBUG"

[development.components.http]
allow_internal = true  # Allow internal services in dev

[development.components.kafka]
brokers = "localhost:9092"

# Production profile - stricter settings, remote services
[production]
log_level = "WARN"

[production.components.http]
connect_timeout_ms = 5000   # Faster fail in production
allow_internal = false

[production.components.kafka]
brokers = "prod-kafka:9092"
group_id = "camel-prod"
session_timeout_ms = 60000

The [development] and [production] blocks set a log_level and override shared component defaults. Shared component defaults can also live in a separate file pulled through include. See Configuration for the merge rules and the include order.

Environment variable overrides

A small allowlist of CAMEL_* environment variables overrides specific fields when the runtime calls CamelConfig::from_file_with_env. The allowlist is the security boundary: any CAMEL_* variable not in the list is ignored at load and logged as a warning.

Cache repo overrides carry a typed contract. String-typed fields receive their raw value verbatim, with no numeric or boolean coercion. Numeric-typed fields parse strictly typed values. Duration fields accept humantime forms with explicit units. A unitless numeric value is rejected at validation with an error naming the required format. An empty value is skipped for the newer scalar variables, so the file or profile value stays effective. Legacy variables receive the raw value, empty or not.

CAMEL_CONFIG_FILE and CAMEL_PROFILE are also read, but outside the allowlist. CAMEL_CONFIG_FILE selects the file path before load. CAMEL_PROFILE selects the profile section.

Note: Connection strings and credentials are outside the allowlist. Set them with ${env:VAR} placeholders in Camel.toml values, never through env overrides. The loader ignores CAMEL_CACHE_REPO_URL, CAMEL_CACHE_REPO_USERNAME, CAMEL_CACHE_REPO_PASSWORD, CAMEL_CACHE_REPO_SENTINEL_USERNAME, and CAMEL_CACHE_REPO_SENTINEL_PASSWORD and logs a warning.

Reference: Config crate