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)

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

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

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__MIN_VERSION`	str	"TLSv1.2"	Minimum TLS version

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

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_HOURS`	int	24	Token expiry time
`MAID_ADMIN__REFRESH_TOKEN_EXPIRY_DAYS`	int	7	Refresh token expiry
`MAID_ADMIN__ALGORITHM`	str	"HS256"	JWT algorithm
`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

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

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__LOG_SLOW_QUERIES`	bool	true	Log slow queries

Hot 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__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

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

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

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