First Server Run

What happens on first start

On startup, VoiceCraft looks for ServerProperties.json in the current directory and subdirectories.

If the file is not found, the server automatically creates:

• config/
• config/ServerProperties.json

This file becomes the main persistent source of truth for server behavior.

Default ports and endpoints

By default the generated config is aligned like this:

• VoiceCraft UDP: 9050
• McHttp: http://127.0.0.1:9050/
• McWss: ws://127.0.0.1:9051/
• McTcp: 127.0.0.1:9050

Notes:

• UDP voice traffic and some transport defaults share 9050
• McWss is separated by default on 9051
• McTcp is especially relevant for GeyserVoice

Startup arguments

VoiceCraft server supports these root arguments:

• --exit-on-invalid-properties Exit if ServerProperties.json cannot be parsed.
• --language <culture> Override server log language for the current run.
• --transport-mode <mode> Enable a subset of Minecraft transports for the current run.
• --transport-host <host> Override the configured Minecraft transport host.
• --transport-port <port> Override the configured Minecraft transport port.
• --server-key <token> Override the shared Minecraft-side login token for the current run.

Short aliases also exist in code:

• -eip
• -l
• -tm
• -th
• -tp
• -sk

Examples

Run with a startup language override

./VoiceCraft.Server --language en-US

Exit if config is invalid

./VoiceCraft.Server --exit-on-invalid-properties

Run only McTcp for a Java bridge

./VoiceCraft.Server --transport-mode tcp --transport-host 0.0.0.0 --transport-port 9050

Run only McHttp

./VoiceCraft.Server --transport-mode http --transport-host 0.0.0.0 --transport-port 9050

Override token without editing JSON

./VoiceCraft.Server --server-key "replace-with-secure-token"

How transport overrides behave

Runtime overrides do not permanently rewrite ServerProperties.json.

They apply only to the current process and are useful when:

• running multiple environments from one image
• using panels or systemd drop-ins
• testing direct vs proxy topologies
• letting another tool such as GeyserVoice launch the runtime with generated values

First-run checklist

1. Change all generated login tokens.
2. Confirm which transport you actually need:
   • McHttp for BDS
   • McWss for local worlds
   • McTcp for GeyserVoice
3. Verify host bindings.
4. Open only the ports you need.
5. Confirm PositioningType with your clients.
6. Test client connection before connecting Minecraft automation.

Common first-run mistakes

• leaving generated tokens unchanged
• exposing 127.0.0.1 endpoints to remote nodes
• forgetting that McTcp may be required by Java-side bridges
• enabling every transport in production without actually needing them

For the full config reference, see ServerProperties.json.