Reference

Configuration

Configuring your Monospace environment.

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

For nested configurations, double underscores (__) are used to separate levels.

Server

Variable	Type	Default	Description
`MONOSPACE_HOST`	string	`127.0.0.1`	Address the server binds to
`MONOSPACE_PORT`	integer	`8100`	Port the server listens on
`MONOSPACE_BASE_URL`	URL	`http://localhost:3000/`	Public base URL used in emails, OAuth redirects, and generated links
`MONOSPACE_SERVE_STATIC_DIR`	string	`./public`	Directory to serve static files from. Defaults to the `public` folder next to the server binary

System Database

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

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_DATABASE__PROVIDER`	string	—	Database provider. Currently: `postgres`

PostgreSQL Provider

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_DATABASE__HOST`	string	—	Database hostname
`MONOSPACE_SYSTEM_DATABASE__PORT`	integer	—	Database port
`MONOSPACE_SYSTEM_DATABASE__USER`	string	—	Database username
`MONOSPACE_SYSTEM_DATABASE__PASSWORD`	string	—	Database password
`MONOSPACE_SYSTEM_DATABASE__DBNAME`	string	—	Database name

SSL Configuration

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_DATABASE__SSL__MODE`	string	`require`	SSL mode: `disable`, `prefer`, `require`, `verify-ca`, `verify-full`
`MONOSPACE_SYSTEM_DATABASE__SSL__CA_CERT`	string	—	CA certificate (base64-encoded or file path)
`MONOSPACE_SYSTEM_DATABASE__SSL__CLIENT_CERT`	string	—	Client certificate (base64-encoded)
`MONOSPACE_SYSTEM_DATABASE__SSL__CLIENT_KEY`	string	—	Client private key (base64-encoded)
`MONOSPACE_SYSTEM_DATABASE__SSL__CLIENT_KEY_PASSWORD`	string	—	Password for encrypted client key

File Storage

Configures where Monospace stores uploaded files and assets.

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_FILE_STORAGE__PROVIDER`	string	—	Storage provider: `local` or `s3`
`MONOSPACE_REDIRECT_ASSET_READ`	boolean	`false`	Redirect asset reads to the file storage provider instead of proxying through the server

Local Provider

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_FILE_STORAGE__ROOT_PATH`	string	—	Absolute path to the directory where files are stored

S3 Provider

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

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_FILE_STORAGE__BUCKET`	string	—	S3 bucket name
`MONOSPACE_SYSTEM_FILE_STORAGE__ACCESS_KEY_ID`	string	—	AWS access key ID
`MONOSPACE_SYSTEM_FILE_STORAGE__SECRET_ACCESS_KEY`	string	—	AWS secret access key
`MONOSPACE_SYSTEM_FILE_STORAGE__REGION`	string	`auto`	AWS region
`MONOSPACE_SYSTEM_FILE_STORAGE__ENDPOINT`	string	—	Custom endpoint URL (for S3-compatible services)
`MONOSPACE_SYSTEM_FILE_STORAGE__ROOT_PATH`	string	—	Prefix path within the bucket

Email

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

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_EMAILER__PROVIDER`	string	—	Email provider: `smtp`
`MONOSPACE_SYSTEM_EMAILER__FROM_ADDRESS`	string	—	Sender email address in the "From" header
`MONOSPACE_SYSTEM_EMAILER__FROM_NAME`	string	—	Display name in the "From" header

SMTP Provider

Variable	Type	Default	Description
`MONOSPACE_SYSTEM_EMAILER__HOST`	string	—	SMTP server hostname
`MONOSPACE_SYSTEM_EMAILER__PORT`	integer	—	SMTP server port (typically 25, 465, or 587)
`MONOSPACE_SYSTEM_EMAILER__USERNAME`	string	—	SMTP authentication username
`MONOSPACE_SYSTEM_EMAILER__PASSWORD`	string	—	SMTP authentication password
`MONOSPACE_SYSTEM_EMAILER__TLS_OFF`	boolean	`false`	Set to `true` to disable TLS

Message Queue (RabbitMQ)

Monospace uses RabbitMQ for internal event processing.

Variable	Type	Default	Description
`MONOSPACE_RABBITMQ__HOST`	string	—	RabbitMQ hostname
`MONOSPACE_RABBITMQ__PORT`	integer	`5672`	RabbitMQ port
`MONOSPACE_RABBITMQ__USER`	string	—	RabbitMQ username
`MONOSPACE_RABBITMQ__PASSWORD`	string	—	RabbitMQ password
`MONOSPACE_RABBITMQ__VHOST`	string	`/`	RabbitMQ virtual host
`MONOSPACE_RABBITMQ__USE_TLS`	boolean	`false`	Use AMQPS instead of AMQP

Authentication & Tokens

Variable	Type	Default	Description
`MONOSPACE_ACCESS_TOKEN_TTL`	duration	`15m`	Access token validity period
`MONOSPACE_REFRESH_TOKEN_TTL`	duration	`7days`	Refresh token validity period
`MONOSPACE_RESET_PASSWORD_TOKEN_TTL`	duration	`15m`	Password reset token validity period
`MONOSPACE_RESET_PASSWORD_COOLDOWN_TTL`	duration	`30s`	Cooldown before a user can request another password reset
`MONOSPACE_INVITE_TOKEN_TTL`	duration	`7days`	Invite token validity period
`MONOSPACE_JWT_LEEWAY`	integer	`60`	JWT clock skew tolerance in seconds
`MONOSPACE_JWT_PRIVATE_KEY`	string	—	Ed25519 private key for JWT signing (PEM content or file path)
`MONOSPACE_JWT_PUBLIC_KEY`	string	—	Ed25519 public key for JWT verification (PEM content or file path)

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

Cookies

Variable	Type	Default	Description
`MONOSPACE_SESSION_COOKIE_NAME`	string	`monospace_session`	Name of the session cookie
`MONOSPACE_REFRESH_COOKIE_NAME`	string	`monospace_refresh`	Name of the refresh token cookie
`MONOSPACE_COOKIE_SECURE`	boolean	`true`	Set the `Secure` flag on cookies. Set to `false` for local development over HTTP

Limits

Variable	Type	Default	Description
`MONOSPACE_QUERY_LIMIT_DEFAULT`	integer	`100`	Default page size when no limit is specified
`MONOSPACE_QUERY_LIMIT_MAX`	integer	—	Maximum allowed page size. No limit if unset
`MONOSPACE_QUERY_BATCH_SIZE`	integer	—	Batch size for bulk operations
`MONOSPACE_QUERY_LIMIT_MAX_FEDERATED`	integer	`1000`	Maximum records fetched in a single cross-source relational query
`MONOSPACE_MAX_PAYLOAD_SIZE`	string	`2m`	Maximum request payload size. Supports `g`, `m`, `k` suffixes (bytes without suffix)
`MONOSPACE_MAX_FILE_PAYLOAD_SIZE`	string	`5m`	Maximum file upload size. Supports `g`, `m`, `k` suffixes (bytes without suffix)

Encryption (KMS)

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

Variable	Type	Default	Description
`MONOSPACE_KMS__TYPE`	string	—	KMS type. Currently: `monospace` (local encryption)
`MONOSPACE_KMS__MASTER_KEY`	string	—	Base64-encoded master encryption key
`MONOSPACE_KMS__MASTER_KEY__FILE`	string	—	Path to a file containing the master key

Content Security Policy

Variable	Type	Default	Description
`MONOSPACE_CONTENT_SECURITY_POLICY__ENABLED`	boolean	`true`	Enable Content-Security-Policy headers
`MONOSPACE_CONTENT_SECURITY_POLICY__DIRECTIVES__*`	string	—	Override individual CSP directives

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.

Variable	Type	Default	Description
`MONOSPACE_CORS__ENABLED`	boolean	`false`	Send CORS headers. The variables below apply only when enabled
`MONOSPACE_CORS__ORIGIN`	string	—	Allowed origins. Use `true` to mirror the request origin, `*` for any origin, or a comma-separated list of origins
`MONOSPACE_CORS__METHODS`	string	`GET, POST, PATCH, DELETE`	Allowed request methods
`MONOSPACE_CORS__ALLOWED_HEADERS`	string	`Content-Type, Authorization`	Allowed request headers. `*` allows any header
`MONOSPACE_CORS__EXPOSED_HEADERS`	string	`Content-Range`	Response headers exposed to the browser
`MONOSPACE_CORS__CREDENTIALS`	boolean	`true`	Allow credentialed requests (cookies, `Authorization` header)
`MONOSPACE_CORS__MAX_AGE`	duration	`18000s`	How long a browser may cache the preflight response

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

A wildcard origin, method, or header cannot be combined with MONOSPACE_CORS__CREDENTIALS=true. The engine rejects this configuration at startup. Name explicit origins when you need to allow credentials.

Observability

Variable	Type	Default	Description
`MONOSPACE_LOG`	string	`info`	Log level filter using tracing `EnvFilter` syntax. Examples: `debug`, `info,aide=warn`, `monospace=trace`
`MONOSPACE_LOG_FORMAT`	string	`json`	Log output format: `compact`, `full`, `pretty`, or `json`. An invalid value fails startup
`MONOSPACE_ENABLE_OTEL_EXPORT`	boolean	`false`	Export traces to an OpenTelemetry collector

When MONOSPACE_ENABLE_OTEL_EXPORT is enabled, configure the collector endpoint using standard OpenTelemetry environment variables (e.g., OTEL_EXPORTER_OTLP_ENDPOINT).

Telemetry

Variable	Type	Default	Description
`MONOSPACE_TELEMETRY__ENABLED`	boolean	`true`	Set to `false` to disable scheduled anonymous usage telemetry
`MONOSPACE_INSTANCE_OWNER_SYNC_ENABLED`	boolean	`true`	Set to `false` to opt out of syncing instance-owner details for compliance telemetry

Advanced

Handle composite keys, dynamic collections, and other special cases.

Connectors

Supported database connectors and their configuration options.