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
134217728bytes - 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
1048576bytes - 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
16777216bytes - 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
trueorfalse - Whether the
blob-orphansjob sweeps for unreferenced blobs. When off, no blob is reported or purged. blob_cleanup_grace_seconds- Default
86400seconds - 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
3600seconds - Allowed values Whole number of seconds, 0 to 31536000
- How often the
backupjob 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 underfiles/<instance id>/. The folder must exist, outside the data directory and the blob folder, and the server never creates it. It cannot be set whileobject_store_bucketis. 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_keyunless 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-1orauto. Changing it needs a sign-in from the last fifteen minutes. object_store_endpoint- Allowed values An absolute
httporhttpsURL 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 removesobject_store_secret_access_keyunless the same write sets it. object_store_path_style- Default
true - Allowed values
trueorfalse - 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_endpointis 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 underbackups/. 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_bucketorobject_store_endpointremoves it, unless the write sets it. posthog_host- Allowed values A secret: an
httpsURL, or anhttpURL 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/eventsunder it, whileerror_reporting_enabledis true. It needsposthog_project_tokenset 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_hostset too. telemetry_enabled- Default
true - Allowed values
trueorfalse - Whether the server sends telemetry about itself: traces, log records and metrics to the OTLP endpoints, and exception reports to
posthog_host. Whenfalse, it sends none of them and keeps every telemetry setting as it is. otel_exporter_otlp_endpoint- Allowed values A secret: an absolute
httporhttpsURL, or empty - The base URL of the OTLP receiver. When set, the server exports traces to
v1/traces, log records tov1/logsand metrics tov1/metricsunder 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
httporhttpsURL, 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
httporhttpsURL, 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
httporhttpsURL, 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=valueHTTP 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=valueHTTP 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=valueHTTP 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=valueHTTP 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.nameinotel_resource_attributes. When both are empty, it ismarfa-server. Kept by this machine and carried by no archive. otel_resource_attributes- Allowed values Comma-separated
key=valuepairs 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
httporhttpsURL, or empty - The URL the server requests on a schedule while
heartbeat_enabledis true, so that something else can notice when the requests stop. When empty, there is no heartbeat. allow_private_addresses- Default
false - Allowed values
trueorfalse - Whether the server may send to loopback, private and other addresses that are not public: webhooks,
heartbeat_url,posthog_host, the three OTLP endpoints andobject_store_endpoint. Changing it needs a sign-in from the last fifteen minutes. enrichment_enabled- Default
true - Allowed values
trueorfalse - Whether the server extracts text from uploaded files.
enrichment_ocr_enabled- Default
true - Allowed values
trueorfalse - Whether the server reads text from images with OCR. When off, images are recorded as unsupported.
enrichment_max_blob_bytes- Default
20971520bytes - 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
67108864bytes - 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
1073741824bytes - 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://localhostwith the port the server listens on, whateverMARFA_LISTEN_HOSTis. It joinsaddresseswithout 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
trueorfalse - 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
60seconds - 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
26214400bytes - 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
1073741824bytes - 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
1073741824bytes - 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
104857600bytes - 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
7days - 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
30days - 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
90days - 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
90days - 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
365days - 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
30days - 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
30days - 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
90days - 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
365days - 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
60days - 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
30days - 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
1hour - 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
trueorfalse - 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
52428800bytes - 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
60seconds - 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
trueorfalse - Send exception reports to
posthog_host. heartbeat_enabled- Default
true - Allowed values
trueorfalse - Send scheduled requests to
heartbeat_url. update_check_enabled- Default
true - Allowed values
trueorfalse - 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"]}}}'| Lever | What it does | What the caller meets |
|---|---|---|
strict_mode | Refuses 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_allowlist | Lets only the listed sources create items of a type. | 403 forbidden, with details.type, details.source and details.allowed. |
source_filter | Leaves 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,nooroff, in any case - Start only the private control listener, without public HTTP or background jobs, for local recovery.
MARFA_CLAIM_ADDRESS- Allowed values An
httpsorigin, or anhttpone 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 allowshttponly onlocalhost,127.0.0.1or[::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,nooroff, 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
/setupwithout 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, setMARFA_TRUSTED_PROXY_HEADERandMARFA_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
httpsorigin, or anhttpone 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
cloudflaredbeside 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 filecloudflaredin the folder that holds its own executable, and it never searchesPATH(cloud/connector-beside,cloud/connector-no-path). A missing or unrunnable file is reported in the link'sconnector, and the server keeps serving. MARFA_TEST_HOOKS- Default
false - Allowed values
true,1,yes,on,false,0,nooroff, 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
0ms - 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, theX-Marfa-Contractheader and the document'sinfo.version. NeedsMARFA_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=valuepairs - Shortens a timing or a batch size the server fixes:
interval.<job>orinterval.*in milliseconds (neither reachesbackup, whose interval is the storedbackup_interval_seconds, andinterval.backupis refused),housekeeping_poll_ms,write_wait_ms,upload_idle_ms,blob_read_idle_ms,inbound_idle_msorconnector_hold_msin milliseconds, orenrichment_batch,blob_replicate_batch,blob_replicate_batch_bytes,blob_integrity_batchorblob_integrity_batch_bytes. NeedsMARFA_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_CONNECTIONShas 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-Forheader, or the headerMARFA_TRUSTED_PROXY_HEADERnames, the server believes. When empty,X-Forwarded-Foris 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-Foris 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.