Configuration Overview

Configuration Overview

Mantis components are configured through TOML files and environment variables.

Configuration Methods

Priority Order

Configuration values are resolved in this order (highest to lowest priority):

┌─────────────────────────────────────────────────────────────┐
│  Configuration Priority                                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Environment variables        (highest priority)         │
│  2. TOML configuration file                                 │
│  3. Default values               (lowest priority)          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Configuration Files

Each component searches standard locations for its config file:

Component	Search Order	Env Override
Mandible	mandible.toml (cwd), /etc/mantis/mandible.toml, ~/.config/mantis/mandible.toml	MANDIBLE_CONFIG
Thorax	thorax.toml, /etc/mantis/thorax.toml, ~/.config/mantis/thorax.toml	THORAX_CONFIG
Tarsus	tarsus.toml, /etc/mantis/client.toml, ~/.config/mantis/client.toml	TARSUS_CONFIG

Environment Variables

Components use different naming conventions:

Component	Convention	Example
Mandible	MANDIBLE__SECTION__KEY (double underscore)	MANDIBLE__JWT__SECRET
Thorax	THORAX__SECTION__KEY (double underscore)	THORAX__GRPC__PORT
Tarsus	TARSUS__SECTION__KEY (double underscore)	TARSUS__LISTEN__PORT

All components use double underscore (__) as the separator for nested configuration sections. See Environment Variables for the complete reference.

Component Configurations

Mandible (REST API)

The Mandible API server handles HTTP requests from Lens UI and external clients.

Section	Purpose
server	HTTP server settings
database	PostgreSQL connection
jwt	Authentication tokens
cors	Cross-origin settings
cookie	Refresh token cookies
auth	Lens login redirects
grpc	Thorax connection (outbound)
internal_grpc	Thorax connection (inbound)
rate_limit	API rate limiting
identity	Server identity/discovery
console	Tokio-console debugging
encryption	Credential encryption
audit	Audit logging
sse	Server-Sent Events
queue	RabbitMQ dispatch
oidc	OIDC/SSO settings
file_cache	S3/Git content caching
log_analyzer	AI log analysis
wireguard	WireGuard transport

See Mandible Configuration for details.

Thorax (Orchestration)

The Thorax server handles gRPC communication with agents and orchestrates deployments.

Section	Purpose
tls	Server TLS/mTLS settings
grpc	gRPC server settings
session	Client session management
tls_rate_limit	TLS handshake rate limiting
audit	Audit logging
console	Tokio-console debugging
encryption	Credential encryption
mandible	Mandible gRPC client
queue	RabbitMQ command consumption
cluster	Redis cluster coordination

See Thorax Configuration for details.

Tarsus (Agent)

The Tarsus agent runs on target servers and executes deployments.

Section	Purpose
tls	Client TLS settings
mandible	Mandible connection (registration)
listen	Listen mode settings
poll	Poll mode settings
registration	Registration and heartbeat
retry	Connection retry settings
console	Tokio-console debugging
transport	WireGuard transport
security	Protected security settings

See Tarsus Configuration for details.

Quick Start

Minimal Mandible Configuration

[server]
port = 3000

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

[jwt]
secret = "your-secret-key-at-least-32-characters"

[auth]
lens_base_url = "https://localhost:5173/login"

[grpc]
orchestration_url = "https://localhost:50051"

Minimal Thorax Configuration

name = "thorax-01"

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

[grpc]
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"

Minimal Tarsus Configuration

name = "web-prod-01"

[tls]
ca_cert_path = "/etc/mantis/certs/ca.crt"
trust_server_thumbprint = "a1b2c3d4e5f6..."

[mandible]
endpoint = "mandible.example.com:50052"

Configuration Locations

Production

/etc/mantis/
├── thorax.toml             # Thorax configuration
├── certs/                  # TLS certificates
│   ├── server.crt
│   ├── server.key
│   ├── ca.crt
│   └── ca.key
└── jwt/                    # JWT keys (RS256)
    ├── private.pem
    └── public.pem

/etc/mantis/
├── client.toml             # Tarsus configuration

Common Patterns

Database Connection

Mandible is the only component with a database. Mandible’s database is configured as:

[database]
url = "postgres://user:password@host:port/database"
max_connections = 10
min_idle = 2
connection_timeout_secs = 10

TLS Configuration

TLS is mandatory for all components. Thorax and Tarsus use mTLS:

[tls]
cert_path = "/path/to/cert.pem"
key_path = "/path/to/key.pem"
ca_cert_path = "/path/to/ca.crt"

Logging

Thorax and Tarsus take a top-level log_level in their TOML:

log_level = "info"   # trace, debug, info, warn, error

Mandible has no log_level config key (its config uses deny_unknown_fields, so adding one fails startup). Control Mandible logging with the RUST_LOG environment variable, e.g. RUST_LOG=mandible=info.

Or via environment variable:

# Thorax
export MANTIS_LOG_LEVEL=debug

# Tarsus
export TARSUS__LOG_LEVEL=debug

# Fine-grained control
export RUST_LOG=info,mandible=debug

Configuration Best Practices

1. Use Environment Variables for Secrets

# Good: Secrets in environment
export DATABASE_URL="postgres://user:secret@localhost/mantis"
export MANDIBLE__JWT__SECRET="$(cat /run/secrets/jwt-secret)"

# Bad: Secrets in config file
# [database]
# url = "postgres://user:secret@localhost/mantis"

2. Validate Before Deployment

# Validate TOML syntax
python -c "import tomllib; tomllib.load(open('config/production.toml', 'rb'))" || exit 1

Components validate their configuration on startup and will report any errors.

Next Steps

• Mandible Configuration - API server settings
• Thorax Configuration - Orchestration server settings
• Tarsus Configuration - Agent settings
• Environment Variables - Complete variable reference