Installation

Basalt is built from source with Cargo, Rust’s build tool. There is nothing else to install: the first start creates every file and folder Basalt needs.

Requirements

• A recent stable Rust toolchain: Rust 1.92 or newer. Some of Basalt’s dependencies need that version.
• Git and an internet connection for the first build, which downloads dependencies.
• An internet connection when Basalt starts with online_mode on (the default), so it can fetch the keys used to check players’ Xbox sign-ins.

Build and run

From the root of the Basalt repository:

cargo run --release -p basalt-server

The release build is heavily optimised, so the first build takes a while. Later starts reuse it. The compiled program is target/release/basalt, and you can run it directly once it is built:

./target/release/basalt

Note

Start Basalt from the repository root. It reads game data from data/1.26.60 relative to the folder it is started in, and creates its own files in that same folder.

To see more detail in the log, set RUST_LOG:

RUST_LOG=info,basalt=debug cargo run --release -p basalt-server

Ports

Basalt listens on two ports. Open both in your firewall and forward both on your router if players join from outside your network.

Port	Protocol	Setting	Used for
19132	TCP	signaling_port	Clients start their connection here
19133	UDP	media_port	Game traffic

If the machine is behind NAT, list its public address in advertised_addresses in basalt.toml so clients are told where to send game traffic:

advertised_addresses = ["203.0.113.10"]

What the first start creates

Path	What it is
basalt.toml	Every setting, with a comment above each. See Configuration.
identity.pem	The key that identifies this installation to clients.
worlds/	World folders. The one named by world in basalt.toml is created if it does not exist.
plugins/	Plugins, plus the TypeScript typings and a tsconfig.json for writing them.
resource_packs/	Packs sent to players as they join.
structures/	.mcstructure files plugins can place.
allowlist.json, banned-players.json, banned-ips.json	The allowlist and the ban lists.
permissions.json, players.json	Operators and permission levels, and everyone who has joined.

Caution

Keep identity.pem and back it up. Clients pin its key the first time they join, so if the file is lost every player has to approve the server again.

The terminal

The terminal Basalt runs in is also its console. Type any command there, with or without the leading slash, and it runs with every permission:

op Steve
list
status

See Commands for the full list.

Stopping

Type stop in the terminal or press Ctrl+C. Either way Basalt disconnects players, saves them and the world, and exits. Players and the world are also saved on a timer while it runs (autosave_ticks).

If you press Ctrl+C a second time while Basalt is still saving, it exits at once and anything not yet saved is lost.

Updating

Pull the new source and build again. When a new version adds settings, Basalt appends them to your existing basalt.toml with their comments and defaults the next time it starts; what you wrote is left as it is.