Configuration¶

This guide covers all configuration options for HoloMUSH.

Overview¶

HoloMUSH configuration follows a hierarchy:

1. Command-line flags (highest precedence)
2. Environment variables
3. Configuration files
4. Built-in defaults

Command-Line Reference¶

Global Commands¶

Core Flags¶

The core process runs the game engine and plugin runtime.

holomush core [flags]

Example:

holomush core \
  --grpc-addr=0.0.0.0:9000 \
  --control-addr=0.0.0.0:9001 \
  --metrics-addr=0.0.0.0:9100 \
  --log-format=text

Gateway Flags¶

The gateway process handles telnet and web client connections.

holomush gateway [flags]

Example:

holomush gateway \
  --telnet-addr=:4201 \
  --core-addr=core.internal:9000 \
  --metrics-addr=0.0.0.0:9101 \
  --log-format=json

Migrate Command¶

The migrate command applies database schema changes.

holomush migrate

No flags. Requires DATABASE_URL environment variable.

Environment Variables¶

DATABASE_URL Format¶

PostgreSQL connection string format:

postgres://user:password@host:port/database?sslmode=mode

SSL Modes:

Examples:

# Local development
DATABASE_URL="postgres://holomush:secret@localhost:5432/holomush?sslmode=disable"

# Production with SSL
DATABASE_URL="postgres://holomush:${DB_PASSWORD}@db.example.com:5432/holomush?sslmode=verify-full"

File Locations¶

HoloMUSH follows the XDG Base Directory Specification.

Generated Files¶

On first startup, core automatically creates:

Docker Configuration¶

Environment Variables in Docker¶

Pass configuration via environment variables:

services:
  core:
    image: ghcr.io/holomush/holomush:latest
    command: ["core", "--grpc-addr=0.0.0.0:9000"]
    environment:
      DATABASE_URL: postgres://holomush:${POSTGRES_PASSWORD}@postgres:5432/holomush?sslmode=disable
      HOME: /home/holomush

Exposed Ports¶

Volume Mounts¶

Persist configuration and certificates:

volumes:
  - holomush_config:/home/holomush/.config/holomush
  - postgres_data:/var/lib/postgresql/data

Log Configuration¶

Log Format¶

JSON output example:

{
  "time": "2026-01-24T10:00:00Z",
  "level": "INFO",
  "msg": "server started",
  "component": "core",
  "addr": "localhost:9000"
}

Text output example:

2026-01-24T10:00:00Z INFO server started component=core addr=localhost:9000

Log Levels¶

HoloMUSH uses standard slog levels:

Network Configuration¶

Address Format¶

Addresses support various formats:

Production Recommendations¶

Next Steps¶

• Installation - Install HoloMUSH
• Operations - Monitor and maintain your server