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

# Configuration

> Every environment variable the control plane reads.

Custos reads process environment variables. It does not open a `.env` file itself — supply these
through whatever starts the binary: a shell, a systemd environment file or credential store,
container configuration, or a hosting platform.

The convention: `CUSTOS_`-prefixed variables are ours. Third-party credentials keep their own
upstream names (`RESEND_API_KEY`, the `OTEL_*` family).

## Required

| Variable | Notes |
| - | - |
| `CUSTOS_DATABASE_URL` | Postgres connection URL |
| `CUSTOS_MASTER_KEY` | from `custoscp gen-keys`; wraps per-secret data keys |
| `CUSTOS_SIGNING_PRIVATE_KEY` | from `custoscp gen-keys`; signs snapshots and secret sets |
| `CUSTOS_SERVER_TRANSPORT_PRIVATE_KEY` | from `custoscp gen-keys`; required only when `CUSTOS_ENCRYPTION` is on |

## Control plane

| Variable | Default | Notes |
| - | - | - |
| `CUSTOS_LISTEN_ADDR` | `:8080` | bind address |
| `CUSTOS_ENCRYPTION` | `true` | additional application-layer encryption of API request and response bodies |
| `CUSTOS_CORS_ORIGINS` | `*` | the public frontend origin |
| `CUSTOS_RELEASE_BASE` | public daemon artifact host | base URL for daemon release artifacts |
| `CUSTOS_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error`; logs are JSON on stderr |

<Note>
  `CUSTOS_ENCRYPTION` is Custos's own hybrid X25519 payload sealing between the API and its clients. It
  is separate from HTTPS/TLS and from at-rest vault encryption, and turning it off disables neither.
  It is commonly off in local development.
</Note>

## Invitations, password resets, and email

| Variable | Notes |
| - | - |
| `CUSTOS_APP_URL` | base URL used to build invite and reset links |
| `CUSTOS_EMAIL_FROM` | a Resend-verified sender, e.g. `Custos <custos@example.com>` |
| `RESEND_API_KEY` | leave empty in development and the link is printed to the logs instead |

## OpenTelemetry

Setting the one general endpoint enables logs, traces, and metrics over OTLP HTTP/protobuf. The
exporters append `/v1/logs`, `/v1/traces`, or `/v1/metrics` as appropriate.

| Variable | Default | Notes |
| - | - | - |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | base endpoint; enables all three signals |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | unset | complete URL, normally including its `/v1/...` path |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | unset | as above |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | unset | as above |
| `OTEL_EXPORTER_OTLP_HEADERS` | unset | e.g. `authorization=Bearer <token>` |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | `10000` | milliseconds |
| `OTEL_METRIC_EXPORT_INTERVAL` | `60000` | milliseconds; applies to the daemon too |

Use the signal-specific variables only when exporting selected signals, and leave the general
endpoint empty. If every endpoint is empty, OTLP export is disabled and JSON logs still go to
stderr.

Daemons need no OTLP variables of their own — see [Observability](/custos/custos/operations/observability).

## Client-side value

`CUSTOS_SERVER_TRANSPORT_PUBLIC_KEY` is generated by `custoscp gen-keys` and configured on every
client that calls the API — for the web app, as a container environment variable. The control-plane
process never reads it.


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