Configuration Reference

MAID uses environment variables and .env files for configuration. All settings use the MAID_ prefix.

Each subsettings class defines its own env_prefix (e.g., MAID_TELNET_, MAID_AI_, MAID_AI_DIALOGUE_), so the preferred form for top-level subsettings fields is the direct-prefix style with a single underscore separator. The root Settings class also supports double-underscore (__) nesting — this is required only for deeply nested sub-settings (e.g., SSL settings nested under Telnet) and works as an alternative for any field.

Configuration Methods

Environment Variables

export MAID_DEBUG=true
export MAID_LOG_LEVEL=DEBUG
export MAID_TELNET_PORT=4000

.env File

Create a .env file in your project root:

MAID_DEBUG=true
MAID_LOG_LEVEL=DEBUG
MAID_TELNET_PORT=4000

Direct-Prefix vs Nested Forms

Each subsettings class has its own env_prefix, making direct-prefix the primary and most readable form. The double-underscore (__) form addresses fields through the root Settings object and is required for deeply nested settings:

# Preferred: direct-prefix form (each subsettings class has its own env_prefix)
MAID_TELNET_PORT=4000              # TelnetSettings.port
MAID_AI_DEFAULT_PROVIDER=anthropic # AISettings.default_provider
MAID_AI_DIALOGUE_DEFAULT_PROVIDER=chatjimmy  # AIDialogueSettings.default_provider

# Also valid: root-nested form (double underscore separates nesting levels)
MAID_TELNET__PORT=4000             # equivalent to above
MAID_AI__DEFAULT_PROVIDER=anthropic

# Required for deeply nested settings (e.g., SSL under Telnet)
MAID_TELNET__SSL__ENABLED=true     # TelnetSettings -> SSLSettings.enabled
MAID_WEB__SSL__ENABLED=true        # WebSettings -> SSLSettings.enabled

Core Settings

Application Settings

Variable	Type	Default	Description
MAID_NAME	str	"MAID"	Application name
MAID_VERSION	str	"0.1.0"	Application version
MAID_DEBUG	bool	false	Enable debug mode
MAID_LOG_LEVEL	str	"INFO"	Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL

Game Settings

Variable	Type	Default	Description
MAID_GAME_TICK_RATE	float	4.0	Game ticks per second
MAID_GAME_SAVE_INTERVAL	float	300.0	Unused by the persistence layer (legacy knob; the SaveScheduler does not read it). Durable auto-save cadence is set only by MAID_PERSISTENCE_SAVE_INTERVAL in the Persistence Settings section below.

Network Settings

Telnet Settings

Variable	Type	Default	Description
MAID_TELNET_HOST	str	"0.0.0.0"	Telnet bind address
MAID_TELNET_PORT	int	4000	Telnet port
MAID_TELNET_MAX_CONNECTIONS	int	1000	Maximum connections
MAID_TELNET_TIMEOUT	float	300.0	Idle timeout in seconds
MAID_TELNET_ENABLE_GMCP	bool	true	Enable GMCP protocol
MAID_TELNET_ENABLE_MXP	bool	true	Enable MXP protocol
MAID_TELNET_ENABLE_MCCP	bool	true	Enable MCCP compression
MAID_TELNET_ENABLE_MSDP	bool	true	Enable MSDP protocol
MAID_TELNET_ENABLE_MSSP	bool	true	Enable MSSP protocol
MAID_TELNET_SSL_PORT	int	null	Separate TLS port (e.g., 4001)
MAID_TELNET_SSL_ONLY	bool	false	If true, only start TLS server, skip plaintext

Telnet SSL Settings

Variable	Type	Default	Description
MAID_TELNET__SSL__ENABLED	bool	false	Enable TLS for telnet
MAID_TELNET__SSL__CERT_PATH	path	null	Path to certificate file
MAID_TELNET__SSL__KEY_PATH	path	null	Path to private key
MAID_TELNET__SSL__KEY_PASSWORD	str	null	Private key password
MAID_TELNET__SSL__MIN_VERSION	str	"TLSv1.2"	Minimum TLS version
MAID_TELNET__SSL__VERIFY_CLIENT	bool	false	Require client certificates
MAID_TELNET__SSL__CA_PATH	path	null	Path to CA bundle for client verification
MAID_TELNET__SSL__CLIENT_CA_PATH	path	null	CA for verifying client certs
MAID_TELNET__SSL__CIPHERS	str	null	Custom cipher suite for TLS 1.2 and below
MAID_TELNET__SSL__TLS13_CIPHERSUITES	str	null	Reserved for future TLS 1.3 cipher config

Web Settings

Variable	Type	Default	Description
MAID_WEB_ENABLED	bool	true	Enable web server
MAID_WEB_HOST	str	"0.0.0.0"	Web server bind address
MAID_WEB_PORT	int	8080	HTTP port
MAID_WEB_STATIC_DIR	str	"static"	Static files directory
MAID_WEB_ENABLE_CORS	bool	true	Enable CORS
MAID_WEB_CORS_ORIGINS	list	[]	Allowed CORS origins
MAID_WEB_HTTPS_PORT	int	null	HTTPS port (e.g., 8443)
MAID_WEB_REDIRECT_HTTP_TO_HTTPS	bool	false	Redirect HTTP to HTTPS
MAID_WEB_TRUSTED_PROXIES	list	[]	IP addresses/CIDR ranges of trusted reverse proxies

Web SSL Settings

Variable	Type	Default	Description
MAID_WEB__SSL__ENABLED	bool	false	Enable HTTPS
MAID_WEB__SSL__CERT_PATH	path	null	Path to certificate
MAID_WEB__SSL__KEY_PATH	path	null	Path to private key
MAID_WEB__SSL__KEY_PASSWORD	str	null	Private key password
MAID_WEB__SSL__CA_PATH	path	null	Path to CA bundle for client verification
MAID_WEB__SSL__MIN_VERSION	str	"TLSv1.2"	Minimum TLS version
MAID_WEB__SSL__VERIFY_CLIENT	bool	false	Require client certificates
MAID_WEB__SSL__CLIENT_CA_PATH	path	null	CA for verifying client certs
MAID_WEB__SSL__CIPHERS	str	null	Custom cipher suite for TLS 1.2 and below
MAID_WEB__SSL__TLS13_CIPHERSUITES	str	null	Reserved for future TLS 1.3 cipher config

Database Settings

PostgreSQL Settings

Variable	Type	Default	Description
MAID_DB_HOST	str	"localhost"	Database host
MAID_DB_PORT	int	5432	Database port
MAID_DB_NAME	str	"maid"	Database name
MAID_DB_USER	str	"maid"	Database user
MAID_DB_PASSWORD	str	""	Database password (use SecretStr)
MAID_DB_POOL_SIZE	int	10	Connection pool size
MAID_DB_MAX_OVERFLOW	int	20	Max pool overflow

Redis Settings

Variable	Type	Default	Description
MAID_REDIS_HOST	str	"localhost"	Redis host
MAID_REDIS_PORT	int	6379	Redis port
MAID_REDIS_DB	int	0	Redis database number
MAID_REDIS_PASSWORD	str	null	Redis password

AI Settings

General AI Settings

Variable	Type	Default	Description
MAID_AI_DEFAULT_PROVIDER	str	"anthropic"	Default AI provider
MAID_AI_MAX_TOKENS	int	500	Maximum response tokens
MAID_AI_TEMPERATURE	float	0.7	Response temperature
MAID_AI_REQUEST_TIMEOUT	float	30.0	Request timeout in seconds

Anthropic Settings

Variable	Type	Default	Description
MAID_AI_ANTHROPIC_API_KEY	str	null	Anthropic API key
MAID_AI_ANTHROPIC_MODEL	str	"claude-sonnet-4-20250514"	Anthropic model

OpenAI Settings

Variable	Type	Default	Description
MAID_AI_OPENAI_API_KEY	str	null	OpenAI API key
MAID_AI_OPENAI_MODEL	str	"gpt-4o"	OpenAI model

Ollama Settings

Variable	Type	Default	Description
MAID_AI_OLLAMA_HOST	str	"http://localhost:11434"	Ollama host URL
MAID_AI_OLLAMA_MODEL	str	"llama3.2"	Ollama model

AI Dialogue Settings

Variable	Type	Default	Description
MAID_AI_DIALOGUE_ENABLED	bool	true	Enable AI dialogue
MAID_AI_DIALOGUE_DEFAULT_PROVIDER	str	"chatjimmy"	Default dialogue provider
MAID_AI_DIALOGUE_DEFAULT_MAX_TOKENS	int	150	Max tokens for dialogue
MAID_AI_DIALOGUE_DEFAULT_TEMPERATURE	float	0.7	Dialogue temperature
MAID_AI_DIALOGUE_GLOBAL_RATE_LIMIT_RPM	int	60	Global rate limit (requests/min)
MAID_AI_DIALOGUE_PER_PLAYER_RATE_LIMIT_RPM	int	10	Per-player rate limit
MAID_AI_DIALOGUE_PER_NPC_COOLDOWN_SECONDS	float	2.0	NPC response cooldown
MAID_AI_DIALOGUE_DAILY_TOKEN_BUDGET	int	null	Daily token budget (null=unlimited)
MAID_AI_DIALOGUE_PER_PLAYER_DAILY_BUDGET	int	null	Per-player daily budget (null = unlimited)
MAID_AI_DIALOGUE_MAX_CONVERSATION_HISTORY	int	10	Max messages in history
MAID_AI_DIALOGUE_CONVERSATION_TIMEOUT_MINUTES	int	30	Conversation timeout
MAID_AI_DIALOGUE_CONTENT_FILTERING	bool	true	Enable content filtering
MAID_AI_DIALOGUE_LOG_CONVERSATIONS	bool	false	Log conversations
MAID_AI_DIALOGUE_WORLD_NAME	str	null	World name for NPC dialogue prompts
MAID_AI_DIALOGUE_DEFAULT_MODEL	str	null	Default model override
MAID_AI_DIALOGUE_ENABLE_STREAMING	bool	true	Stream AI responses incrementally
MAID_AI_DIALOGUE_DAILY_RESET_TIMEZONE	str	"UTC"	Timezone for daily budget resets (IANA name)
MAID_AI_DIALOGUE_INCLUDE_WORLD_CONTEXT	bool	true	Include world context in prompts
MAID_AI_DIALOGUE_INCLUDE_LOCATION_CONTEXT	bool	true	Include location context in prompts
MAID_AI_DIALOGUE_INCLUDE_PLAYER_CONTEXT	bool	true	Include player context in prompts
MAID_AI_DIALOGUE_MAX_HISTORY_TOKENS	int	2000	Max tokens for conversation history (null=unlimited)
MAID_AI_DIALOGUE_CONVERSATION_CLEANUP_INTERVAL_SECONDS	float	60.0	Interval for cleaning up expired conversations
MAID_AI_DIALOGUE_ENFORCE_CHARACTER	bool	true	Enforce NPC stays in character
MAID_AI_DIALOGUE_BLOCK_META_DISCUSSION	bool	true	Block meta/out-of-character discussion
MAID_AI_DIALOGUE_BLOCK_HARMFUL_CONTENT	bool	true	Block harmful content in prompts
MAID_AI_DIALOGUE_ALLOWED_ACTIONS	list	[]	Actions NPCs are allowed to perform
MAID_AI_DIALOGUE_PROVIDER_FALLBACK_CHAIN	list	["npc","settings","registry"]	Provider fallback order
MAID_AI_DIALOGUE_PROFANITY_FILE	str	null	Path to external profanity word list file

Note: The double-underscore form (e.g., MAID_AI_DIALOGUE__DEFAULT_PROVIDER) also works as an alternative when addressing fields through the root Settings object.

Admin Settings

Variable	Type	Default	Description
MAID_ADMIN_ENABLED	bool	true	Enable admin API
MAID_ADMIN_HOST	str	"0.0.0.0"	Admin API host
MAID_ADMIN_PORT	int	8081	Admin API port
MAID_ADMIN_SECRET_KEY	str	(required)	JWT secret key (min 32 chars in prod)
MAID_ADMIN_TOKEN_EXPIRY_MINUTES	int	15	Access token expiry in minutes
MAID_ADMIN_REFRESH_TOKEN_EXPIRY_DAYS	int	7	Refresh token expiry
MAID_ADMIN_ALGORITHM	str	"RS256"	JWT algorithm
MAID_ADMIN_PRIVATE_KEY_PATH	str	null	RSA private key path for RS256 (auto-generated if missing)
MAID_ADMIN_PUBLIC_KEY_PATH	str	null	RSA public key path for RS256 (auto-generated if missing)
MAID_ADMIN_RATE_LIMIT_REQUESTS	int	100	Rate limit requests
MAID_ADMIN_RATE_LIMIT_WINDOW_SECONDS	int	60	Rate limit window
MAID_ADMIN_ALLOWED_ORIGINS	list	(localhost)	CORS allowed origins
MAID_ADMIN_CSRF_ENABLED	bool	true	Enable CSRF protection for state-changing requests
MAID_ADMIN_DYNAMIC_ROUTE_HOST_ENABLED	bool	true	Enable atomic runtime activation of pack-owned admin HTTP routes under /admin/ext

Security Note

In production (MAID_DEBUG=false), MAID_ADMIN_SECRET_KEY must be set to a secure random value of at least 32 characters. The default insecure key is only allowed in debug mode.

The dynamic route host is enabled by default. It is mounted once at startup; pack lifecycle operations swap isolated child generations without changing the main FastAPI route list. Disable it only as an emergency compatibility switch:

MAID_ADMIN_DYNAMIC_ROUTE_HOST_ENABLED=false

Changing the flag requires a process restart. While disabled, startup pack routes remain available and guarded, but late-loaded or code-reloaded route-backed admin surfaces report restart_required. Pack Inventory shows host status, generation, route count, retired generations, and any degradation reason. Authorized administrators can inspect the active generation schema at GET /admin/ext/openapi.json; there is no public child docs endpoint.

Plugin Settings

Variable	Type	Default	Description
MAID_PLUGINS_AUTO_DISCOVER	bool	true	Auto-discover content packs
MAID_PLUGINS_SEARCH_PATHS	list	[]	Additional search paths

Internationalization Settings

Variable	Type	Default	Description
MAID_I18N_DEFAULT_LOCALE	str	"en"	Default locale
MAID_I18N_FALLBACK_LOCALE	str	"en"	Fallback locale
MAID_I18N_LOCALES_DIR	str	"locales"	Locales directory
MAID_I18N_AVAILABLE_LOCALES	list	[]	Available locales
MAID_I18N_LOG_MISSING	bool	true	Log missing translations
MAID_I18N_LOAD_MO_FILES	bool	true	Load compiled .mo files
MAID_I18N_RECURSIVE_LOAD	bool	false	Load locale files recursively
MAID_I18N_ALLOW_FUZZY	bool	false	Use fuzzy (unverified) translations as fallback
MAID_I18N_TRANSLATION_CACHE_SIZE	int	1000	LRU cache size for translation lookups (0=disabled)

Persistence Settings

Variable	Type	Default	Description
MAID_PERSISTENCE_ENABLED	bool	true	Enable durable persistence
MAID_PERSISTENCE_SAVE_INTERVAL	float	300.0	Seconds between save cycles
MAID_PERSISTENCE_BATCH_SIZE	int	50	Max entities per save batch
MAID_PERSISTENCE_UPSERT_TIMEOUT	float	5.0	Timeout for individual upsert operations
MAID_PERSISTENCE_BATCH_TIMEOUT	float	30.0	Timeout for entire batch operations
MAID_PERSISTENCE_CYCLE_TIMEOUT	float	60.0	Timeout for a full save cycle
MAID_PERSISTENCE_MAX_TOMBSTONE_RETRIES	int	10	Max retries for tombstone cleanup
MAID_PERSISTENCE_MAX_ENTITY_DOC_BYTES	int	1048576	Max serialized entity document size (1 MB)
MAID_PERSISTENCE_ENABLE_CHECKSUMS	bool	false	Enable checksum verification on save
MAID_PERSISTENCE_BULK_UPSERT_ENABLED	bool	true	Use bulk upsert for batch saves

Observability Settings

Variable	Type	Default	Description
MAID_OBSERVABILITY_ENABLED	bool	true	Master switch for observability
MAID_OBSERVABILITY_JSON_LOGS	bool	true	JSON format (prod) or console (dev)
MAID_OBSERVABILITY_LOG_LEVEL	str	"INFO"	Log level
MAID_OBSERVABILITY_LOG_SAMPLING_ENABLED	bool	true	Enable log sampling
MAID_OBSERVABILITY_OPERATIONAL_LOG_SAMPLE_RATE	int	10	Operational log sample rate (1 in N)
MAID_OBSERVABILITY_AUDIT_RETENTION_DAYS	int	90	Audit log retention in days
MAID_OBSERVABILITY_LOG_QUEUE_SIZE	int	10000	Async log queue size
MAID_OBSERVABILITY_METRICS_ENABLED	bool	true	Enable Prometheus metrics endpoint
MAID_OBSERVABILITY_INTERNAL_HOST	str	"127.0.0.1"	Internal metrics server bind address
MAID_OBSERVABILITY_INTERNAL_PORT	int	9090	Internal metrics server port
MAID_OBSERVABILITY_METRICS_TOKEN	str	""	Bearer token for /metrics endpoint
MAID_OBSERVABILITY_GAUGE_EXPORT_INTERVAL	float	15.0	Gauge export interval in seconds
MAID_OBSERVABILITY_HISTOGRAM_PROFILE	str	"compact"	Histogram bucket profile
MAID_OBSERVABILITY_SCRAPE_CACHE_TTL	float	1.0	Metrics scrape cache TTL in seconds
MAID_OBSERVABILITY_SYSTEM_TICK_DETAIL	str	"pack_only"	Tick detail level
MAID_OBSERVABILITY_MAX_PACK_METRICS	int	20	Max content pack metrics
MAID_OBSERVABILITY_TRACING_ENABLED	bool	false	Enable distributed tracing
MAID_OBSERVABILITY_TRACING_MODE	str	"minimal"	Tracing mode: minimal, default, verbose
MAID_OBSERVABILITY_TRACING_SAMPLE_RATE	float	0.05	Tracing sample rate (0.0–1.0)
MAID_OBSERVABILITY_TRACING_EXPORTER	str	"none"	Tracing exporter backend
MAID_OBSERVABILITY_SENTRY_DSN	str	""	Optional Sentry DSN for error reporting
MAID_OBSERVABILITY_SENTRY_TRACES_SAMPLE_RATE	float	0.0	Sentry performance tracing rate
MAID_OBSERVABILITY_ANONYMIZE_PLAYER_IDS	bool	true	Anonymize player IDs in telemetry
MAID_OBSERVABILITY_REDACT_COMMAND_ARGS	bool	true	Redact command arguments in logs

Memory Settings

Variable	Type	Default	Description
MAID_MEMORY_ENABLED	bool	false	Enable NPC memory system
MAID_MEMORY_EXTRACTION_QUEUE_SIZE	int	100	Memory extraction queue size
MAID_MEMORY_CACHE_MAX_ENTRIES	int	1000	Max entries in memory cache
MAID_MEMORY_CACHE_TTL_SECONDS	int	300	Memory cache TTL in seconds
MAID_MEMORY_CONTEXT_PROVIDER_TIMEOUT_MS	int	40	Context provider timeout in milliseconds
MAID_MEMORY_TOTAL_CONTEXT_BUDGET_TOKENS	int	2000	Total token budget for memory context
MAID_MEMORY_MEMORY_BOUNDS_EPISODIC	int	200	Max episodic memories per NPC
MAID_MEMORY_DECAY_CYCLE_TICKS	int	50	Ticks between memory decay cycles
MAID_MEMORY_DECAY_RATE	float	0.01	Memory decay rate per cycle
MAID_MEMORY_CONSOLIDATION_CYCLE_TICKS	int	100	Ticks between memory consolidation cycles
MAID_MEMORY_GOSSIP_BUDGET_PER_TICK	int	3	Max gossip propagations per tick
MAID_MEMORY_GOSSIP_COOLDOWN_TICKS	int	10	Ticks between gossip for same NPC
MAID_MEMORY_EXTRACTION_RPM_PER_NPC	int	10	Max extraction requests per minute per NPC
MAID_MEMORY_EXTRACTION_DAILY_TOKENS_PER_NPC	int	50000	Daily token budget per NPC for extraction

Quest Generation Settings

Quest generation is configured via QuestGenerationSettings (see maid_stdlib.systems.quests.generation.constants). These settings are passed programmatically rather than via environment variables.

Setting	Type	Default	Description
min_importance	float	0.4	Minimum story signal importance to create a seed
min_involved_npcs	int	1	Minimum NPCs involved in a signal
max_active_seeds	int	10	Max active quest seeds
cooldown_per_npc	int	3600	Cooldown per NPC before reuse (seconds)
variety_window	int	5	Recent quest window for variety enforcement
max_pending_quests	int	10	Max pending generated quests
max_seed_attempts	int	3	Max build attempts per seed
max_concurrent_builds	int	3	Max concurrent quest builds
max_active_quests_per_region	int	3	Max active quests per region
max_pending_offers_per_player	int	2	Max pending quest offers per player
token_budget_window	float	3600.0	Token budget window in seconds
token_budget_limit	int	15000	Token budget limit per window
consequence_signal_budget	int	5	Max consequence signals per quest
max_chain_depth	int	5	Max quest chain depth
chain_dampening	float	0.7	Importance dampening per chain link
max_tokens_per_narrative	int	500	Max tokens per narrative generation
max_tokens_per_dialogue	int	400	Max tokens per dialogue generation
gossip_confidence_cap	float	0.9	Cap on gossip-sourced confidence

Development Settings

Profiling Settings

Variable	Type	Default	Description
MAID_PROFILING_ENABLED	bool	false	Enable profiling
MAID_PROFILING_MEMORY_TRACE_DEPTH	int	10	Memory trace depth
MAID_PROFILING_MEMORY_TOP_ALLOCATIONS	int	50	Top allocations to track
MAID_PROFILING_SLOW_QUERY_THRESHOLD_MS	float	100.0	Slow query threshold
MAID_PROFILING_MAX_RECENT_QUERIES	int	100	Max recent queries
MAID_PROFILING_MAX_SLOW_QUERIES	int	50	Max slow queries
MAID_PROFILING_CAPTURE_QUERY_STACK_TRACE	bool	true	Capture stack traces for queries
MAID_PROFILING_QUERY_STACK_TRACE_DEPTH	int	10	Depth of query stack traces
MAID_PROFILING_MEMORY_SNAPSHOT_LIMIT	int	20	Max allocations in snapshot comparisons
MAID_PROFILING_SNAPSHOT_INTERVAL_SECONDS	float	10.0	Default interval for automatic snapshots
MAID_PROFILING_AUTO_STOP_DURATION_SECONDS	float	null	Auto-stop profiling after duration
MAID_PROFILING_LOG_SLOW_QUERIES	bool	true	Log slow queries
MAID_PROFILING_LOG_MEMORY_WARNINGS	bool	true	Log memory warnings

Reload Settings

Variable	Type	Default	Description
MAID_RELOAD_ENABLED	bool	true	Enable hot reload
MAID_RELOAD_MAX_SNAPSHOTS	int	10	Max rollback snapshots
MAID_RELOAD_CASCADE_RELOAD	bool	true	Reload dependent modules
MAID_RELOAD_TRACK_INSTANCES	bool	true	Track instances
MAID_RELOAD_ROOT_PACKAGES	list	["maid_engine","maid_stdlib","maid_classic_rpg"]	Root packages to monitor
MAID_RELOAD_WATCH_ENABLED	bool	false	Enable file watching
MAID_RELOAD_WATCH_DIRS	list	[]	Directories to watch
MAID_RELOAD_WATCH_PATTERNS	list	["*.py"]	File patterns to watch
MAID_RELOAD_WATCH_DEBOUNCE	float	0.5	Debounce time in seconds

Hot Reload Settings

Variable	Type	Default	Description
MAID_HOT_RELOAD_ENABLED	bool	true	Enable hot reload functionality
MAID_HOT_RELOAD_FILE_WATCH	bool	false	Watch files for changes
MAID_HOT_RELOAD_WATCH_PATHS	list	[]	Paths to watch for file changes
MAID_HOT_RELOAD_DEBOUNCE_DELAY	float	0.5	Delay in seconds before processing changes
MAID_HOT_RELOAD_PAUSE_TIMEOUT	float	5.0	Timeout in seconds to wait for tick pause
MAID_HOT_RELOAD_ENABLE_ROLLBACK	bool	true	Enable automatic rollback on reload failure
MAID_HOT_RELOAD_LOG_LEVEL	str	"INFO"	Logging level for hot reload operations
MAID_HOT_RELOAD_MAX_HISTORY	int	10	Max reload history entries to keep

Log Buffer Settings

Variable	Type	Default	Description
MAID_LOG_BUFFER_MAX_ENTRIES	int	10000	Max log entries
MAID_LOG_BUFFER_MAX_ENTRY_SIZE	int	2048	Max entry size in chars
MAID_LOG_BUFFER_MAX_TRACEBACK_SIZE	int	4096	Max traceback size

Bridge Settings

Discord Bridge

Variable	Type	Default	Description
MAID_BRIDGES__DISCORD__ENABLED	bool	false	Enable Discord bridge
MAID_BRIDGES__DISCORD__BOT_TOKEN	str	""	Discord bot token
MAID_BRIDGES__DISCORD__GUILD_ID	int	null	Restrict to guild
MAID_BRIDGES__DISCORD__COMMAND_PREFIX	str	"!"	Command prefix
MAID_BRIDGES__DISCORD__SHOW_GAME_JOINS	bool	true	Show game joins
MAID_BRIDGES__DISCORD__SHOW_GAME_QUITS	bool	true	Show game quits

IRC Bridge

Variable	Type	Default	Description
MAID_BRIDGES__IRC__ENABLED	bool	false	Enable IRC bridge
MAID_BRIDGES__IRC__SERVER	str	""	IRC server
MAID_BRIDGES__IRC__PORT	int	6667	IRC port
MAID_BRIDGES__IRC__SSL	bool	false	Use SSL
MAID_BRIDGES__IRC__NICKNAME	str	"MAIDBot"	Bot nickname
MAID_BRIDGES__IRC__PASSWORD	str	null	Server password
MAID_BRIDGES__IRC__CHANNELS	list	[]	Channels to join
MAID_BRIDGES__IRC__RECONNECT_DELAY	int	30	Reconnect delay
MAID_BRIDGES__IRC__MAX_MESSAGE_LENGTH	int	400	IRC message length limit

RSS Feed

Variable	Type	Default	Description
MAID_BRIDGES__RSS__ENABLED	bool	false	Enable RSS feed
MAID_BRIDGES__RSS__TITLE	str	"MAID Server News"	Feed title
MAID_BRIDGES__RSS__DESCRIPTION	str	(default)	Feed description
MAID_BRIDGES__RSS__LINK	str	"http://localhost:8080"	Feed link
MAID_BRIDGES__RSS__MAX_ITEMS	int	50	Max feed items
MAID_BRIDGES__RSS__INCLUDE_ANNOUNCEMENTS	bool	true	Include announcements
MAID_BRIDGES__RSS__INCLUDE_WORLD_EVENTS	bool	true	Include world events

Bridge Channel Mappings

Variable	Type	Default	Description
MAID_BRIDGES__CHANNEL_MAPPINGS	list	[]	Channel mappings between game and external services

Security Settings

Variable	Type	Default	Description
MAID_SECURITY_PBKDF2_ITERATIONS	int	600000	PBKDF2 iteration count for API key hashing (100000-10000000)
MAID_SECURITY_API_KEY_SALT_LENGTH	int	32	Salt length in bytes for API key hashing (16-64)

API Middleware Settings

Variable	Type	Default	Description
MAID_API_MIDDLEWARE_ENABLE_AUDIT_LOGGING	bool	true	Enable audit logging
MAID_API_MIDDLEWARE_AUDIT_MAX_ENTRIES	int	10000	Max audit entries
MAID_API_MIDDLEWARE_AUDIT_EXCLUDE_PATHS	list	(defaults)	Paths to exclude
MAID_API_MIDDLEWARE_ENABLE_RESPONSE_TIME	bool	true	Enable timing
MAID_API_MIDDLEWARE_SLOW_REQUEST_THRESHOLD_MS	float	1000.0	Slow request threshold
MAID_API_MIDDLEWARE_LOG_ALL_REQUEST_TIMES	bool	false	Log all request times

Example Configuration

Development (.env)

# Debug mode
MAID_DEBUG=true
MAID_LOG_LEVEL=DEBUG

# Network
MAID_TELNET_PORT=4000
MAID_WEB_PORT=8080

# AI (optional)
MAID_AI_ANTHROPIC_API_KEY=sk-ant-...

# Admin (using default insecure key in debug mode)
MAID_ADMIN_PORT=8081

Production (.env)

# Production mode
MAID_DEBUG=false
MAID_LOG_LEVEL=INFO

# Network with SSL
MAID_TELNET_PORT=4000
MAID_TELNET__SSL__ENABLED=true
MAID_TELNET__SSL__CERT_PATH=/etc/ssl/certs/maid.crt
MAID_TELNET__SSL__KEY_PATH=/etc/ssl/private/maid.key
MAID_TELNET_SSL_PORT=4001

MAID_WEB_PORT=8080
MAID_WEB_CORS_ORIGINS=["https://mygame.com"]
MAID_WEB__SSL__ENABLED=true
MAID_WEB__SSL__CERT_PATH=/etc/ssl/certs/maid.crt
MAID_WEB__SSL__KEY_PATH=/etc/ssl/private/maid.key
MAID_WEB_HTTPS_PORT=8443

# Database
MAID_DB_HOST=db.internal
MAID_DB_PASSWORD=secure-password
MAID_DB_POOL_SIZE=20

# Admin
MAID_ADMIN_SECRET_KEY=your-secure-random-key-at-least-32-chars
MAID_ADMIN_ALLOWED_ORIGINS=["https://admin.mygame.com"]

# AI
MAID_AI_ANTHROPIC_API_KEY=sk-ant-...
MAID_AI_DIALOGUE_DAILY_TOKEN_BUDGET=100000

Programmatic Access

Access settings in code:

from maid_engine.config.settings import get_settings

settings = get_settings()

# Access nested settings
telnet_port = settings.telnet.port
debug_mode = settings.debug
ai_provider = settings.ai.default_provider

Extending Settings

Content packs can define their own settings classes:

from pydantic_settings import BaseSettings, SettingsConfigDict


class MyPackSettings(BaseSettings):
    """Settings for my content pack."""

    model_config = SettingsConfigDict(env_prefix="MAID_MY_PACK_")

    enabled: bool = True
    max_items: int = 100
    custom_value: str = "default"

Usage:

MAID_MY_PACK_ENABLED=true
MAID_MY_PACK_MAX_ITEMS=200
MAID_MY_PACK_CUSTOM_VALUE=custom