Quickstart¶

Get your first MAID server running in just a few minutes.

Starting the Server¶

After installing MAID, start the server.

On a fresh install the server refuses to start while the admin secret_key is left at its built-in default. For local development, set MAID_DEBUG=true (this permits the insecure default key):

MAID_DEBUG=true uv run maid server start

--debug alone is not enough

The --debug flag is applied after settings are loaded and validated, so it does not satisfy the admin-secret check on a clean install. Use the MAID_DEBUG=true environment variable as shown above, or configure a secure MAID_ADMIN_SECRET_KEY (32+ characters) for production.

By default the server prints a startup banner followed by structured log lines. You should see something like:

  Discovered: stdlib
  Discovered: classic-rpg
  Loaded: stdlib
  Loaded: classic-rpg

🎮 MAID Server v0.1.0 starting...

╭───────────── Connection Info ──────────────╮
│   Telnet:  telnet localhost 4000           │
│   Web:     http://localhost:8080/play/     │
│   Admin:   http://localhost:8080/admin-ui/ │
╰────────────────────────────────────────────╯
  Loaded packs: stdlib, classic-rpg

Server started. Press Ctrl+C to stop.

Quieter output

Set MAID_GAME_SHOW_BANNER=false to skip the banner and print a plain Starting MAID Server... summary instead.

The server is now running with:

Telnet on port 4000
WebSocket on port 8080
Player Web Client at http://localhost:8080/play/
Health Check at http://localhost:9090/healthz
Metrics at http://localhost:9090/metrics

Connecting via Telnet¶

Open a new terminal and connect using telnet:

telnet localhost 4000

Or use a MUD client like Mudlet, TinTin++, or Blightmud.

Client Configuration¶

For Mudlet or similar clients:

Host: localhost (or your server IP)
Port: 4000
Protocol: Telnet

Basic Commands¶

Once connected, try these basic commands:

look        - Look around the current room
help        - Show available commands
who         - See who's online
say hello   - Say something to the room
quit        - Disconnect

Creating a Character¶

When you first connect, you'll be prompted to create a character:

Enter your desired character name
Create a password
Confirm your password
Start playing!

Exploring the World¶

The default world loaded from maid-classic-rpg includes:

A starting area with multiple rooms
NPCs to interact with
Items to find and use
Basic combat system

Entity state (NPCs, items, rooms, player progress) is kept in an in-memory store by default, so it is not saved across server restarts. To persist your world, configure a PostgreSQL database — set MAID_DB_HOST and a non-empty MAID_DB_PASSWORD (persistence is enabled by default) — and MAID will use a durable Postgres-backed store. See the configuration reference for details.

Try these exploration commands:

north, south, east, west  - Move between rooms
look <object>             - Examine something
get <item>                - Pick up an item
inventory                 - Check your inventory
drop <item>               - Drop an item

Server Options¶

Customize your server with command-line options. On a clean install, prefix each command with MAID_DEBUG=true (or set a secure MAID_ADMIN_SECRET_KEY) so the admin secret-key check passes — see Starting the Server:

# Custom ports
MAID_DEBUG=true uv run maid server start --telnet-port 5000 --web-port 9000

# Bind to specific host
MAID_DEBUG=true uv run maid server start --host 127.0.0.1

# Verbose debug logging (--debug raises the log level; MAID_DEBUG=true is what
# permits the default admin key on a clean install)
MAID_DEBUG=true uv run maid server start --debug

# Load specific content packs
MAID_DEBUG=true uv run maid server start --content stdlib --content classic-rpg

Using the Web Interface¶

MAID also provides a WebSocket interface for web clients. Connect using a WebSocket client or the built-in web interface at:

http://localhost:8080

The web player client is available at http://localhost:8080/play/.

Testing AI Features¶

If you have an AI provider configured, test it:

# Test AI with a prompt
uv run maid dev test-ai "Describe a fantasy tavern"

# Generate content
uv run maid dev generate room "The Dragon's Rest Inn"

Viewing Content Packs¶

See what content packs are available:

# List installed packs
uv run maid content list

# Get details about a pack
uv run maid content info classic-rpg

Interactive Development Shell¶

For exploring and debugging:

uv run maid dev shell

This opens a Python REPL with MAID modules pre-loaded:

>>> from maid_engine.core.world import World
>>> from maid_engine.config.settings import get_settings
>>> world = World(get_settings())
>>> # Explore the API...

What's Next?¶

Now that you have a server running, explore these topics:

AI Configuration - Set up AI providers
Command System - Learn about commands
NPC Dialogue - Create AI-powered NPCs
Building Commands - Create custom commands
Content Pack System - Build your own content

Stopping the Server¶

Press Ctrl+C in the terminal where the server is running:

^C
Server stopped.

Troubleshooting¶

Connection Refused¶

If you can't connect:

Verify the server is running
Check the port isn't in use: lsof -i :4000
Try binding to localhost: --host 127.0.0.1

Content Packs Not Found¶

If content packs aren't loading:

# Verify packages are installed
uv run maid content list

# Reinstall if needed
uv sync

Debug Mode¶

For more detailed logging:

MAID_DEBUG=true uv run maid server start --debug

--debug raises the log level for verbose troubleshooting output. On a clean install MAID_DEBUG=true is also required (it permits the insecure default admin key); the --debug flag alone is applied after settings are validated, so it does not bypass that check.