# Instance settings (/reference/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](/run/settings) shows how. **Start-only settings** are environment variables the server reads when it starts.

## Stored settings [#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`.

| Key | Default | Allowed values | What it sets |
| - | - | - | - |
| `disk_reserve_bytes` | `134217728` bytes | 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` | `1048576` bytes | 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` | `16777216` bytes | 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` | `1` | Whole number, 1 to 1000000 | The fewest live copies a blob keeps. A drop that would leave fewer is refused. |
| `blob_cleanup_enabled` | `true` | `true` or `false` | Whether the `blob-orphans` job sweeps for unreferenced blobs. When off, no blob is reported or purged. |
| `blob_cleanup_grace_seconds` | `86400` seconds | 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` | `3600` seconds | 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` | None | 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` | None | 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` | `us-east-1` | 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` | None | 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` | `true` | `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` | `marfa` | `/`-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` | None | Text of 1 to 256 characters, or empty | The access key ID for the object store. |
| `object_store_secret_access_key` | None | 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` | None | 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` | None | 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` | `true` | `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` | None | 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` | None | 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` | None | 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` | None | 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` | None | 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` | None | 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` | None | 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` | None | 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` | `0.05` | 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` | None | 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` | None | 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` | None | 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` | `false` | `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` | `true` | `true` or `false` | Whether the server extracts text from uploaded files. |
| `enrichment_ocr_enabled` | `true` | `true` or `false` | Whether the server reads text from images with OCR. When off, images are recorded as unsupported. |
| `enrichment_max_blob_bytes` | `20971520` bytes | 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` | `100000` | 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` | `67108864` bytes | 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` | `1073741824` bytes | 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` | `3` | Whole number, 1 to 100 | How many times the server tries to extract text from a failing item before it stops. |
| `sign_in_address` | None | 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` | None | 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` | `true` | `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` | `4000` | Whole number, 1 to 1000000 | The requests one key or app may make to all operations together in each window. |
| `rate_limit_window_seconds` | `60` seconds | Whole number of seconds, 1 to 86400 | The length of a rate-limit window. |
| `rate_limit_keys_requests` | `200` | Whole number, 1 to 1000000 | The requests one credential may make in each window to the operations under `/keys`. |
| `inbound_max_bytes` | `26214400` bytes | Whole number of bytes, 1 to 1099511627776 | The largest inbound webhook delivery the server stores. |
| `rate_limit_inbound_requests` | `600` | Whole number, 1 to 1000000 | The deliveries one inbound endpoint accepts in each rate-limit window. |
| `inbound_backlog_deliveries` | `10000` | Whole number, 1 to 1000000 | The unhandled deliveries one registration may hold before the server refuses more deliveries for it. |
| `inbound_backlog_bytes` | `1073741824` bytes | 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` | `10000` | Whole number, 1 to 1000000 | The most deliveries the server retains across live and retired endpoints. |
| `inbound_retained_bytes` | `1073741824` bytes | Whole number of bytes, 1 to 1099511627776 | The most bytes of deliveries the server retains across live and retired endpoints. |
| `inbound_in_flight_bytes` | `104857600` bytes | 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` | `7` days | 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` | `30` days | 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` | `90` days | 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` | `90` days | 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` | `365` days | 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` | `30` days | 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` | `30` days | Whole number of days, 0 to 36500 | The window in which the version policy keeps every version of an item. |
| `version_daily_snapshot_days` | `90` days | 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` | `365` days | 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` | `500` | Whole number, 1 to 1000000 | The most versions the version policy keeps for one item. |
| `trash_retention_days` | `60` days | 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` | `30` days | 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` | `1` hour | 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` | `0` | 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` | `true` | `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` | `52428800` bytes | 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` | `60` seconds | 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` | `true` | `true` or `false` | Send exception reports to `posthog_host`. |
| `heartbeat_enabled` | `true` | `true` or `false` | Send scheduled requests to `heartbeat_url`. |
| `update_check_enabled` | `true` | `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` | None | 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-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`:

```bash
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](/reference/cli) says.

## Start-only settings [#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.

| Setting | Default | Allowed values | What it sets |
| - | - | - | - |
| `MARFA_PORT` | `8600` | Whole number, 0 to 65535 | The port the server listens on. Zero lets the operating system assign a port. |
| `MARFA_LISTEN_HOST` | None | Any text | 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` | `./data/marfa.db` | Any text | 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` | None | Any text | 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` | `false` | `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` | None | 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` | `false` | `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` | `https://cloud.marfa.so` | 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` | `cloudflared` beside the server's own executable | 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` | `false` | `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` | `0` ms | 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` | The build's contract version | 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` | None | 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` | `1024` | 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` | `256` | 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` | `./data/blobs` | Any text | The folder of the disk store, where every upload lands. |
| `MARFA_ENRICHMENT_TESSDATA_DIR` | None | Any text | A folder of OCR language models. |
| `MARFA_TRUSTED_PROXY_CIDRS` | None | 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` | None | 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` | None. Generated on first start into `marfa.secrets`. | 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` | None. Generated on first start into `marfa.secrets`. | 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](/run/telemetry) shows them, and [Give your instance an address](/run/address#behind-a-proxy-of-your-own) the proxy settings.
