---
title: "Self-hosting FNLB"
description: "Run your own FNLB cluster."
canonical: "https://developers.fnlb.net/docs/self-hosting"
markdown: "/docs/self-hosting.md"
---
> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Self-hosting FNLB
---
title: "Self-Hosting Guide"
sidebarTitle: "Self-Hosting"
description: "Easily self-host your own FNLB cluster using this minimal setup. FNLB is a powerful and scalable system for managing Fortnite bots at scale."
icon: "server"
---
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](https://nodejs.org/)
- A valid [**FNLB API token**](https://app.fnlb.net/account). [How the header works.](/docs/authenticating.md#header) The cluster calls `https://api.fnlb.net` and `https://gateway.fnlb.net` with that token.
- _(Optional)_ [**Bun**](https://bun.sh) – 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:
Download or clone the FNLB self-hosting project to your local machine:
```bash
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](https://github.com/Fortnite-LobbyBot/Self-Hosted/archive/refs/heads/dev.zip) as a ZIP.
Install required packages with your preferred runtime:
- Using **Node.js**:
```bash
npm install
```
- Using **Bun**:
```bash
bun i
```
Rename the `.env.example` file to `.env`:
```bash
cp .env.example .env
```
Edit the `.env` file with your actual values:
```ini
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](https://app.fnlb.net/account) under “API Tokens”.
**Category IDs:** Open a bot in the [FNLB app](https://app.fnlb.net/bots), or read them from [GET /categories](/api?method=GET&path=/categories). The id is the value you put in `CATEGORIES`.
## Running the FNLB Cluster
Once configured, start your FNLB instance:
- With **Node.js**:
```bash
npm start
```
- With **Bun**:
```bash
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:
| Variable | Description | Default |
| ------------------ | --------------------------------------------------------------- | --------------------- |
| `API_TOKEN` | Your personal FNLB API token | _Required_ |
| `CATEGORIES` | Comma-separated list of bot category IDs | _Required_ |
| `NUMBER_OF_SHARDS` | Number of individual shards (instances) to spawn | `2` |
| `BOTS_PER_SHARD` | Maximum number of bots assigned to each shard | `32` |
| `RESTART_INTERVAL` | Cluster restart interval in seconds (for stability/maintenance) | `3600` |
| `CLUSTER_NAME` | The name of the cluster that will appear in the app | `Self Hosted Cluster` |
---
## Keeping FNLB Up to Date
Ensure you're always using the latest and most stable version of FNLB:
```bash
git pull origin main
```
- With **Node.js**:
```bash
npm update fnlb
```
- With **Bun**:
```bash
bun update --latest
```
```bash
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](https://app.fnlb.net/account). 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`.
---
## From this portal
- [Authenticating](/docs/authenticating.md) covers the token in `API_TOKEN`.
- [GET /categories](/api?method=GET&path=/categories) returns the ids for `CATEGORIES`.
- [GET /shards](/gateway?method=GET&path=/shards) shows the cluster after it connects, including `clusterName` and how many bots are online.
- [Node.js SDK](/docs/sdk-node.md) is the same runtime, called from your own process instead of this repository.
Get help, support, or chat with other developers