Configuration

Mantle loads configuration from three sources: a YAML config file, environment variables, and CLI flags. This page documents every configuration option and how the sources interact.

Precedence

When the same setting is specified in multiple places, the highest-priority source wins:

1. CLI flags (highest priority)
2. Environment variables
3. Config file (mantle.yaml)
4. Built-in defaults (lowest priority)

For example, if mantle.yaml sets database.url to one value and you pass --database-url on the command line, the flag value is used.

Config File

By default, Mantle looks for a file named mantle.yaml in the current working directory. You can specify a different path with the --config flag.

Full Example

database:
  url: postgres://mantle:mantle@localhost:5432/mantle?sslmode=disable
  max_open_conns: 25
  max_idle_conns: 10
  conn_max_lifetime: 5m

api:
  address: ":8080"

log:
  level: info

encryption:
  key: "your-64-char-hex-encoded-key-here"

engine:
  worker_poll_interval: 200ms
  worker_max_backoff: 5s
  orchestrator_poll_interval: 500ms
  step_lease_duration: 60s
  orchestration_lease_duration: 120s
  ai_step_lease_duration: 300s
  reaper_interval: 30s
  step_output_max_bytes: 1048576
  default_max_tool_rounds: 10
  default_max_tool_calls_per_round: 10

All Config File Fields

Config File Discovery

When you do not pass --config, Mantle searches for mantle.yaml in the current directory. If no config file is found, Mantle silently falls back to defaults. This is intentional — most commands work fine with defaults when you use the provided docker-compose.yml.

When you pass --config path/to/config.yaml explicitly, Mantle requires that file to exist and be valid YAML. A missing or unparseable explicit config file is a hard error.

Environment Variables

All environment variables use the MANTLE_ prefix with underscores replacing dots and hyphens.

Example:

export MANTLE_DATABASE_URL="postgres://prod:secret@db.example.com:5432/mantle?sslmode=require"
export MANTLE_LOG_LEVEL="warn"
mantle init

Environment variables are useful in container deployments and CI pipelines where you do not want to mount a config file.

CLI Flags

Every configuration option has a corresponding CLI flag. Flags take the highest priority.

The --config flag has no environment variable or config file equivalent — it controls which config file to load.

Example:

mantle init --database-url "postgres://prod:secret@db.example.com:5432/mantle?sslmode=require"

Defaults

If you start Postgres using the included docker-compose.yml and run Mantle from the project directory, the defaults work without any configuration:

Common Configurations

Local Development

No config file needed. Start Postgres with docker-compose up -d and use defaults:

mantle init
mantle validate workflow.yaml
mantle apply workflow.yaml

CI Pipeline

Use environment variables to avoid config files in CI:

export MANTLE_DATABASE_URL="postgres://ci:ci@localhost:5432/mantle_test?sslmode=disable"
mantle init
mantle validate workflow.yaml
mantle apply workflow.yaml

Production

Use a mantle.yaml file with production values, or pass everything through environment variables:

# mantle.yaml
database:
  url: postgres://mantle:${DB_PASSWORD}@db.internal:5432/mantle?sslmode=require

api:
  address: ":8080"

log:
  level: warn

Note: Mantle does not perform variable substitution in the config file. The ${DB_PASSWORD} example above is illustrative — use environment variables (MANTLE_DATABASE_URL) for secrets instead of embedding them in config files.

For production secrets management, set the encryption key through an environment variable rather than the config file:

export MANTLE_ENCRYPTION_KEY="$(openssl rand -hex 32)"
export MANTLE_DATABASE_URL="postgres://mantle:secret@db.internal:5432/mantle?sslmode=require"
mantle secrets create --name prod-openai --type openai --field api_key=sk-...

The encryption key has no default value. It is only required when you use mantle secrets commands or run workflows that reference credentials. All other Mantle commands work without it.

Server Mode

When running mantle serve, the api.address setting controls which address the HTTP server, webhook listener, and health endpoints bind to:

# mantle.yaml
database:
  url: postgres://mantle:secret@db.internal:5432/mantle?sslmode=require

api:
  address: ":8080"

log:
  level: info

Or with environment variables:

export MANTLE_DATABASE_URL="postgres://mantle:secret@db.internal:5432/mantle?sslmode=require"
export MANTLE_API_ADDRESS=":8080"
export MANTLE_ENCRYPTION_KEY="$(cat /run/secrets/mantle-key)"
mantle serve

The server runs migrations automatically on startup, so you do not need a separate mantle init step.

Offline Commands

The mantle validate and mantle version commands do not require a database connection. They skip config loading entirely, so you can run them without Postgres, a config file, or any environment variables:

mantle validate workflow.yaml   # works anywhere, no database needed
mantle version                  # works anywhere

Cloud Secret Backend Configuration

Mantle can resolve credentials from external cloud secret stores. Cloud backends are configured through environment variables — there are no config file fields for these.

Cloud backends are optional. If none are configured, Mantle resolves credentials from the Postgres store and environment variable fallback only.

Each cloud backend uses its respective SDK’s default credential chain:

• AWS: environment variables, shared credentials file, EC2/ECS instance profile
• GCP: Application Default Credentials (gcloud auth application-default login, Workload Identity, service account key)
• Azure: DefaultAzureCredential (az login, managed identity, environment variables)

See the Secrets Guide for detailed setup instructions and IAM requirements.

Plugin Configuration

Plugins are stored in .mantle/plugins/ relative to the current working directory. This location is not currently configurable via the config file — it uses a fixed path.

Reference

See also:

• CLI Reference — flag documentation for every command
• Getting Started — setup walkthrough using defaults
• Secrets Guide — credential encryption, cloud backends, and key rotation
• Server Guide — running Mantle as a persistent server with triggers
• Plugins Guide — writing and managing third-party connector plugins
• Observability Guide — Prometheus metrics, audit trail, and structured logging