TOML Configuration Files

Mantis uses TOML (Tom’s Obvious Minimal Language) for configuration files.

TOML Basics

Syntax Overview

TOML is designed to be easy to read and write:

# This is a comment

# Basic key-value pairs
key = "value"
number = 42
boolean = true

# Sections (tables)
[section]
key = "value in section"

# Nested sections
[section.subsection]
key = "nested value"

# Arrays
items = ["one", "two", "three"]

# Inline tables
point = { x = 1, y = 2 }

Data Types

Type	Example	Description
String	`"hello"`	Text in quotes
Integer	`42`	Whole numbers
Float	`3.14`	Decimal numbers
Boolean	`true`, `false`	True/false values
DateTime	`2024-01-15T10:30:00Z`	ISO 8601 format
Array	`[1, 2, 3]`	List of values
Table	`[section]`	Nested structure

Configuration Structure

Mandible Configuration

# Server section
[server]
host = "0.0.0.0"
port = 3000

# Nested TLS section
[server.tls]
cert_path = "/etc/mantis/certs/server.crt"
key_path = "/etc/mantis/certs/server.key"

# Database section
[database]
url = "postgres://mantis:password@localhost:5432/mantis"
max_connections = 10

# JWT section
[jwt]
algorithm = "HS256"
secret = "your-secret-key"
access_token_expiry_secs = 3600

# Auth section
[auth]
lens_base_url = "https://lens.example.com/login"

Thorax Configuration

[tls]
auth_mode = "thumbprint"
cert_path = "/etc/mantis/certs/thorax.crt"
key_path = "/etc/mantis/certs/thorax.key"

[grpc]
address = "0.0.0.0"
port = 50051

[mandible]
endpoint = "https://mandible.example.com:50052"
tls_cert_path = "/etc/mantis/certs/client.crt"
tls_key_path = "/etc/mantis/certs/client.key"
tls_ca_cert_path = "/etc/mantis/certs/ca.crt"

[queue]
enabled = true
host = "localhost"
port = 5671

[cluster]
enabled = true
redis_url = "redis://localhost:6379"

Tarsus Configuration

name = "web-prod-01"
mode = "listen"

# Tarsus registers with Mandible (not Thorax); env: TARSUS__MANDIBLE__ENDPOINT
[mandible]
endpoint = "mandible.example.com:50052"

[tls]
cert_path = "/etc/tarsus/cert.pem"
key_path = "/etc/tarsus/key.pem"
ca_cert_path = "/etc/tarsus/ca.crt"

String Formats

Basic Strings

# Double quotes - escape sequences supported
path = "/etc/mantis/config"
message = "Line 1\nLine 2"

# Literal strings - no escaping
regex = 'C:\Users\name'

Multi-line Strings

# Multi-line basic string
description = """
This is a longer description
that spans multiple lines.
Newlines are preserved."""

# Multi-line literal string
script = '''
#!/bin/bash
echo "Hello, World!"
exit 0
'''

String Escapes

Escape	Meaning
`\n`	Newline
`\t`	Tab
`\\`	Backslash
`\"`	Double quote

Arrays

Simple Arrays

# Array of strings
origins = ["https://app.example.com", "https://admin.example.com"]

# Array of integers
ports = [80, 443, 8080]

# Mixed types (not recommended)
mixed = ["string", 42, true]

Multi-line Arrays

allowed_origins = [
    "https://app.example.com",
    "https://admin.example.com",
    "https://api.example.com",
]

Array of Tables

# Array of inline tables
[[storage.backends]]
name = "local"
type = "filesystem"
path = "/var/lib/mantis/storage"

[[storage.backends]]
name = "s3"
type = "s3"
bucket = "mantis-artifacts"
region = "us-east-1"

Tables (Sections)

Standard Tables

[server]
host = "0.0.0.0"
port = 3000

[database]
url = "postgres://localhost/mantis"

Nested Tables

# Dotted keys
[server.tls]
cert_path = "/path/to/cert"

# Equivalent to:
[server]
[server.tls]
cert_path = "/path/to/cert"

Inline Tables

# Inline table (one line)
point = { x = 1, y = 2 }

# Useful for small, related values
database = { host = "localhost", port = 5432 }

Comments

Line Comments

# This is a comment on its own line
key = "value"  # This is an end-of-line comment

# Comments can explain configuration
# Maximum number of database connections
max_connections = 10

Section Comments

# ============================================
# Server Configuration
# ============================================
[server]
host = "0.0.0.0"
port = 3000

# ============================================
# Database Configuration
# ============================================
[database]
url = "postgres://localhost/mantis"

Variable Substitution

TOML doesn’t support variable substitution natively. Use these approaches:

Environment Variables

# Reference in TOML (processed by application)
[database]
url = "${DATABASE_URL}"

# Or use environment variable directly
# export DATABASE_URL=postgres://localhost/mantis

Shell Preprocessing

# Using envsubst
envsubst < config.toml.template > config.toml

# config.toml.template:
# [database]
# url = "${DATABASE_URL}"

Validation

Syntax Validation

# Using Python
python -c "import tomllib; tomllib.load(open('config.toml', 'rb'))"

# Using taplo (TOML toolkit)
taplo check config.toml

Common Syntax Errors

Error	Cause	Fix
Unexpected character	Missing quotes	Add quotes around strings
Invalid key	Special characters	Quote the key or rename
Duplicate key	Key defined twice	Remove duplicate
Type mismatch	Wrong value type	Use correct type

Best Practices

1. Organize by Section

# Good: Logical grouping
[server]
host = "0.0.0.0"
port = 3000

[server.tls]
cert_path = "/path/to/cert"

[database]
url = "..."

# Bad: Mixed order
[server.tls]
cert_path = "/path/to/cert"

[database]
url = "..."

[server]
host = "0.0.0.0"

2. Use Comments Wisely

# Good: Explain non-obvious settings
[server]
# Higher timeout for slow network environments
request_timeout_secs = 120

# Bad: State the obvious
[server]
# Server port
port = 3000

3. Keep Secrets Out

# Bad: Secrets in config
[jwt]
secret = "super-secret-key"

# Good: Reference environment variable
[jwt]
# Set via MANDIBLE__JWT__SECRET environment variable
algorithm = "HS256"

4. Use Sensible Defaults

# Only override when needed
[server]
# port = 3000  # Using default
request_timeout_secs = 120  # Non-default value

[database]
url = "postgres://localhost/mantis"
# max_connections = 10  # Using default

5. Document Custom Settings

# Custom timeout for high-latency network
# Ticket: INFRA-1234
request_timeout_secs = 300

File Organization

Development vs Production

config/
├── development.toml     # Local development
├── staging.toml         # Staging environment
├── production.toml      # Production settings
└── base.toml           # Shared settings (if using includes)

Per-Component Configuration

/etc/mantis/
├── mandible.toml        # API configuration
├── thorax.toml          # Orchestration configuration
└── shared/              # Shared files
    └── ca.crt

/etc/tarsus/
├── tarsus.toml          # Agent configuration
├── cert.pem
└── key.pem

Complete Examples

Minimal Production Mandible

# Minimal production configuration

[server]
port = 3000

[server.tls]
cert_path = "/etc/mantis/certs/server.crt"
key_path = "/etc/mantis/certs/server.key"

[database]
url = "postgres://mantis@db.internal/mantis?sslmode=require"

[jwt]
algorithm = "RS256"
private_key_path = "/etc/mantis/jwt/private.pem"
public_key_path = "/etc/mantis/jwt/public.pem"

[grpc]
orchestration_url = "https://thorax.internal:50051"

Full Development Mandible

# Development configuration with all options

[server]
host = "127.0.0.1"
port = 3000
request_timeout_secs = 60

[database]
# Prefer the DATABASE_URL environment variable in real deployments
url = "postgres://mantis:mantis@localhost:5432/mantis_dev"
max_connections = 5
min_idle = 1
connection_timeout_secs = 10

[jwt]
algorithm = "HS256"
# Set via MANDIBLE__JWT__SECRET in real deployments
secret = "development-only-secret-not-for-production"
access_token_expiry_secs = 86400
refresh_token_expiry_secs = 604800
issuer = "mantis-dev"

[cors]
allowed_origins = ["https://localhost:5173"]
allowed_methods = ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
allowed_headers = ["Content-Type", "Authorization", "Accept", "X-Request-ID"]
allow_credentials = true
max_age_secs = 3600

[cookie]
secure = false
same_site = "Lax"

[grpc]
orchestration_url = "https://localhost:50051"
connect_timeout_secs = 5
request_timeout_secs = 30

Log level is controlled by the RUST_LOG environment variable (the standard tracing EnvFilter), not a [logging] section.

Troubleshooting

Parse Errors

Error: TOML parse error at line 15, column 8
  |
15 | key = value without quotes
   |       ^^^^^
invalid string

Fix: Add quotes around string values.

Key Not Found

Error: missing field `url` in section `database`

Fix: Add the required field or check spelling.

Type Mismatch

Error: expected integer for `port`, found string

Fix: Remove quotes from numeric values.

# Wrong
port = "3000"

# Correct
port = 3000

Next Steps

Configuration Overview - Configuration concepts
Environment Variables - Variable reference
Mandible Configuration - API configuration