log in
substrata logo

Running your own Substrata Server

Running your own Substrata server is (hopefully) relatively easy, as it's just a single executable to run. It will require some technical proficiency though.

You can run a Substrata server on your personal computer, or on a cloud server somewhere. It's free to run.

The instructions below are generally written for running a server on your personal computer, though they can be adapted for e.g. a cloud Linux server.


Download the server distribution for your operating system:

Windows - SubstrataServer_v1.2.15.7z

MacOS - SubstrataServerMacOS_v1.2.15_x64.tar.gz

Linux - SubstrataServer_v1.2.15.tar.gz

Extract the contents into a convenient directory, e.g. c:/substrata_server

(You will need 7-zip to extract the Windows distribution)

Executables are signed by Glare Technologies Limited on Windows and Mac: on Windows, check that server.exe has a digital signature from Glare Technologies Limited. (right click on exe, Properties, Digital Signatures tab)

Run the server

Run the server executable from the files you just extracted.

This will create the server_state_dir (if it does not already exist) described in the next section.

Locating server_state_dir

This is the top level directory where config files will be placed, and will have subdirectories where various files will be saved.

This directory will be automatically created, if it does not already exist, when the substrata server is run.

server_state_dir is:

On Windows: APPDATA/Substrata/server_data

Where APPDATA is your application data directory, something like C:\Users\YOURNAME\AppData.

On Mac: /Users/USERNAME/cyberspace_server_state

On Linux: /home/USERNAME/cyberspace_server_state

Where USERNAME is the current user name.

Generating a TLS keypair

On Windows

If you don't have OpenSSL installed, download from our server: LibreSSL_3.5.2_OpenSSL.zip.

Extract to a directory, check that openssl.exe has a Digital signature from Glare Technologies Limited. (right click on exe, Properties, Digital Signatures tab)

Open a command shell (cmd.exe or powershell), go to the directory you extracted the openssl files (openssl.exe, openssl.cnf and some dlls), and execute this command:

./openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out MyCertificate.crt -keyout MyKey.key -config openssl.cnf

It will ask some questions, you can press enter to skip them, apart from at least one: Organization name, enter anything you want.

This should generate two files: MyCertificate.crt (your public key) and MyKey.key (your private key). Copy these files into your server_state_dir.

On Linux / Mac

You probably already have openssl installed, so execute

openssl req -new -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out MyCertificate.crt -keyout MyKey.key

and copy the two generated files (MyCertificate.crt and MyKey.key) into your server_state_dir.

Downloading other server distribution files

Download this zip file: server_dist_files.zip, and extract the contents into your server_state_dir.

Your server_state_dir (i.e. C:\Users\YOURNAME\AppData\Roaming\Substrata), should now looks something like:

               -----------substrata_server_config.xml, MyCertificate.crt, MyKey.key
               |            |
               |            ---------- xbot_glb_3242545562312850498.bmesh  
                            ---------- logo_main_page.png, logo_small.png, main.css

If so, you are ready to properly run the server!

Run the server

In cmd.exe or powershell, change into the directory you extracted the server distribution, and run the server, e.g.

cd c:/substrata_server

Read the output carefully, there will probably be some warning messages, but if it doesn't exit by itself, then your server is ready to use!

Visiting in your Substrata client

Run Substrata, then enter sub://localhost in the URL bar:

Substrata connecting to localhost

You should see an empty Substrata world.

Create a user in your Substrata client using the 'Sign Up' link in the top right of your Substrata client. The first user you create will be the admin user, and will have permissions to create and destroy objects anywhere, as well as to administer the server via the admin web interface.

Visiting the local web interface

In your web browser, visit https://localhost/. Note that because we used a self-signed certificate, your browser will probably complain that the certificate is invalid ('site not secure'). Just skip these warnings.

You should see a basic substrata website:

Substrata localhost website

You can log into the web interface using the same username and password you just created in your Substrata client.

Once you have logged in, you can click on your name in the upper right of the page, then click on 'Admin Page' on the upper right of the page again, to access the administrator web interface:

Substrata admin web interface

Video tutorial

Here is a slightly out of date, but still very helpful tutorial, walking you through similar steps.


Need help running your own server? Come and chat about it on our Discord server.


To document:

* How to set up the webclient files for your server, so users can access your Substrata world via a web browser.

* How to use a TLS certificate from a public certificate authority like Let's Encrypt, instead of a self-signed certificate.