Commonwealth-Online-Server/server

Commonwealth Online Server - Quick Start

Quick Launch

Windows: double-click start.bat, or run it from a terminal:

start.bat

Linux / macOS:

chmod +x start.sh fix-port.sh   # once
./start.sh

The start script will:

1. Check that Python 3.9+ is installed
2. Install required dependencies (typer, rich)
3. Generate a default commonwealth-server.json config file (if needed)
4. Start the server listening on 0.0.0.0:7777
5. Open an interactive commonwealth> prompt in the same window

At the prompt you can type commands directly, for example:

help
users
users once
ban 2 --reason griefing
world time 1430
quit

users live-updates the player table every second (press Enter to stop).

First Run

On first run, a default commonwealth-server.json file is created in the server directory with these settings:

{
  "host": "0.0.0.0",
  "port": 7777,
  "server_name": "Commonwealth Online Server",
  "max_players": 16,
  "log_verbosity": "info"
}

Port Already in Use?

If you get an error like "Only one usage of each socket address ... is normally permitted", port 7777 is already in use by another process.

Option 1: Kill the blocking process

Run fix-port.bat (Windows) or ./fix-port.sh (Linux / macOS) to:

• Detect which process is using port 7777
• Kill the process
• Restart the server

Option 2: Use a different port

Run fix-port.bat / ./fix-port.sh and select "Use a different port" to change the port in your config file.

Alternatively, manually edit commonwealth-server.json and change the "port" value to something like 7778, 8000, or 9999.

Customizing the Server

Edit commonwealth-server.json to customize:

• host: Bind address (default 0.0.0.0 for all interfaces)
• port: Server port (default 7777)
• server_name: Display name
• max_players: Metadata for client displays
• log_verbosity: debug, info, warning, or error (info hides per-packet transform spam; use debug for protocol troubleshooting)

Connecting Clients

Once the server is running:

• Local PC: Connect to 127.0.0.1:7777 (or your custom port)
• LAN: Connect to your PC's local IP (displayed on startup, e.g., 192.168.1.64:7777)
• Remote: Forward port 7777/TCP on your router and use your public IP

Stopping the Server

Type quit at the commonwealth> prompt, or press Ctrl+C.

---

For Advanced Users (Command Line)

If you prefer command-line usage, use the CLI directly:

cd server
pip install -r requirements.txt

# Generate config
python consumer_server_cli.py config init my-config.json

# Start server with interactive prompt (same as start.bat / start.sh)
python consumer_server_cli.py serve --config my-config.json --interactive

# Start server without a prompt (Host GUI / headless)
python consumer_server_cli.py serve --config my-config.json

# Management commands from another terminal while a server is running
python consumer_server_cli.py help
python consumer_server_cli.py status
python consumer_server_cli.py users
python consumer_server_cli.py world time 1430
python consumer_server_cli.py world weather 0002b52a

Run python consumer_server_cli.py --help to see all available commands.

Troubleshooting: Port in Use

If using the CLI, manually change the port:

# Generate config with custom port
python consumer_server_cli.py config init my-config.json
# Edit my-config.json and change "port" to a different number
python consumer_server_cli.py serve --config my-config.json --port 8000

Or use the CLI port override:

python consumer_server_cli.py serve --config commonwealth-server.json --port 8000