Instance settings

Every setting an instance reads, stored or start-only, with its default, its allowed values and what it sets.

An instance reads two kinds of setting. Stored settings live in its database and change while it runs: Change an instance's settings shows how. Start-only settings are environment variables the server reads when it starts.

Stored settings

A retention of 0 keeps those records with no age limit. The version windows must not decrease from recent to daily to weekly, and a type's own version policy takes precedence over the instance's. Secret settings are set but never shown back: marfa config get names them in secrets_set.

disk_reserve_bytes
Default 134217728 bytes
Allowed values Whole number of bytes, 0 to 1099511627776
The free space on the disk store's volume that uploads, restores, and archive exports must leave. An export's temporary files are included. A request that would take the volume below it is refused 507 insufficient_storage. A backup folder on a volume the server shares is held to it, and counts as on a disk of its own only when its device and its free space both differ from the server's, so a shared pool whose free space changes between two reads can look separate. Health reports the disk as degraded when the database's or the disk store's volume has less free than the greater of this and 64 MiB. At 0 no write is refused for room, and health still degrades below 64 MiB.
max_request_bytes
Default 1048576 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The largest ordinary JSON request body. A larger body is answered 413 request_too_large. Bulk writes, connector state, client registration, blob uploads and inbound webhook deliveries have separate limits. The server waits 180 seconds for a body, so a body larger than about 21 MiB can't arrive in time over a 1 Mbit/s link.
max_bulk_request_bytes
Default 16777216 bytes
Allowed values Whole number of bytes, 1 to 33554432
The largest body the bulk operations accept. It may be at most half of the 67108864 bytes a restore reads on one archive line, so that an item written at this limit fits on its line. The server waits 180 seconds for a body, so a body larger than about 21 MiB can't arrive in time over a 1 Mbit/s link.
blob_min_copies
Default 1
Allowed values Whole number, 1 to 1000000
The fewest live copies a blob keeps. A drop that would leave fewer is refused.
blob_cleanup_enabled
Default true
Allowed values true or false
Whether the blob-orphans job sweeps for unreferenced blobs. When off, no blob is reported or purged.
blob_cleanup_grace_seconds
Default 86400 seconds
Allowed values Whole number of seconds, 0 to 31536000
How long an unreferenced blob stands in the orphan report before a later run purges it. At 0 the next run purges it.
backup_interval_seconds
Default 3600 seconds
Allowed values Whole number of seconds, 0 to 31536000
How often the backup job puts a backup in the backup folder or the object store when anything it holds has changed. At 0 scheduled backups are off.
backup_path
Allowed values An absolute path with no .. in it, or empty
The folder the server backs itself up to: each backup under backups/<instance id>/ and a copy of each file under files/<instance id>/. The folder must exist, outside the data directory and the blob folder, and the server never creates it. It cannot be set while object_store_bucket is. When neither is set, the server keeps no backup. Changing it needs a sign-in from the last fifteen minutes.
object_store_bucket
Allowed values A name of 1 to 255 letters, digits, ., :, - and _, other than . and .., or empty
The bucket of an S3-compatible object store, which keeps a second copy of each file and the backups. The store is in use while this is set. Changing it needs a sign-in from the last fifteen minutes, and removes object_store_secret_access_key unless the same write sets it.
object_store_region
Default us-east-1
Allowed values A name of 1 to 63 letters, digits, - and _ that can be part of a host name, or empty
The region of the object store, such as us-east-1 or auto. Changing it needs a sign-in from the last fifteen minutes.
object_store_endpoint
Allowed values An absolute http or https URL with no user name or password, or empty
The endpoint of the object store. A / that is the whole path is dropped. When empty, the store's provider chooses it. Changing it needs a sign-in from the last fifteen minutes, and removes object_store_secret_access_key unless the same write sets it.
object_store_path_style
Default true
Allowed values true or false
Whether the object store is addressed by path rather than by virtual host, where the bucket goes before the endpoint's host. Read only while object_store_endpoint is set. Changing it needs a sign-in from the last fifteen minutes.
object_store_prefix
Default marfa
Allowed values /-joined segments of letters, digits, ., _ and -
The key prefix the instance keeps everything under in the bucket: its files under blobs/ and its backups under backups/. Each running instance on a bucket needs its own; a server that replaces an instance starts on its prefix. A / at either end is dropped; a . or .. segment is refused. Changing it needs a sign-in from the last fifteen minutes.
object_store_access_key_id
Allowed values Text of 1 to 256 characters, or empty
The access key ID for the object store.
object_store_secret_access_key
Allowed values A secret: text of 1 to 4096 characters with no whitespace around it, or empty
The secret access key for the object store. A write that changes object_store_bucket or object_store_endpoint removes it, unless the write sets it.
posthog_host
Allowed values A secret: an https URL, or an http URL on this machine, with no user name or password, or empty
The PostHog host the server sends a report of each unhandled fault to, at i/v1/analytics/events under it, while error_reporting_enabled is true. It needs posthog_project_token set too. When empty, no exception report is sent.
posthog_project_token
Allowed values A secret: 1 to 256 visible ASCII characters with no spaces, or empty
The PostHog project token the server sends its exception reports with. It needs posthog_host set too.
telemetry_enabled
Default true
Allowed values true or false
Whether the server sends telemetry about itself: traces, log records and metrics to the OTLP endpoints, and exception reports to posthog_host. When false, it sends none of them and keeps every telemetry setting as it is.
otel_exporter_otlp_endpoint
Allowed values A secret: an absolute http or https URL, or empty
The base URL of the OTLP receiver. When set, the server exports traces to v1/traces, log records to v1/logs and metrics to v1/metrics under it, keeping its query. When empty, no trace, log record or metric is exported.
otel_exporter_otlp_traces_endpoint
Allowed values A secret: an absolute http or https URL, or empty
The URL traces are posted to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set.
otel_exporter_otlp_logs_endpoint
Allowed values A secret: an absolute http or https URL, or empty
The URL log records are posted to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set.
otel_exporter_otlp_metrics_endpoint
Allowed values A secret: an absolute http or https URL, or empty
The URL metrics are posted to, used as written, in place of the one under otel_exporter_otlp_endpoint, which must also be set.
otel_exporter_otlp_headers
Allowed values A secret: comma-separated key=value HTTP headers with percent-encoded values, of at most 8192 bytes, or empty
The headers sent with every OTLP export.
otel_exporter_otlp_traces_headers
Allowed values A secret: comma-separated key=value HTTP headers with percent-encoded values, of at most 8192 bytes, or empty
The headers sent with trace exports. One here replaces the one of the same name in otel_exporter_otlp_headers.
otel_exporter_otlp_logs_headers
Allowed values A secret: comma-separated key=value HTTP headers with percent-encoded values, of at most 8192 bytes, or empty
The headers sent with log exports. One here replaces the one of the same name in otel_exporter_otlp_headers.
otel_exporter_otlp_metrics_headers
Allowed values A secret: comma-separated key=value HTTP headers with percent-encoded values, of at most 8192 bytes, or empty
The headers sent with metric exports. One here replaces the one of the same name in otel_exporter_otlp_headers.
otel_sample_ratio
Default 0.05
Allowed values A number from 0 to 1
The share of traces exported. A trace that contains an error is exported whatever this says: the span that failed, the spans held for the trace (at most 500) and every span after it.
otel_service_name
Allowed values Text of 1 to 255 characters, or empty
The service name on everything exported, in place of a service.name in otel_resource_attributes. When both are empty, it is marfa-server. Kept by this machine and carried by no archive.
otel_resource_attributes
Allowed values Comma-separated key=value pairs with percent-encoded values, of at most 4096 bytes, or empty
Attributes added to everything exported. One named here replaces the server's own of the same name, such as service.version. Kept by this machine and carried by no archive.
heartbeat_url
Allowed values A secret: an absolute http or https URL, or empty
The URL the server requests on a schedule while heartbeat_enabled is true, so that something else can notice when the requests stop. When empty, there is no heartbeat.
allow_private_addresses
Default false
Allowed values true or false
Whether the server may send to loopback, private and other addresses that are not public: webhooks, heartbeat_url, posthog_host, the three OTLP endpoints and object_store_endpoint. Changing it needs a sign-in from the last fifteen minutes.
enrichment_enabled
Default true
Allowed values true or false
Whether the server extracts text from uploaded files.
enrichment_ocr_enabled
Default true
Allowed values true or false
Whether the server reads text from images with OCR. When off, images are recorded as unsupported.
enrichment_max_blob_bytes
Default 20971520 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The largest blob the server extracts text from. A larger blob gets no extracted text.
enrichment_max_text_chars
Default 100000
Allowed values Whole number, 1 to 100000000
The most Unicode characters of extracted text the server keeps, counted as characters, not UTF-16 code units. Longer text is cut short.
enrichment_max_inflated_bytes
Default 67108864 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The most a document may inflate to when the server extracts its text, all of its parts together. A document that inflates past it is skipped.
enrichment_max_memory_bytes
Default 1073741824 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The most memory reading one file may use. A file that needs more is skipped.
enrichment_max_attempts
Default 3
Allowed values Whole number, 1 to 100
How many times the server tries to extract text from a failing item before it stops.
sign_in_address
Allowed values An origin with no path, or empty
The address people sign in at, which OAuth, cookies and links use. An origin has a scheme, a host and an optional port, with no user name, password, path, query or fragment. Empty uses http://localhost with the port the server listens on, whatever MARFA_LISTEN_HOST is. It joins addresses without being listed there.
cors_origins
Allowed values List of origins, each scheme://host[:port] with no path
The browser origins allowed to call the API across origins with a token, beside the web pages the owner approves.
rate_limit_enabled
Default true
Allowed values true or false
Whether the rate limiter is on for a key's or an app's requests, and for app registration, device code requests, passkey sign-in challenges and deliveries to inbound addresses.
rate_limit_requests
Default 4000
Allowed values Whole number, 1 to 1000000
The requests one key or app may make to all operations together in each window.
rate_limit_window_seconds
Default 60 seconds
Allowed values Whole number of seconds, 1 to 86400
The length of a rate-limit window.
rate_limit_keys_requests
Default 200
Allowed values Whole number, 1 to 1000000
The requests one credential may make in each window to the operations under /keys.
inbound_max_bytes
Default 26214400 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The largest inbound webhook delivery the server stores.
rate_limit_inbound_requests
Default 600
Allowed values Whole number, 1 to 1000000
The deliveries one inbound endpoint accepts in each rate-limit window.
inbound_backlog_deliveries
Default 10000
Allowed values Whole number, 1 to 1000000
The unhandled deliveries one registration may hold before the server refuses more deliveries for it.
inbound_backlog_bytes
Default 1073741824 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The bytes of unhandled deliveries one registration may hold before the server refuses more deliveries for it.
inbound_retained_deliveries
Default 10000
Allowed values Whole number, 1 to 1000000
The most deliveries the server retains across live and retired endpoints.
inbound_retained_bytes
Default 1073741824 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The most bytes of deliveries the server retains across live and retired endpoints.
inbound_in_flight_bytes
Default 104857600 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The most bytes of inbound webhook deliveries the server holds in memory at once.
inbound_handled_retention_days
Default 7 days
Allowed values Whole number of days, 0 to 36500
How long the server keeps a handled delivery. At 0 age does not expire a delivery.
inbound_pending_retention_days
Default 30 days
Allowed values Whole number of days, 0 to 36500
How long the server keeps an unhandled delivery. At 0 age does not expire a delivery.
audit_retention_days
Default 90 days
Allowed values Whole number of days, 0 to 36500
How long the server keeps audit entries and webhook delivery history. At 0 no entry expires by age.
revoked_grant_retention_days
Default 90 days
Allowed values Whole number of days, 0 to 36500
How long a revoked application grant is kept. At 0 no revoked grant is purged.
grant_inactivity_days
Default 365 days
Allowed values Whole number of days, 0 to 36500
How long an application grant may go unused before the server retires it. At 0 grants are never retired.
event_log_retention_days
Default 30 days
Allowed values Whole number of days, 0 to 36500
The least time an event stays in the event log, which bounds how far back a stream can replay, and the time the server keeps the answer to a write sent with an Idempotency-Key. At 0 neither expires by age.
version_recent_days
Default 30 days
Allowed values Whole number of days, 0 to 36500
The window in which the version policy keeps every version of an item.
version_daily_snapshot_days
Default 90 days
Allowed values Whole number of days, 0 to 36500
The window in which the version policy keeps one version a day. It must be at least version_recent_days.
version_weekly_snapshot_days
Default 365 days
Allowed values Whole number of days, 0 to 36500
The window in which the version policy keeps one version a week. It must be at least version_daily_snapshot_days.
version_max_versions
Default 500
Allowed values Whole number, 1 to 1000000
The most versions the version policy keeps for one item.
trash_retention_days
Default 60 days
Allowed values Whole number of days, 0 to 36500
How long an item stays in the trash before the server deletes it. At 0 nothing in the trash expires by age.
row_log_retention_days
Default 30 days
Allowed values Whole number of days, 0 to 36500
How long a table keeps a batch in its change log, which bounds how far back a batch can be undone. At 0 no batch leaves the log by age.
unapproved_app_retention_hours
Default 1 hour
Allowed values Whole number of hours, 0 to 876000
How long a dynamically registered client with no grants is kept, counted from its registration or the last time an approval page offered it. At 0 none is removed by age.
event_stream_max_viewers
Default 0
Allowed values Whole number, 0 to 1000000
The most event-stream viewers one server instance serves at once. At 0 there is no limit.
mcp_fetch_enabled
Default true
Allowed values true or false
Whether MCP tools fetch a file from a web address, or a file a chat attached, to save it. When off, a tool asked to fetch one is refused.
mcp_fetch_max_bytes
Default 52428800 bytes
Allowed values Whole number of bytes, 1 to 1099511627776
The largest file an MCP tool fetches from a web address to save. A larger file is refused and nothing is stored.
mcp_fetch_timeout_seconds
Default 60 seconds
Allowed values Whole number of seconds, 1 to 3600
How long an MCP tool's fetch of a file from a web address may take, from connecting to the last byte.
error_reporting_enabled
Default true
Allowed values true or false
Send exception reports to posthog_host.
heartbeat_enabled
Default true
Allowed values true or false
Send scheduled requests to heartbeat_url.
update_check_enabled
Default true
Allowed values true or false
Whether the server checks GitHub for new Marfa releases every few hours. When off, it makes no request for them and reports no release as newer.
addresses
Allowed values List of origins, each scheme://host[:port] with no path
The addresses people reach this instance at, such as https://marfa.example. Each is an origin: a scheme, a host and an optional port, with no path. Links the server builds come from this list and the sign-in address.

Enforcement levers

enforcement is one stored setting that holds chosen types to a stricter rule. Each lever names types, and source_allowlist and source_filter also name sources:

marfa config update --body '{"enforcement": {"strict_mode": {"types": ["core.note"]}}}'
LeverWhat it doesWhat the caller meets
strict_modeRefuses a write that names a property neither the item's type nor an ancestor declares. Without it, Marfa keeps an undeclared property and serves it back.400 invalid_properties, with details.code set to unknown_property.
source_allowlistLets only the listed sources create items of a type.403 forbidden, with details.type, details.source and details.allowed.
source_filterLeaves items of a type whose source isn't listed out of listings, searches, exports, event streams and webhook deliveries.Nothing: the item isn't there.

strict_mode and source_allowlist hold for exactly the types they list, not the types that inherit from them. source_filter also covers the types under a listed type. Reading an item by its ID isn't filtered. An item with no source counts as one whose source is unknown.

An update that names enforcement replaces all three levers, and null removes them. A key can carry levers of its own in enforcement_override, each replacing the instance's for that key: marfa keys create --help and marfa keys update --help show the --enforcement-override option, as the CLI says.

Start-only settings

Most instances set none by hand: the install, the image and the Railway template set the ones they need. The MARFA_TEST_ settings are for Marfa's own tests: leave them unset. A MARFA_ name the server doesn't read warns and names the setting you may have meant. The exception is a likely typo of MARFA_KEY_SALT or MARFA_AUTH_SECRET while that secret is missing: the server refuses to start, because it would make a new secret and end every key or sign-in.

MARFA_PORT
Default 8600
Allowed values Whole number, 0 to 65535
The port the server listens on. Zero lets the operating system assign a port.
MARFA_LISTEN_HOST
The IP address or hostname the public HTTP listener binds to. Unset uses the runtime's unspecified address: IPv6 when available, otherwise IPv4.
MARFA_DATABASE_PATH
Default ./data/marfa.db
The path of the database file. A value starting with file: is passed to the database as written, and :memory: opens a database held in memory.
MARFA_CONTROL_SOCKET
Absolute private Unix socket path. Defaults to control/marfa.sock beside the database. Its directory must belong to the server account with mode 0700.
MARFA_CONTROL_ONLY
Default false
Allowed values true, 1, yes, on, false, 0, no or off, in any case
Start only the private control listener, without public HTTP or background jobs, for local recovery.
MARFA_CLAIM_ADDRESS
Allowed values An https origin, or an http one on a loopback name
The sign-in address of an instance with no owner, for one that is claimed from another host. As it starts, the server stores it as sign_in_address, judged by that setting's rule, which also allows http only on localhost, 127.0.0.1 or [::1]. Once the instance has an owner, the server ignores it and logs that it did, and the address changes only through /config.
MARFA_OWNER_RECOVERY
Default false
Allowed values true, 1, yes, on, false, 0, no or off, in any case
Whether each start of an instance with an owner prints a recovery code in the server's own log, with which the owner chooses a new password at /setup without a shell. The code works once, for 60 minutes, and the next start replaces it. Off, a start removes any code an earlier start printed. Behind a platform proxy or shared edge, set MARFA_TRUSTED_PROXY_HEADER and MARFA_TRUSTED_PROXY_CIDRS, or every caller shares one attempt limit and wrong guesses can block the owner's code for a while.
MARFA_CLOUD_URL
Default https://cloud.marfa.so
Allowed values An https origin, or an http one on a loopback name
Where Marfa Cloud is. The server sends to it only for a link the owner starts (cloud/nothing-sent).
MARFA_CLOUDFLARED
Default cloudflared beside the server's own executable
Allowed values An absolute path
The file the server runs as the tunnel connector while the instance is linked to Marfa Cloud (cloud/connector-setting). Where it is not set, the server runs the file cloudflared in the folder that holds its own executable, and it never searches PATH (cloud/connector-beside, cloud/connector-no-path). A missing or unrunnable file is reported in the link's connector, and the server keeps serving.
MARFA_TEST_HOOKS
Default false
Allowed values true, 1, yes, on, false, 0, no or off, in any case
Serve the clock and fault routes a conformance harness drives on the private control socket. Never on the public listener. A server built without test hooks refuses to start when it is true. Leave off on every instance that holds real data.
MARFA_TEST_CLOCK_OFFSET_MS
Default 0 ms
Allowed values Whole number of milliseconds, 0 to 3153600000000
How far ahead of the system clock the server's clock starts. Needs MARFA_TEST_HOOKS, so a harness that moved the clock can restart the server without the time going back.
MARFA_TEST_CONTRACT_VERSION
Default The build's contract version
Allowed values Whole number, 0 to 1000000
The contract version the server speaks instead of the build's, in the root's contract, the X-Marfa-Contract header and the document's info.version. Needs MARFA_TEST_HOOKS, so a harness can show what a change of contract does to what the server kept.
MARFA_TEST_TUNING
Allowed values Comma-separated name=value pairs
Shortens a timing or a batch size the server fixes: interval.<job> or interval.* in milliseconds (neither reaches backup, whose interval is the stored backup_interval_seconds, and interval.backup is refused), housekeeping_poll_ms, write_wait_ms, upload_idle_ms, blob_read_idle_ms, inbound_idle_ms or connector_hold_ms in milliseconds, or enrichment_batch, blob_replicate_batch, blob_replicate_batch_bytes, blob_integrity_batch or blob_integrity_batch_bytes. Needs MARFA_TEST_HOOKS.
MARFA_MAX_CONNECTIONS
Default 1024
Allowed values Whole number, 1 to 1000000
The most connections the public listener, with the tunnel listener while a link to Marfa Cloud is linking or linked, holds open at once. The server lowers it at start where the open-file limit leaves too little room ("Open connections").
MARFA_MAX_CONNECTIONS_PER_ADDRESS
Default 256
Allowed values Whole number, 1 to 1000000
The most connections the public listener holds open for one caller address, where the listener does not believe a forwarded address. An IPv6 address counts with the rest of its /64. A value above MARFA_MAX_CONNECTIONS has no effect.
MARFA_BLOB_PATH
Default ./data/blobs
The folder of the disk store, where every upload lands.
MARFA_ENRICHMENT_TESSDATA_DIR
A folder of OCR language models.
MARFA_TRUSTED_PROXY_CIDRS
Allowed values Comma-separated CIDR ranges, IPv4 or IPv6
The address ranges of the proxies whose X-Forwarded-For header, or the header MARFA_TRUSTED_PROXY_HEADER names, the server believes. When empty, X-Forwarded-For is ignored.
MARFA_TRUSTED_PROXY_HEADER
Allowed values An HTTP header name
The name of a header that the platform's edge overwrites with the client address, believed only from a peer inside MARFA_TRUSTED_PROXY_CIDRS, which it needs. While it is set, X-Forwarded-For is ignored.
MARFA_KEY_SALT
Default None. Generated on first start into marfa.secrets.
Allowed values Text with no whitespace around it
The salt for hashing API keys and app tokens. Changing it invalidates every existing key and token. Unset, the server uses the salt in marfa.secrets, which it generated on first start.
MARFA_AUTH_SECRET
Default None. Generated on first start into marfa.secrets.
Allowed values Text of at least 32 characters, with no whitespace around it
The secret that signs sign-in cookies, authorize queries, reach proofs and credential-free blob links. It must be at least 32 characters. Unset, the server uses the secret in marfa.secrets, which it generated on first start.

The telemetry settings are stored settings: Send or turn off telemetry shows them, and Give your instance an address the proxy settings.

On this page