---
title: "How to host a BattleSpades server"
description: "Host an Ace of Spades Battle Builder server with BattleSpades: portable releases, configuration, UDP port 27015, bots, maps, and security."
canonical: "https://aosplay.net/host-a-server"
markdown: "https://aosplay.net/docs/host-a-server.md"
last_updated: "2026-07-16"
content_type: "TechArticle"
keywords: ["host Ace of Spades server","BattleSpades hosting guide","Ace of Spades server port 27015","Battle Builder private server","run voxel game server"]
---

# How to host a BattleSpades server

> Host an Ace of Spades Battle Builder server with BattleSpades: portable releases, configuration, UDP port 27015, bots, maps, and security.

You can run a private playtest, a community game night, or a persistent public server without rebuilding the original backend. The fastest path is a portable BattleSpades alpha; the source path is better when you plan to change modes, commands, plugins, protocol behavior, or the simulation itself.

![Castle Wars Ace of Spades map preview showing opposing voxel fortifications](https://aosplay.net/game/maps/castlewars.png)

_A private Castle Wars match is a good first deployment: small group, familiar objectives, and plenty of world mutation to validate._

## At a glance

| Value | Meaning |
| --- | --- |
| 27015 | default UDP port |
| 24 | default player slots |
| 6 | implemented modes |
| 3 | desktop operating systems |

## Choose a portable or source build

Portable 0.0.2 alpha archives are the shortest route to a running host. They include the launcher, Python and native runtime, configuration, VXL maps, KV6 prefabs, plugin directory, and notices. Select the archive for Windows, Linux, or macOS and for x86-64 or ARM64.

A source build supports Python 3.10 through 3.12, with Python 3.12 as the primary development target. You also need a C/C++ toolchain because Cython extensions and the pinned ENet transport are compiled locally.

> **Before publishing — Change the default administrator password.** The sample configuration uses changeme. Replace it before opening UDP port 27015 to the internet.

## Start a portable server

Extract the entire archive rather than copying only the executable. Maps, native libraries, configuration, plugins, and notices are part of the runtime. Run the built-in check first so missing files or an invalid configuration fail before players arrive.

The first macOS alpha is unsigned and not notarized, so the host may need an explicit local Gatekeeper override. That is an operator decision; the release does not claim Apple notarization.

**Portable validation and launch**

~~~text
Windows
.\BattleSpades.exe --check
.\BattleSpades.exe

Linux or macOS
./BattleSpades --check
./BattleSpades
~~~

## Build from source

Use a virtual environment so compiled dependencies stay isolated from other Python projects. The platform install scripts clone dependencies, build the extensions, and leave the normal Python entry point available for development.

Stop the server before rebuilding Cython extensions. A running Windows process locks the loaded native modules, and rebuilding over them will fail.

**Clone, install, and run**

~~~text
Linux or macOS
 git clone https://github.com/KikoTs/BattleSpades.git
 cd BattleSpades
 ./scripts/install.sh
 python run_server.py

Windows PowerShell
 git clone https://github.com/KikoTs/BattleSpades.git
 cd BattleSpades
 .\scripts\install.ps1
 python run_server.py
~~~

## Configure the match before opening the port

The editable config.toml file controls identity, networking budgets, maps, modes, bots, game rules, classes, equipment, weapons, administration, and plugins. Start with a small, predictable setup and change one category at a time.

The simulation tick rate should remain 60 unless you are actively developing and validating client parity. It is not a generic performance knob: client behavior is calibrated around the current fixed rate.

- Set a recognizable server name and choose the default VXL map
- Choose tdm, ctf, classic_ctf, arena, vip, or zombie as the default mode
- Keep the default 24 slots for a first public test, then measure before raising it
- Set bot_count to populate an empty server or test objectives
- Review friendly fire, fall damage, block damage, respawn, class, and equipment rules
- Set strong administrative credentials and remove values you do not use

## Network and firewall checklist

BattleSpades listens on UDP port 27015 by default. A host behind a home router normally needs a UDP port-forward from the public address to the machine running the server. The operating-system firewall must allow the same inbound UDP port.

Test locally first, then from another device on the local network, and finally from outside the network. A local connection proves the server is running; it does not prove the router, carrier, cloud security group, or upstream network permits public traffic.

1. **Local.** Connect a compatible client to 127.0.0.1:27015 on the host machine.
2. **LAN.** Connect from a second device using the host’s private network address.
3. **Public.** Forward UDP 27015 and test from a different internet connection.
4. **Observe.** Watch logs, tick timing, packet backlog, map transitions, and reconnect behavior during a real match.

## Publish a verified community listing

Once the server is reachable from the public internet, send its game and query ports to POST /api/master/servers/register on the revival website. The service uses the source address it observes instead of trusting a caller-supplied IP address, then imports the server name, map, mode, region, version, and population from a verified UDP A2S_INFO response.

A successful probe creates a community listing and returns a server-scoped token once. Store that token as a secret and use it for heartbeats from that server only. A timed-out or invalid probe remains pending and is never silently published; fix the firewall, forwarding, or server response and request verification again.

- Expose the configured game port over UDP before registering
- Send only the public game and query ports; live match metadata comes from A2S
- Keep the returned aos_srv token private and rotate it by registering again if it is exposed
- Use the scoped token for that server's heartbeat rather than the internal master write token
- Keep direct-connect instructions available so discovery outages never stop independent play

## Operate it like a small service

Back up configuration, custom maps, prefabs, plugins, and moderation data before upgrades. Validate a new archive or source revision on a separate port before replacing a working public instance.

For ongoing hosting, use a service manager appropriate to the operating system, capture logs with bounded retention, and document who can restart or administer the process. The repository runbook contains the deeper capacity, parity, bot, map, mode, and release validation gates used by the project.

## Frequently asked questions

### Do players need Python installed?

No. Players only need a compatible client. Hosts using a portable BattleSpades archive also do not need a system Python installation or compiler.

### Which port should I forward?

The default is UDP port 27015. If you change the configured port, update the operating-system firewall, router or cloud security rule, and the address shared with players.

### Can I host a match with bots only?

Yes. The configurable bot worker supports voxel navigation, class actions, and roles for the implemented modes, which is useful for development and low-population sessions.

### Should I change the 60 Hz tick rate?

Not for ordinary hosting. The server and client parity work is calibrated around a 60 Hz simulation, and changing it can alter movement and reconciliation behavior.

## Related reading

- [BattleSpades dedicated server](https://aosplay.net/dedicated-server) ([Markdown](https://aosplay.net/docs/dedicated-server.md))
- [Inside the Ace of Spades protocol 168](https://aosplay.net/protocol-168) ([Markdown](https://aosplay.net/docs/protocol-168.md))
- [A master server for reconnecting the community](https://aosplay.net/master-server) ([Markdown](https://aosplay.net/docs/master-server.md))

---

Source: [How to host a BattleSpades server](https://aosplay.net/host-a-server)  
Maintained by Ace of Spades Revival contributors.