Getting Started

This guide will help you get PipeWorks MUD Server up and running.

Prerequisites

Python 3.12 or 3.13
pip (Python package manager)
Git

Installation

Clone and Setup

# Clone the repository
git clone https://github.com/pipe-works/pipeworks_mud_server.git
cd pipeworks_mud_server

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install -e .

Initialize Database

# Initialize the database schema
mud-server init-db

This creates the SQLite database with required tables. If MUD_ADMIN_USER and MUD_ADMIN_PASSWORD are set and no users exist, init-db also bootstraps the superuser.

Create Superuser

The server requires a superuser account for administration. Passwords must meet the STANDARD security policy requirements:

Minimum 12 characters (NIST SP 800-63B recommended)
Not a commonly used password (checked against 150+ known weak passwords)
No sequential characters (abc, 123, xyz)
No excessive repeated characters (aaa, 1111)

Choose one method:

Interactive mode (recommended for local development):

mud-server create-superuser
# Password requirements will be displayed
# Real-time feedback on password strength

Environment variables (for CI/deployment):

export MUD_ADMIN_USER=myadmin
export MUD_ADMIN_PASSWORD="MySecure#Pass2024"  # Must meet policy requirements
mud-server create-superuser

Note

The password policy ensures strong passwords are used from the start. See Security for complete details on the password policy.

Running the Server

Start the Server

mud-server run

This starts:

API Server: http://localhost:8000
Web UI: http://localhost:7860

Press Ctrl+C to stop the server.

Creating Your First World

The default world is defined in data/world_data.json:

{
  "rooms": {
    "spawn": {
      "id": "spawn",
      "name": "Spawn Zone",
      "description": "A central gathering point.",
      "exits": {
        "north": "forest",
        "south": "desert"
      },
      "items": ["torch"]
    }
  },
  "items": {
    "torch": {
      "id": "torch",
      "name": "torch",
      "description": "A burning torch providing light."
    }
  }
}

To create your own world:

Edit data/world_data.json
Add rooms with connections
Add items to rooms
Restart the server

No code changes required!

Development Setup

For development work:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run tests with coverage
pytest --cov=mud_server --cov-report=html

# Lint code
ruff check src/ tests/

# Format code
black src/ tests/

# Type checking
mypy src/ --ignore-missing-imports

Running Components Separately

API Server Only

python -m mud_server.api.server

Gradio Client Only

python -m mud_server.admin_gradio.app

Requires API server to be running.

Admin TUI (Terminal Interface)

For SSH/tmux workflows or terminal-based administration:

# Install TUI dependencies
pip install -e ".[admin-tui]"

# Run the terminal UI (connects to localhost:8000 by default)
pipeworks-admin-tui

# Connect to a remote server
pipeworks-admin-tui --server http://remote-server:8000

The TUI provides:

Login screen with username/password authentication
Dashboard with server status and quick actions
Create user workflow (role selection + password confirmation)
Keyboard shortcuts for common operations

Requires API server to be running.

Guest Registration

The public /register and /register-guest endpoints create temporary guest accounts for testing/dev. /register-guest generates the username server-side, while /register accepts a client-supplied username. Each guest account gets a single character and is automatically purged after 24 hours (the user is deleted, characters are unlinked).

Example: `POST /register` (client-supplied username)

curl -s -X POST http://localhost:8000/register \\
  -H "Content-Type: application/json" \\
  -d '{
    "username": "guest_demo",
    "password": "SecurePass#1234",
    "password_confirm": "SecurePass#1234"
  }'

Response (200):

{
  "success": true,
  "message": "Temporary account created successfully! You can now login as guest_demo."
}

Example: `POST /register-guest` (server-generated username)

curl -s -X POST http://localhost:8000/register-guest \\
  -H "Content-Type: application/json" \\
  -d '{
    "password": "SecurePass#1234",
    "password_confirm": "SecurePass#1234",
    "character_name": "Guest Wanderer"
  }'

Response (200):

{
  "success": true,
  "message": "Temporary guest account created successfully! You can now login as guest_00421.",
  "username": "guest_00421"
}

Environment Variables

Optional configuration:

Variable	Default	Description
`MUD_HOST`	`0.0.0.0`	Server bind address
`MUD_PORT`	`8000`	API server port
`MUD_SERVER_URL`	`http://localhost:8000`	Client API endpoint
`MUD_ADMIN_USER`	(none)	Superuser username for create-superuser or init-db bootstrap
`MUD_ADMIN_PASSWORD`	(none)	Superuser password for create-superuser or init-db bootstrap
`MUD_REQUEST_TIMEOUT`	`30`	HTTP request timeout (seconds) for TUI

CLI Reference

The mud-server CLI provides these commands:

mud-server init-db           Initialize database schema
mud-server create-superuser  Create a superuser account
mud-server run               Start the server

The pipeworks-admin-tui CLI (requires [admin-tui] extra):

pipeworks-admin-tui                    Connect to localhost:8000
pipeworks-admin-tui -s URL             Connect to specified server
pipeworks-admin-tui -t SECONDS         Set request timeout

For help on any command:

mud-server --help
mud-server init-db --help
pipeworks-admin-tui --help

Next Steps

Read the Architecture to understand the system design
Learn how to Extending the Server the server with new features
Explore the API Reference for API documentation
- - MUD_CHAR_DEFAULT_SLOTS
  - 2
  - Default character slots per account
- - MUD_CHAR_MAX_SLOTS
  - 10
  - Maximum character slots per account