Skip to content

Server Setup

Spacebar-server setup ranges in difficulty depending on how you want to configure your system. This page provides a minimal setup guide to get you up and running, you should check out the other pages on this site to take your instance to the next level.

For this guide, we assume you're familar with the terminal.

We do not recommend or support running Spacebar using services such as Ngrok or Heroku.
You must have access to a terminal for this guide.

We do not recommend using Windows to run Spacebar.


  • Git
  • NodeJS. Version 18+ (for npm, node commands) (NOTE: Ubuntu and Debian based systems often ship with an outdated version of NodeJS, so you can use NodeSource to install a newer version)
  • Python. Version 3.10 or later. Make sure this is executable via python in your terminal.
    (See: python-is-python3 package)
  • On Linux: gcc/g++. Packaged with build-essential on Debian/Ubuntu and base-devel on Arch.
  • On Windows: Visual Studio (NOT VSCode) with the Desktop development with C++ package. You do not need the full Visual Studio install, the build tools are fine.


In your terminal:

# Download Spacebar
git clone

# Navigate to project root
cd server

# Install javascript packages
npm i

# Build and generate schema. Separately, they are `build` and `generate:schema`.
npm run setup

# Start the bundle server ( API, CDN, Gateway in one )
npm run start

If all went according to plan, you can now access your new Spacebar instance at http://localhost:3001! Congrats!

If you set up your server remotely, you can use curl http://localhost:3001/api/ping to verify the server is up and running (you should set up a reverse proxy, next!).

Connecting from remote machines

For your server to be a bit more useful to those not on the same machine, you'll need to do a bit more configuration.

The official Spacebar client does automatic discovery of the endpoints it uses to communicate with the server, but it needs to retrieve those from somewhere, that being the API server.

If you don't tell the API server where to find the other services, the official Spacebar client wont be able to connect. Other clients which don't do automatic discovery will be, but that's because your users will need to provide the locations manually.

We'll be doing some server configuration in this step, which is stored in your servers database by default. By default, Spacebar uses an SQLite database in the project root called database.db, but you might not want to use that for production. If you're going to switch databases, do it now.

Once you've opened your database, navigate to the config table. You'll see 2 columns named key and value. You'll want to set the value of the rows with the following keys to the correct values.

key value
api_endpointPublic Your API endpoint. Likely "https://DOMAIN_NAME/api/v9"
cdn_endpointPublic Your CDN endpoint. Likely "https://DOMAIN_NAME"
gateway_endpointPublic Your Gateway endpoint. Likely "wss://DOMAIN_NAME"

You must wrap these values in doublequotes as they are parsed as JSON!

If you're in the CLI for this, heres some template SQL:

update config
where key = "THE_SERVICE_NAME_endpointPublic";

Now what?

Well, now you can configure Spacebar to your liking!