Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mistle.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
SectionPurpose
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.smtpSMTP delivery settings
internal_authService-to-service authentication
sandbox.*Sandbox provider, storage, publish, and token settings
telemetry.*OpenTelemetry export settings

​
Services

Service sections define where each service listens and how other services reach it.
SectionRequired settings
services.dashboardpublic_url, control_plane_api_origin
services.control_plane_apihost, port, public_url, internal_url
services.data_plane_apihost, port, internal_url
services.data_plane_gatewayhost, port, internal_url, sandbox WebSocket URLs
services.control_plane_workerworkflow_concurrency
services.data_plane_workerworkflow_concurrency
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.
FieldUsed for
direct_urlMigrations and other direct database ownership tasks
pooled_urlRuntime 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. object_store.sandbox_storage is used when Archil sandbox storage should mount an S3-compatible bucket: 
[sandbox.storage.archil]
mount_object_store = "sandbox_storage"

​
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 only when Google OAuth is configured: 
[services.control_plane_api.auth]
enabled_methods = ["otp", "google"]
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

Use sandbox.provider = "docker" for local or simple single-node deployments. Use sandbox.provider = "e2b" for cloud sandboxes. Sandbox storage is configured independently:
BackendRequired section
docker_volumesandbox.storage.docker_volume
archilsandbox.storage.archil
Archil-backed storage can mount object_store.sandbox_storage by setting: 
[sandbox.storage.archil]
mount_object_store = "sandbox_storage"

​
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.
KeyRequiredNotes
global.envYesdevelopment or production.
telemetry.enabledYesEnables or disables telemetry export.
telemetry.debugYesEnables debug telemetry behavior.
telemetry.resource_attributesNoOpenTelemetry resource attributes string.
telemetry.traces.endpointYes when telemetry is enabledOptional when telemetry is disabled.
telemetry.logs.endpointYes when telemetry is enabledOptional when telemetry is disabled.
telemetry.metrics.endpointYes when telemetry is enabledOptional when telemetry is disabled.
services.dashboard.public_urlYesPublic dashboard origin.
services.dashboard.control_plane_api_originYesBrowser-facing control-plane API origin used by the dashboard build.
services.control_plane_api.hostYesBind host.
services.control_plane_api.portYesBind port.
services.control_plane_api.public_urlYesPublic control-plane API URL.
services.control_plane_api.internal_urlYesInternal control-plane API URL.
services.control_plane_api.auth.secretYesAuth signing secret.
services.control_plane_api.auth.trusted_originsYesAllowed dashboard/browser origins.
services.control_plane_api.auth.enabled_methodsNoSupported values: otp, google. Google requires credentials. If omitted, only OTP is exposed to users.
services.control_plane_api.auth.otp.lengthYesOTP code length.
services.control_plane_api.auth.otp.expires_in_secondsYesOTP expiry.
services.control_plane_api.auth.otp.allowed_attemptsYesMaximum OTP attempts.
services.control_plane_api.auth.google.client_idRequired when Google auth is enabledGoogle OAuth client ID.
services.control_plane_api.auth.google.client_secretRequired when Google auth is enabledGoogle OAuth client secret.
services.control_plane_api.integrations.active_master_encryption_key_versionYesActive integration credential key version.
services.control_plane_api.integrations.master_encryption_keys.<version>YesOne or more positive integer string versions.
services.data_plane_api.hostYesBind host.
services.data_plane_api.portYesBind port.
services.data_plane_api.internal_urlYesInternal data-plane API URL.
services.data_plane_gateway.hostYesBind host.
services.data_plane_gateway.portYesBind port.
services.data_plane_gateway.internal_urlYesInternal data-plane gateway URL.
services.data_plane_gateway.sandbox_ws_public_urlYesPublic sandbox WebSocket tunnel URL.
services.data_plane_gateway.sandbox_ws_internal_urlYesInternal sandbox WebSocket tunnel URL.
services.control_plane_worker.workflow_concurrencyYesControl-plane workflow worker concurrency.
services.data_plane_worker.workflow_concurrencyYesData-plane workflow worker concurrency.
workflow.control_plane.namespace_idYesControl-plane workflow namespace.
workflow.data_plane.namespace_idYesData-plane workflow namespace.
postgres.control_plane.direct_urlYesDirect control-plane Postgres URL for migrations.
postgres.control_plane.pooled_urlYesPooled control-plane Postgres URL for runtime traffic.
postgres.data_plane.direct_urlYesDirect data-plane Postgres URL for migrations.
postgres.data_plane.pooled_urlYesPooled data-plane Postgres URL for runtime traffic.
kv.control_plane.backendNoOptional control-plane Valkey backend. Currently valkey when set.
kv.control_plane.urlRequired when kv.control_plane is setControl-plane Valkey URL.
kv.control_plane.key_prefixRequired when kv.control_plane is setControl-plane Valkey key prefix.
kv.data_plane.backendYesCurrently valkey.
kv.data_plane.urlYesData-plane Valkey URL.
kv.data_plane.key_prefixYesData-plane Valkey key prefix.
object_store.assets.bucket_nameYesAsset object store bucket.
object_store.assets.regionYesAsset object store region.
object_store.assets.endpointNoCustom object store endpoint.
object_store.assets.force_path_styleNoS3 path-style setting.
object_store.assets.access_key_idYesAsset object store access key.
object_store.assets.secret_access_keyYesAsset object store secret key.
object_store.sandbox_storage.bucket_nameRequired when mounted by Archil storageSandbox storage object store bucket.
object_store.sandbox_storage.regionNoSandbox storage object store region; not used by the current Archil mount payload.
object_store.sandbox_storage.endpointRequired when mounted by Archil storageSandbox storage object store endpoint.
object_store.sandbox_storage.force_path_styleNoS3 path-style setting.
object_store.sandbox_storage.access_key_idRequired when mounted by Archil storageSandbox storage access key.
object_store.sandbox_storage.secret_access_keyRequired when mounted by Archil storageSandbox storage secret key.
email.smtp.from_addressYesSMTP sender address.
email.smtp.from_nameYesSMTP sender name.
email.smtp.hostYesSMTP host.
email.smtp.portYesSMTP port.
email.smtp.secureYesWhether SMTP uses TLS.
email.smtp.usernameYesSMTP username.
email.smtp.passwordYesSMTP password.
internal_auth.methodNoOptional; currently shared_token when present.
internal_auth.shared_token.tokenYesShared service-to-service token.
sandbox.providerYesdocker or e2b.
sandbox.default_base_imageYesSandbox base image reference.
sandbox.publish_base_domainYesBase domain for published sandbox URLs.
sandbox.storage.backendYesarchil or docker_volume.
sandbox.storage.archil.api_keyRequired when storage backend is archilArchil API key.
sandbox.storage.archil.regionRequired when storage backend is archilArchil region.
sandbox.storage.archil.name_prefixNoPrefix for Archil storage names.
sandbox.storage.archil.mount_object_storeNoCurrently only sandbox_storage.
sandbox.storage.docker_volume.name_prefixNoPrefix for Docker volume names; section required when storage backend is docker_volume.
sandbox.tokens.connect.secretYesConnect token signing secret.
sandbox.tokens.connect.issuerYesConnect token issuer.
sandbox.tokens.connect.audienceYesConnect token audience.
sandbox.tokens.bootstrap.secretYesBootstrap token signing secret.
sandbox.tokens.bootstrap.issuerYesBootstrap token issuer.
sandbox.tokens.bootstrap.audienceYesBootstrap token audience.
sandbox.publish.access_token.secretYesPublished sandbox access token signing secret.
sandbox.publish.access_token.issuerYesPublished sandbox access token issuer.
sandbox.publish.access_token.audienceYesPublished sandbox access token audience.
sandbox.publish.session.cookie_signing_secretYesPublished sandbox session cookie signing secret.
sandbox.docker.socket_pathRequired when sandbox provider is dockerDocker socket path.
sandbox.docker.network_nameNoDocker sandbox network name.
sandbox.e2b.api_keyRequired when sandbox provider is e2bE2B API key.
sandbox.e2b.domainNoE2B domain. Defaults to e2b.app when unset.
sandbox.e2b.cpu_countNoE2B sandbox CPU count. Defaults to 2 when unset.
sandbox.e2b.memory_mbNoE2B sandbox memory in MiB. Defaults to 4096 when unset.
sandbox.sandboxd_test_faults_enabledNoInternal test-only flag to inject sandbox service faults.