Configuration
Cleave reads a TOML configuration file. The current configuration has eight top-level areas:
| Section | Configures |
|---|---|
[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.
Response links
[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.
| Mode | Response behavior |
|---|---|
none | Suppress generated links. |
paging | Supply pagination links. |
full | Supply 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.