Documentation

Configuration

Cleave reads a TOML configuration file. The current configuration has eight top-level areas:

SectionConfigures
[tcp]Listener address, port, workers, TLS, and connection timeouts.
[http]Request size limits, keep-alive, and browser origins (CORS).
[interface]The client-facing protocol and its resource, paging, link, and representation policies.
[dbms]Repository adapter, credentials, endpoints, and connection pools.
[auth]JWT verification and record access policy.
[cache]Response caching and cache lifetime.
[logging]Operational log destination and severity.
[metrics]Request counters, latency measurements, and reporting destination.

The examples below follow the current runtime configuration layout, including Cleave.container.mysql.toml and the PostgreSQL and MongoDB presets. They are section examples: combine the sections you need into your deployment file and replace addresses, credentials, and policy values for your environment.

Use [interface] and its nested sections for client-facing settings. Omitted optional settings use built-in defaults; the values explicitly shown below are example choices, not a complete list of defaults.

TCP listener

[tcp]
address = "0.0.0.0"
port = 27896
workers = 1
tls_enabled = false
timeout = 100
shutdown = 5

For a container, 0.0.0.0 accepts connections on its network interfaces; decide which host interfaces expose that port through your Docker mapping. For a native service called only by a same-host proxy, a loopback listener may be appropriate.

timeout bounds connection handling in seconds; shutdown is the graceful shutdown interval. workers selects the runtime worker count. TLS certificate and key paths belong here when Cleave serves HTTPS itself:

[tcp]
tls_enabled = true
tls_cert_path = "/etc/cleave/tls/server.crt"
tls_key_path = "/etc/cleave/tls/server.key"

See Deployment for Docker and proxy arrangements.

HTTP limits and browser origins

Request limits and keep-alive belong under [http], separately from the listener:

[http]
req_uri_maxlength = 500
req_body_maxlength = 10000
keep_alive = true
cors_allow_origins = ["https://app.example.com", "https://admin.example.com"]

Size limits are in bytes. Choose limits that accommodate your supported requests while keeping their size bounded.

CORS entries are the origins hosting your frontend pages, including the scheme and any nonstandard port. An empty list emits no CORS origin header; ["*"] allows any browser origin. See Security: CORS.

Client interface

[interface] selects the application-facing adapter and shared service policy:

[interface]
adapter = "jsonapi"
path_prefix = "/api/0.0/"
version = "1.0"
uuid_version = "v7"
service_available = []
use_forwarded_headers = false
trusted_proxy_ips = []

adapter selects the interface, not the database. The JSON:API interface is jsonapi; the repository adapter is configured separately under [dbms]. Current interface names also include graphql and xmlapi; their configuration and supported operations differ. GraphQL requires an explicit schema file under [interface.graphql] rather than inheriting the JSON:API resource contract.

path_prefix defines the API path. uuid_version controls generated resource identities. version supplies the configured interface version and can be blank.

An empty service_available list does not restrict client IPs. For a local-only caller, set service_available = ["127.0.0.1"]. Configure trusted proxy addresses explicitly before enabling forwarded headers. See Security: Service Availability.

Paging

[interface.paging]
limit_default = 5
limit_max = 100
skip_max = 250

limit_default applies when a request omits its page size. limit_max caps the requested size; skip_max bounds offset pagination.

[interface.links]
base_url = "https://api.example.com"
mode = "full"

Set base_url to the public HTTP(S) origin callers should use, especially behind a proxy. Do not append the API path, credentials, a query string, or a fragment. The path prefix remains in [interface]. This URL configures Cleave's response links, independently of the website's Zola base_url.

ModeResponse behavior
noneSuppress generated links.
pagingSupply pagination links.
fullSupply pagination and other resource links supported by the interface.

See Resource Access for following links.

Method and collection restrictions

[interface.methods]
not_allowed_entity = []
not_allowed_collection = ["DELETE"]

[interface.collections]
forbidden = ["private_admin"]

This example disables collection DELETE and excludes the private_admin resource. Set restrictions for the resources your application actually exposes. Record permissions remain a separate policy under [auth].

Field visibility and writes

[interface.fields]
get_forbidden = ["private_note"]
post_forbidden = ["private_note"]
put_forbidden = ["private_note"]
patch_forbidden = ["private_note"]
get_allow_special = false

Each method's list restricts fields for that operation. Explicit lists replace the configured defaults: retain protections for service-managed metadata when customizing your deployment. get_allow_special controls visibility of protected metadata fields on reads.

Representation and dates

[interface.format]
value_encoding = "literal"
meta = "nested"
relationship = "nested"

[interface.datetime]
date_format = "iso8601"
datetime_format = "iso8601"
utc_offset = "+00:00"

literal uses ordinary scalar values; typed enables explicit value-type annotations. meta and relationship select flat or nested representation. Date and datetime settings control formatting, with utc_offset supplying the timezone offset preference.

Language and public errors

[interface.language]
accept_language = []
accept_charset = ""
content_language = ""
content_charset = ""

[interface.errors]
expose_repository_codes = false

accept_language is a list of configured language preferences. Blank charset and content-language values leave those gates unset. Keep repository-specific error codes out of public responses unless your deployment explicitly needs them; use operational logs for diagnosis.

[interface.security] is currently reserved and can be omitted.

Repository access

[dbms]
adapter = "mysql"
value_binding = "parameterized"
address = "mysql"
port = 3306
writer_endpoint = "mysql:3306"
reader_endpoint = "mysql:3306"
user = "cleave_app"
passwd = "replace-with-your-database-password"
schema = "my_application"
charset = "ascii"

Writes use writer_endpoint; reads use reader_endpoint. They can point to the same repository initially. Use hostnames reachable from Cleave's environment and a database account limited to the application's resources.

Select mysql, postgres, or mongodb for the relevant build and repository. MongoDB also supports mongo_auth_source for its authentication database. See Repositories and the deployment connection examples.

Reader and writer pools

Pool controls are configured under [dbms.pool]:

[dbms.pool]
writer_min_size = 1
writer_max_size = 10
writer_max_lifetime = 300
writer_idle_timeout = 100
writer_acquire_timeout = 5
writer_max_uses = 1000000

reader_min_size = 1
reader_max_size = 10
reader_max_lifetime = 300
reader_idle_timeout = 100
reader_acquire_timeout = 5
reader_max_uses = 1000000

Durations are seconds. Acquisition timeout limits the wait for a connection, not how long a query may execute. Lifetime and idle timeout control connection retirement; max_uses caps connection reuse where supported. Zero disables the corresponding retirement limit. Set capacities within your repository's connection budget and tune reader and writer sizes for the workload.

MongoDB manages its own physical pools. Its presets set both max_lifetime and max_uses to zero for reader and writer pools. Use the adapter-specific preset rather than copying SQL pool retirement settings unchanged.

Authentication and access policy

[auth]
ignore_auth = false
control_level = "usergroup"
algorithm = "HS256"
secret = "replace-with-your-deployment-secret"
issuer = "https://identity.example.com/"
audience = "cleave-api"
require_exp = true
require_nbf = false
clock_skew_seconds = 60
initial_perm = "744"

This example uses shared-secret verification. For an RS256 issuer, set algorithm = "RS256" and supply its PEM verification key through public_key. Configure the issuer, audience, and access policy to match your application's signed tokens. See JWT Authentication and Access Control.

Some local runtime presets disable authentication for evaluation. Keep ignore_auth = false for deployments that require verified callers.

Cache

[cache]
caching = false
ttl_ms = 1000

Caching has its own top-level section. ttl_ms is milliseconds, unlike the connection-pool durations above. Enable caching only when the resulting freshness behavior suits your application.

Operational logging

[logging]
type = "console"
level = "notice"

For syslog, select type = "syslog" and configure transport, endpoint, and any required certificate settings. Transports include udp, tcp, tls, and unix. Runtime presets may use cert as an alias for certificate.

Choose verbosity and retention for the information your operators need. Debug and detailed request logs can contain sensitive application context.

Metrics

Metrics have their own destination and enablement, separate from log severity:

[metrics]
enabled = true
request_latency = true
type = "syslog"
transport = "udp"
endpoint = "logstash:5515"
interval = 10
send_sparse = false

interval is seconds and must be positive. send_sparse = false skips empty intervals; true emits them as well. request_latency enables latency measurement. The receiver must exist and be reachable from Cleave; these settings do not start it.

Use [metrics] rather than increasing operational logging verbosity just to collect counters. See Deployment: Throughput and Latency Metrics for a complete receiver example.

Inspect the effective configuration

Start the server with --print to include its effective configuration in startup output, with supported secret fields redacted:

./cleave --print /path/to/Cleave.toml

This also starts the service; it is not a standalone validation command. Confirm the listener, public link origin, repository endpoints, and reporting destinations before directing application traffic to it.