Configuration Reference¶

MAID uses environment variables and .env files for configuration. All settings use the MAID_ prefix and support nested configuration with double underscores (__).

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

Nested Settings¶

Use double underscores for nested settings:

MAID_TELNET__PORT=4000           # TelnetSettings.port
MAID_WEB__SSL__ENABLED=true      # WebSettings.ssl.enabled
MAID_AI__ANTHROPIC_API_KEY=sk-...  # AISettings.anthropic_api_key

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	Auto-save interval in seconds

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	"anthropic"	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	5000	Per-player daily budget
`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

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

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.

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