Configuration

Monospace Server can be configured using environment variables or a config.yaml file. Environment variables are prefixed with MONOSPACE_.

Boolean environment variables accept true, 1, yes, or on for true and false, 0, no, or off for false, regardless of capitalization. Any other value causes a startup error that names the invalid key.

These aliases apply only to environment variables. In config.yaml, use YAML booleans; cookie_secure: "yes" is an error.

Server

Durations accept human-readable strings such as 15s, 5m, and 2h 30m.

License

Monospace runs on the built-in Starter license until you configure one of the variables below. Set one or the other, never both. See Licensing for activation, revalidation, the startup usage check, and license status.

Setting both variables fails startup. When a key is activated, Monospace sends MONOSPACE_BASE_URL to the licensing service as the instance's public URL.

Cache and Redis-Compatible Storage

Caching is enabled by default, and requires Redis-compatible storage. Monospace supports Redis 7.4 and later, and Valkey 7.2 and later.

See Caching for eligible reads, freshness behavior, bypass headers, and Redis memory guidance.

Configure the connection URL

redis:
  url: redis://cache.example.com:6379
  prefix: "monospace:"
  connection_timeout: 2s
  response_timeout: 1s
  # Redis may be configured at runtime through Monospace.
  config_set:
    maxmemory: 100mb
    maxmemory-policy: volatile-lru

cache:
  enabled: true
  include_status_header: false
  ttl: 5m
  max_entry_size: 8m

Redis and Valkey URLs use this form:

{redis|valkey|rediss|valkeys}://[username[:password]@]host[:port][/db]

Monospace always uses RESP3. Append #insecure only to rediss or valkeys URLs for unverified TLS.

Configure TLS settings

Use rediss or valkeys for TLS. The default trusted roots verify the server certificate unless you configure a custom CA.

This configuration replaces the default trusted roots and supplies a mutual TLS identity:

redis:
  url: rediss://cache.example.com:6379
  tls:
    ca_cert: !file /run/secrets/redis-ca.pem
    client_cert: !file /run/secrets/redis-client.pem
    client_key: !file /run/secrets/redis-client-key.pem
    client_key_password: change-me

Certificate fields accept PEM or DER content as base64, or a file reference. Client keys accept PKCS#8, PKCS#1 RSA, and SEC1 EC in PEM or DER form. Encrypted PKCS#8 keys require client_key_password.

Appending #insecure to a TLS URL disables certificate and hostname verification, and disables SNI.

Transactions

Monospace logs one warning when a transaction remains open beyond the configured threshold after attempting a mutation. This warning identifies long-running transactions that delay query-cache invalidation and retain data-source resources.

transaction:
  long_running_mutation_warning_threshold: 30s

System Database

Configures the database Monospace uses to store its own metadata (workspaces, roles, policies, etc.). Currently supports PostgreSQL.

PostgreSQL Provider

SSL Configuration

File Storage

Configures where Monospace stores uploaded files and assets.

Local Provider

S3 Provider

Compatible with AWS S3 and S3-compatible services (MinIO, Cloudflare R2, etc.).

Email

Configures outbound email for invitations, password resets, and notifications.

SMTP Provider

Message Queue (RabbitMQ)

Monospace uses RabbitMQ for internal event processing.

Clustering

Runs several replicas against one system database. Requires PostgreSQL, RabbitMQ, and shared file storage. Clustered mode is on by default. See Horizontal Scaling for the deployment requirements.

Durations accept human-readable strings such as 15s, 5m, and 2h 30m.

Authentication & Tokens

Duration values use human-readable format: 15m, 30s, 7days, 1h, etc.

Cookies

Limits

Extensions

Extensions are in preview. See Extensions for how Monospace loads them.

Encryption (KMS)

Configures the Key Management Service used to encrypt sensitive values stored in the database.

Content Security Policy

CORS

Controls the Cross-Origin Resource Sharing headers the engine sends. CORS is disabled by default — the engine sends no CORS headers until you enable it. Enable it to let browser clients on other origins call your API.

The default methods, headers, credentials, and max age above apply when MONOSPACE_CORS__ENABLED is true and the variable is left unset.

Observability

When MONOSPACE_ENABLE_OTEL_EXPORT is enabled, configure the collector endpoint using standard OpenTelemetry environment variables (e.g., OTEL_EXPORTER_OTLP_ENDPOINT). Traces and metrics are exported over OTLP/HTTP.

Metrics cover query execution and inbound HTTP requests.

Telemetry

The Starter license requires scheduled telemetry. When the active license requires it, Monospace ignores MONOSPACE_TELEMETRY__ENABLED=false and logs a warning.