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.