Skip to main content

View GitHub Repository (optional)

Browse the full source code, issues, and updates on GitHub

​
Prerequisites

Before you begin, make sure you have the following installed and ready:
  • Node.js (version 22 or newer) – Download Node.js
  • A valid FNLB API Token – required to authenticate with FNLB services. Learn more.
  • (Optional) Bun – A fast JavaScript runtime that can be used as an alternative to Node.js

​
Installation Steps

Follow these steps to get your FNLB cluster up and running:
1

Clone the Repository

Download or clone the FNLB self-hosting project to your local machine:
git clone https://github.com/Fortnite-LobbyBot/Self-Hosted.git
cd Self-Hosted
Alternatively, you can manually copy the files into a folder or download the source code as a ZIP.
2

Install Dependencies

Install required packages with your preferred runtime:
  • Using Node.js: 
    npm install
  • Using Bun: 
    bun i
3

Configure Environment Variables

Rename the .env.example file to .env:
cp .env.example .env
Edit the .env file with your actual values:
API_TOKEN=your_token_here
CATEGORIES=12345678,98765432
NUMBER_OF_SHARDS=2
BOTS_PER_SHARD=32
RESTART_INTERVAL=3600
CLUSTER_NAME=Self Hosted Cluster
API Token: Get this from your FNLB Account under “API Tokens”.
Category IDs: Visit the FNLB Bots Page, select a bot, and locate the “Category ID” in the “About this bot” section.

​
Running the FNLB Cluster

Once configured, start your FNLB instance:
  • With Node.js: 
    npm start
  • With Bun: 
    bun start:bun
The cluster will initialize using your configuration and automatically restart on the interval you defined, ensuring long-term stability and uptime.

​
Environment Variable Reference

Below is a breakdown of each environment variable used in the setup:
VariableDescriptionDefault
API_TOKENYour personal FNLB API tokenRequired
CATEGORIESComma-separated list of bot category IDsRequired
NUMBER_OF_SHARDSNumber of individual shards (instances) to spawn2
BOTS_PER_SHARDMaximum number of bots assigned to each shard32
RESTART_INTERVALCluster restart interval in seconds (for stability/maintenance)3600
CLUSTER_NAMEThe name of the cluster that will appear in the appSelf Hosted Cluster

​
Keeping FNLB Up to Date

Ensure you’re always using the latest and most stable version of FNLB:
1

Pull the latest changes from the Git repository

git pull origin main
2

Update dependencies

  • With Node.js: 
    npm update fnlb
  • With Bun: 
    bun update --latest
3

Restart the cluster to apply changes

npm start
# or
bun start:bun
Regular updates provide access to new features, performance boosts, and essential bug fixes.

​
What the Script Does

Once started, the script performs the following:
  • Initializes FNLB using your API credentials and environment settings
  • Configures:
    • Number of shards (isolated bot processes)
    • Maximum bots per shard
    • Allowed category IDs
  • Implements automatic restarts for resilience, using the configured time interval

​
Troubleshooting

If you encounter issues while setting up or running your FNLB cluster, check the following common solutions:

​
Invalid API Token Error

  • Cause: The API_TOKEN in your .env file is incorrect or has been revoked.
  • Solution: Double-check your token in the FNLB Dashboard. Ensure there are no leading or trailing spaces.

​
Shards Crashing on Startup

  • Cause: Insufficient system resources (RAM/CPU) or Node.js version mismatch.
  • Solution: Ensure you are using Node.js 22+. If running many shards, monitor your memory usage. Try reducing NUMBER_OF_SHARDS to test.

​
Connection Issues

  • Cause: Network connectivity issues.
  • Solution: Ensure your server has outbound access to api.fnlb.net and gateway.fnlb.net.

​
📎 Additional Resources

​
🗨️ Join the Community

Need help, support, or just want to chat with other developers? Come hang out with us on Discord! 👇

Join Discord

Get help, support, or chat with other developers