> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vexlo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Deployment settings, environment variables and capture policy controls.

Use [Install and run](https://docs.vexlo.ai/deployment/install.md) for startup.

## Server settings

`vexlo serve` and `vexlo check` accept the same server configuration. `check` validates that
configuration and estimates capacity without opening execution storage.

| Flag | Environment variable | Default / requirement |
| - | - | - |
| `-api-addr` | `VEXLO_API_ADDR` | `127.0.0.1:8080` |
| `-db-path` | `VEXLO_DB_PATH` | `vexlo.db` under the data directory |
| `-value-store-dir` | `VEXLO_VALUE_STORE_DIR` | `values` under the data directory |
| `-shape-retention-days` | None | `7`, positive integer |
| `-value-budget-bytes` | None | `21474836480` (20 GiB), positive integer |
| `-allow-overcommit` | None | `false`; accept a value budget greater than the volume's total capacity |
| `-tls-cert` | `VEXLO_TLS_CERT_FILE` | Certificate file; required with key for non-loopback TLS |
| `-tls-key` | `VEXLO_TLS_KEY_FILE` | Private-key file paired with certificate |
| `-allow-insecure-http` | `VEXLO_ALLOW_INSECURE_HTTP` | `false`; allow a non-loopback plaintext listener |
| `-no-auth` | `VEXLO_NO_AUTH` | `false`; disabling auth forces a loopback listener |
| `-team` | `VEXLO_TEAM` | `default`; team used under `-no-auth` |
| `-header-trust` | `VEXLO_HEADER_TRUST` | `false`; accept trusted proxy headers for read access |
| `-header-trust-secret` | `VEXLO_HEADER_TRUST_SECRET` | Required when header trust is enabled |

The data directory is `VEXLO_DATA_DIR`, falling back to `~/.vexlo/data`. Token commands use
that directory through `-data-dir` or `VEXLO_DATA_DIR`; the server also accepts independent
database and value paths. Keep token administration pointed at the server's actual database.

See [Authentication](https://docs.vexlo.ai/deployment/authentication.md) for credentials and transport security, and
[Retention](https://docs.vexlo.ai/deployment/retention.md) for stored-data lifetimes.

## Relay settings

The relay and SDK must use the same queue directory. The endpoint is the server's base URL;
the credential must have the ingest role.

| Flag | Environment variable | Default / requirement |
| - | - | - |
| `-spool-dir` | `VEXLO_SPOOL_DIR` | `~/.vexlo` |
| `-spool-budget-bytes` | None | `2147483648` (2 GiB) |
| `-destination` | `VEXLO_ENDPOINT` | Required server base URL |
| `-token` | `VEXLO_INGEST_TOKEN` | Required ingest credential |
| `-environment` | `VEXLO_ENVIRONMENT` | Unset |
| `-health-addr` | `VEXLO_HEALTH_ADDR` | `127.0.0.1:9101` |
| `-allow-insecure-http` | `VEXLO_ALLOW_INSECURE_HTTP` | `false`; allow non-loopback HTTP destination |
| `-poll-interval` | None | `250ms` |
| `-heartbeat-interval` | None | `30s` |
| `-retention-interval` | None | `1m` |
| `-finality-grace` | None | `5m` after a queue hour ends |
| `-writer-ttl` | None | `24h` for idle writer metadata eligible for retirement |
| `-max-writers` | None | `10000` tracked writer IDs |
| `-destination-file` | `VEXLO_ENDPOINT_FILE` | Unset; source for destination reload |
| `-token-file` | `VEXLO_INGEST_TOKEN_FILE` | Unset; source for token reload |

The optional environment label is sent as `X-Vexlo-Environment`. It accepts 1–64 printable
ASCII characters excluding commas. It does not select the team: the ingest token supplies
that boundary.

`relay status` accepts `-spool-dir` and `-spool-budget-bytes`. It reads queue status without
requiring a running relay. `/healthz` and `/metrics` use the relay's health listener, separate
from the server API.

## Environment resolution

For relay and server boolean environment settings, empty, `0` and `false` mean false;
`false` is case-insensitive. Other nonempty values mean true. A true environment value is
still applied when the corresponding flag is false, so set the environment variable to `0`
to turn that setting off.

For paths and credentials, a nonempty explicit flag takes precedence over its environment
fallback. Unset storage paths then resolve to the defaults listed above.

## Reload the relay destination or token

Configure `-destination-file`, `-token-file`, or both at startup to enable reload. Each file
contains one destination URL or token. Send `SIGHUP` to the relay after updating the file.
The relay trims surrounding whitespace, validates the new configuration and retains the old
configuration if validation fails.

These files do not supply startup values. Provide `-destination` / `VEXLO_ENDPOINT` and
`-token` / `VEXLO_INGEST_TOKEN` at startup as well. Changing another shell's environment does
not update a running relay. A `SIGHUP` without either file setting is refused.

## Capture policy

`vexlo policy set` writes a whole policy through the server. It uses an ingest token and the
server URL from `VEXLO_INGEST_TOKEN` and `VEXLO_ENDPOINT`, or their explicit command flags.
Add `-service` to target one service; omit it for the team's default. Team scope comes from
the token, not another command argument.

| Required flag | Server accepts | Python SDK effect |
| - | - | - |
| `-enabled` | Capture enabled/disabled | Can disable capture within the local `init()` ceiling |
| `-value-sample-rate` | A fraction from `0` to `1` | Lowers the fraction of traces retaining values |
| `-max-value-bytes` | A positive maximum in bytes | Accepted and relayed, but currently does not change Python capture's 16 KiB bound |
| `-capture-logs` | Log capture enabled/disabled | Can disable logs; cannot enable logs disabled locally |

Supply all four flags, using `=false` for a false boolean. The Python SDK does not enforce
policy `max_value_bytes`; its value bound remains 16 KiB. Do not use this field to enforce a
smaller data boundary.

The Python SDK also recognizes policy restrictions for `capture_values` and
`capture_error_message`. The current server/relay administrative interface does not expose
those fields. Configure them locally through `init()` when you need that restriction.

### Policy freshness and fallback

The relay receives service policy through heartbeats and writes it for the SDK. The Python
SDK checks its policy cache on a one-second cadence. A missing, unreadable or malformed policy,
a missing or invalid `updated_at`, or a timestamp older than 300 seconds causes fallback to
the configuration supplied to `init()`.

A remote restriction therefore does not remain enforced indefinitely during a delivery
outage. Put required data restrictions in local SDK configuration; a service policy can
lower that ceiling while it remains usable, but cannot replace it.

`policy show` reads the server's resolved policy through a heartbeat. It shows the configured
policy, not a measurement that each application process has received or enforced it.
See [Capture controls](https://docs.vexlo.ai/instrumentation/capture.md) for local data-handling decisions.

## Capacity check

| `vexlo check` flag | Default | Meaning |
| - | - | - |
| `-expected-write-rate` | `2` | Expected sustained traces per second used in the estimate |

`-expected-write-rate` affects `check`, not `serve`. The check estimates value retention using
fixed bytes per trace rather than measuring application traffic. Values expiring before call
records are reported without failing the check.

Both commands reject a value budget greater than the total capacity of its volume unless
`-allow-overcommit` is set. A budget greater than current free space only produces a warning.
See [Retention](https://docs.vexlo.ai/deployment/retention.md) for capacity planning.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.