Quickstart¶

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

Starting the Server¶

After installing MAID, start the server with:

uv run maid server start

You should see output like:

Starting MAID Server...
  Telnet: 0.0.0.0:4000
  Web:    0.0.0.0:8080
  Discovered: maid-stdlib
  Discovered: maid-classic-rpg
  Loaded: maid-stdlib
  Loaded: maid-classic-rpg
Server started. Press Ctrl+C to stop.

The server is now running with:

Telnet on port 4000
WebSocket on port 8080

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

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:

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

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

# Enable debug mode
uv run maid server start --debug

# Load specific content packs
uv run maid server start --content maid-stdlib --content maid-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

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 maid-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
>>> world = World()
>>> # 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:

uv run maid server start --debug

This enables verbose output for troubleshooting.