Configuration Reference

Overview

Self-hosted Mistle deployments are configured with a TOML file plus optional environment overrides. Use config/config.sample.toml as the complete reference for the resource-oriented TOML shape. Set MISTLE_CONFIG_PATH to the TOML file path used by each service. Current resource-oriented MISTLE_* environment variables can override TOML values after the file is loaded.

Deployment Shape

A simple deployment can point the control plane and data plane at the same Postgres, PgBouncer, Valkey, and object storage instances. Larger deployments can split those resources by plane. The config file keeps these shared resources separate from individual service settings:

Section	Purpose
`services.*`	Service hosts, ports, public URLs, internal URLs, and service-owned settings
`postgres.*`	Plane-specific Postgres URLs
`kv.*`	Plane-specific Valkey configuration
`object_store.*`	Shared object stores
`workflow.*`	OpenWorkflow namespaces
`email.smtp`	SMTP delivery settings
`internal_auth`	Service-to-service authentication
`sandbox.*`	Sandbox provider, base image, publish, and token settings
`telemetry.*`	OpenTelemetry export settings

Services

Service sections define where each service listens and how other services reach it.

Section	Required settings
`services.dashboard`	`public_url`, `control_plane_api_origin`
`services.control_plane_api`	`host`, `port`, `public_url`, `internal_url`
`services.data_plane_api`	`host`, `port`, `internal_url`
`services.data_plane_gateway`	`host`, `port`, `internal_url`, sandbox WebSocket URLs
`services.control_plane_worker`	`workflow_concurrency`, `workflow_database_pool_max`
`services.data_plane_worker`	`workflow_concurrency`, `workflow_database_pool_max`

Use public URLs for browser-facing and provider-facing traffic. Use internal URLs for service-to-service traffic inside the deployment network.

Postgres

Postgres is configured separately for the control plane and data plane.

Field	Used for
`direct_url`	Migrations and other direct database ownership tasks
`pooled_url`	Runtime application traffic through PgBouncer

Simple deployments can set both planes to the same database. Split deployments can use separate databases for postgres.control_plane and postgres.data_plane.

KV

kv.data_plane describes the data-plane Valkey dependency used by the gateway runtime-state layer. kv.control_plane is available for future control-plane Valkey use, but no service requires it today. Only valkey is supported today:

[kv.data_plane]
backend = "valkey"
url = "redis://valkey:6379"
key_prefix = "mistle:runtime-state"

Object Stores

object_store.assets stores application assets.

Authentication

Control-plane user authentication is configured under services.control_plane_api.auth. enabled_methods controls which login methods are available. otp is required by the current runtime. Add google or github only when the matching OAuth provider is configured:

[services.control_plane_api.auth]
enabled_methods = ["otp", "google", "github"]
allow_signups = true

Set allow_signups = false to let existing users continue signing in while blocking first-time OTP, Google, and GitHub users from creating accounts. Service-to-service auth is configured under internal_auth. The method field is currently optional and kept for future expansion; the runtime uses shared-token auth while using internal_auth.shared_token.token.

Workflows

Workflow config is split by plane:

[workflow.control_plane]
namespace_id = "production"

[workflow.data_plane]
namespace_id = "production"

Workers consume the namespace and their service-specific concurrency. Managed deployments should run database and workflow migrations as deployment steps instead of relying on long-lived worker startup.

Sandbox

Managed sandbox providers are enabled per provider section. Docker is enabled with sandbox.docker.enabled = true plus its socket settings. E2B is enabled with sandbox.e2b.enabled = true plus its API credentials. A provider is available as a managed provider only when it is enabled and its required provider config is present.

Environment Overrides

TOML should be the primary authored config. Environment variables are override inputs for deployment systems and secret managers.

set MISTLE_CONFIG_PATH to the config file path
use the resource-oriented MISTLE_POSTGRES_*, MISTLE_KV_*, MISTLE_SERVICES_*, and related MISTLE_* environment namespaces
internal-only and test-only overrides, such as MISTLE_INTERNAL_AUTH_* and MISTLE_TEST_SANDBOXD_TEST_FAULTS_ENABLED, are also supported when needed.

Environment overrides win when both TOML and env provide the same runtime setting.

Full TOML Key Reference

This table covers the operator-facing TOML keys accepted by @mistle/config.

Key	Required	Notes
`global.env`	Yes	`development` or `production`.
`telemetry.enabled`	Yes	Enables or disables telemetry export.
`telemetry.debug`	Yes	Enables debug telemetry behavior.
`telemetry.resource_attributes`	No	OpenTelemetry resource attributes string.
`telemetry.traces.endpoint`	Yes when telemetry is enabled	Optional when telemetry is disabled.
`telemetry.logs.endpoint`	Yes when telemetry is enabled	Optional when telemetry is disabled.
`telemetry.metrics.endpoint`	Yes when telemetry is enabled	Optional when telemetry is disabled.
`services.dashboard.public_url`	Yes	Public dashboard origin.
`services.dashboard.control_plane_api_origin`	Yes	Browser-facing control-plane API origin used by the dashboard build.
`services.dashboard.posthog.enabled`	No	Managed-cloud only. Self-hosted deployments should leave this commented out.
`services.dashboard.posthog.project_api_key`	Required when PostHog is enabled	Managed-cloud only. PostHog project API key.
`services.dashboard.posthog.host`	Required when PostHog is enabled	Managed-cloud only. PostHog ingestion host.
`services.control_plane_api.host`	Yes	Bind host.
`services.control_plane_api.port`	Yes	Bind port.
`services.control_plane_api.public_url`	Yes	Public control-plane API URL.
`services.control_plane_api.internal_url`	Yes	Internal control-plane API URL.
`services.control_plane_api.auth.secret`	Yes	Auth signing secret.
`services.control_plane_api.auth.trusted_origins`	Yes	Allowed dashboard/browser origins.
`services.control_plane_api.auth.enabled_methods`	No	Supported values: `otp`, `google`, `github`. Social providers require credentials. If omitted, only OTP is exposed to users.
`services.control_plane_api.auth.allow_signups`	No	Whether first-time OTP, Google, and GitHub sign-ins may create users. Defaults to `true`.
`services.control_plane_api.auth.otp.length`	Yes	OTP code length.
`services.control_plane_api.auth.otp.expires_in_seconds`	Yes	OTP expiry.
`services.control_plane_api.auth.otp.allowed_attempts`	Yes	Maximum OTP attempts.
`services.control_plane_api.auth.google.client_id`	Required when Google auth is enabled	Google OAuth client ID.
`services.control_plane_api.auth.google.client_secret`	Required when Google auth is enabled	Google OAuth client secret.
`services.control_plane_api.auth.github.client_id`	Required when GitHub auth is enabled	GitHub OAuth app client ID.
`services.control_plane_api.auth.github.client_secret`	Required when GitHub auth is enabled	GitHub OAuth app client secret.
`services.control_plane_api.integrations.active_master_encryption_key_version`	Yes	Active integration credential key version.
`services.control_plane_api.integrations.master_encryption_keys.<version>`	Yes	One or more positive integer string versions.
`services.data_plane_api.host`	Yes	Bind host.
`services.data_plane_api.port`	Yes	Bind port.
`services.data_plane_api.internal_url`	Yes	Internal data-plane API URL.
`services.data_plane_gateway.host`	Yes	Bind host.
`services.data_plane_gateway.port`	Yes	Bind port.
`services.data_plane_gateway.internal_url`	Yes	Internal data-plane gateway URL.
`services.data_plane_gateway.sandbox_ws_public_url`	Yes	Public sandbox WebSocket tunnel URL.
`services.data_plane_gateway.sandbox_ws_internal_url`	Yes	Internal sandbox WebSocket tunnel URL.
`services.data_plane_gateway.port_access.authorization_timeout_ms`	No	Sandbox target authorization timeout in milliseconds. Defaults to `5000`.
`services.control_plane_worker.workflow_concurrency`	Yes	Control-plane workflow worker concurrency.
`services.control_plane_worker.workflow_database_pool_max`	Yes	Maximum direct Postgres connections for the control-plane worker OpenWorkflow pool.
`services.data_plane_worker.workflow_concurrency`	Yes	Data-plane workflow worker concurrency.
`services.data_plane_worker.workflow_database_pool_max`	Yes	Maximum direct Postgres connections for the data-plane worker OpenWorkflow pool.
`workflow.control_plane.namespace_id`	Yes	Control-plane workflow namespace.
`workflow.data_plane.namespace_id`	Yes	Data-plane workflow namespace.
`postgres.control_plane.direct_url`	Yes	Direct control-plane Postgres URL for migrations.
`postgres.control_plane.pooled_url`	Yes	Pooled control-plane Postgres URL for runtime traffic.
`postgres.data_plane.direct_url`	Yes	Direct data-plane Postgres URL for migrations.
`postgres.data_plane.pooled_url`	Yes	Pooled data-plane Postgres URL for runtime traffic.
`kv.control_plane.backend`	No	Optional control-plane Valkey backend. Currently `valkey` when set.
`kv.control_plane.url`	Required when `kv.control_plane` is set	Control-plane Valkey URL.
`kv.control_plane.key_prefix`	Required when `kv.control_plane` is set	Control-plane Valkey key prefix.
`kv.data_plane.backend`	Yes	Currently `valkey`.
`kv.data_plane.url`	Yes	Data-plane Valkey URL.
`kv.data_plane.key_prefix`	Yes	Data-plane Valkey key prefix.
`object_store.assets.bucket_name`	Yes	Asset object store bucket.
`object_store.assets.region`	Yes	Asset object store region.
`object_store.assets.endpoint`	No	Custom object store endpoint.
`object_store.assets.force_path_style`	No	S3 path-style setting.
`object_store.assets.access_key_id`	Yes	Asset object store access key.
`object_store.assets.secret_access_key`	Yes	Asset object store secret key.
`email.smtp.from_address`	Yes	SMTP sender address.
`email.smtp.from_name`	Yes	SMTP sender name.
`email.smtp.host`	Yes	SMTP host.
`email.smtp.port`	Yes	SMTP port.
`email.smtp.secure`	Yes	Whether SMTP uses TLS.
`email.smtp.username`	Yes	SMTP username.
`email.smtp.password`	Yes	SMTP password.
`internal_auth.method`	No	Optional; currently `shared_token` when present.
`internal_auth.shared_token.token`	Yes	Shared service-to-service token.
`billing.stripe.enabled`	No	Managed-cloud only. Self-hosted deployments should leave this commented out.
`billing.stripe.secret_key`	Required when Stripe is enabled	Managed-cloud only. Stripe secret key for customer provisioning.
`sandbox.default_base_image`	Yes	Sandbox base image reference.
`sandbox.publish_base_domain`	Yes	Base domain for published sandbox URLs.
`sandbox.docker.enabled`	No	Enables managed Docker sandbox provider config when Docker credentials are present.
`sandbox.docker.socket_path`	Required when Docker is enabled	Docker daemon socket path.
`sandbox.docker.network_name`	No	Docker network name for sandbox containers.
`sandbox.e2b.enabled`	No	Enables managed E2B sandbox provider config when E2B credentials are present.
`sandbox.e2b.api_key`	Required when E2B is enabled	E2B API key.
`sandbox.e2b.domain`	No	E2B API domain.
`sandbox.tokens.connect.secret`	Yes	Connect token signing secret.
`sandbox.tokens.connect.issuer`	Yes	Connect token issuer.
`sandbox.tokens.connect.audience`	Yes	Connect token audience.
`sandbox.tokens.bootstrap.secret`	Yes	Bootstrap token signing secret.
`sandbox.tokens.bootstrap.issuer`	Yes	Bootstrap token issuer.
`sandbox.tokens.bootstrap.audience`	Yes	Bootstrap token audience.
`sandbox.publish.access_token.secret`	Yes	Published sandbox access token signing secret.
`sandbox.publish.access_token.issuer`	Yes	Published sandbox access token issuer.
`sandbox.publish.access_token.audience`	Yes	Published sandbox access token audience.
`sandbox.publish.session.cookie_signing_secret`	Yes	Published sandbox session cookie signing secret.
`sandbox.docker.socket_path`	Required when sandbox provider is `docker`	Docker socket path.
`sandbox.docker.network_name`	No	Docker sandbox network name.
`sandbox.e2b.api_key`	Required when sandbox provider is `e2b`	E2B API key.
`sandbox.e2b.domain`	No	E2B domain. Defaults to `e2b.app` when unset.
`sandbox.e2b.cpu_count`	No	E2B sandbox CPU count. Defaults to `2` when unset.
`sandbox.e2b.memory_mb`	No	E2B sandbox memory in MiB. Defaults to `4096` when unset.
`sandbox.sandboxd_test_faults_enabled`	No	Internal test-only flag to inject sandbox service faults.

Quickstart

Integrations