FNLB – Self-Host Your Own Fortnite Bot

Self-host and scale Fortnite lobby bots for Bot Lobbies with the official FNLB Node.js / Bun SDK.

npm install fnlb@latest
# or
bun install fnlb@latest

You need Node.js 22+ or Bun, and an API token from your FNLB account.

Start your first bot

Create a client, then call start() with your token and the category that owns the bot.

import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  token: 'your-api-token', // https://app.fnlb.net/account
  categories: ['your-category-id'] // bot page → About this bot → Category ID
});

When you're done:

await fnlb.stop();

Authentication

start() accepts token (API Token or OAuth2 access token):

| Credential | Prefix | Where to get it | | --- | --- | --- | | API token | FNLB_… | app.fnlb.net/account | | OAuth2 access token | FNLBOA2AT_… | Needs bots.run, categories.read, and bots.read (see OAuth2 docs) |

await fnlb.start({
  token: 'FNLBOA2AT_...',
  categories: ['your-category-id']
});

Run more bots on one process

botsPerShard is the max number of bots that can run inside a single shard (subprocess):

import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  token: 'your-api-token',
  categories: ['your-category-id'],
  botsPerShard: 10
});

Scale with multiple shards

Each shard is its own subprocess. Multiply shards × bots-per-shard for your capacity ceiling:

import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  token: 'your-api-token',
  categories: ['your-category-id'],
  numberOfShards: 2,
  botsPerShard: 10 // up to 20 bots total
});

Choose which bots to run

By category

Pass one or more category IDs. Find them on app.fnlb.net/bots → select a bot → About this bot → Category ID.

await fnlb.start({
  token: 'your-api-token',
  categories: ['category-id-1', 'category-id-2'],
  numberOfShards: 2,
  botsPerShard: 10
});

By bot ID

Pass exact bot IDs from the same About this bot panel (FNLB ID):

await fnlb.start({
  token: 'your-api-token',
  bots: ['bot-id-1', 'bot-id-2'],
  botsPerShard: 2
});

How selection works

categories and bots are include lists:

• Categories only - bots in those categories, plus unassigned bots
• Bots only - only the listed IDs
• Both - union of category bots and listed bot IDs
• Neither - your full bot pool

Invalid IDs are ignored. Multiple shards can share the same bots list; the gateway assigns each ID to one shard.

await fnlb.start({
  token: 'your-api-token',
  categories: ['category-id-1', 'category-id-2'],
  bots: ['bot-id-1', 'bot-id-2'],
  numberOfShards: 2,
  botsPerShard: 10
});

Omit categories (or pass []) when you only want specific bot IDs from any category. If categories is set, bots without a category are still included.

Update selection without restart

After start(), you can change which categories/bots the running shards may use without calling stop().

Optional second argument: a partial category config applied to those ids (same merge rules as overrideCategoryConfig).

import FNLB from 'fnlb';
import { CategoryConfigPartyPrivacy } from '@fnlb-project/shared/types';

const fnlb = new FNLB();

await fnlb.start({
  apiToken: 'your-api-token',
  categories: ['category-id-1'],
  botsPerShard: 10
});

// Expand the include list
fnlb.addCategories(['category-id-2'], {
  privacy: CategoryConfigPartyPrivacy.Private
});
fnlb.addBots(['bot-id-1'], {
  acceptFriendRequests: false
});

// Replace the include list
fnlb.setCategories(['category-id-2', 'category-id-3']);
fnlb.setBots(['bot-id-1', 'bot-id-2'], {
  statusText: ['Custom status']
});

// Clear (back to unrestricted)
fnlb.setCategories();
fnlb.setBots();

// Shrink it (bots that no longer match are stopped; capacity refills from the new pool)
fnlb.removeCategories(['category-id-1']);
fnlb.removeBots(['bot-id-1']);

// Current include lists (`undefined` = unrestricted for that dimension)
fnlb.getCategories();
fnlb.getBots();

Rules:

• undefined means unrestricted for that dimension.
• add* on an unrestricted dimension starts an include list (narrows from “all”).
• add* on an existing list unions and dedupes.
• set* replaces the list (undefined / omitted = unrestricted).
• remove* on unrestricted is a no-op.
• Removing until empty returns that dimension to unrestricted.
• Overrides passed to add* / set* are stored per id and removed with remove* (or when set* drops that id).
• Throws if no shards are running.

Override category settings at start

Change a few category options for this run without editing the dashboard.

overrideCategoryConfig is scoped. Merge order (later wins): FNLB config → all → matching category → matching bot.

import FNLB from 'fnlb';
import { CategoryConfigPartyPrivacy } from '@fnlb-project/shared/types';

const fnlb = new FNLB();

await fnlb.start({
  apiToken: 'your-api-token',
  overrideCategoryConfig: {
    // every bot
    all: {
      acceptFriendRequests: false
    },
    // bots in this category
    categories: {
      'category-id-1': {
        privacy: CategoryConfigPartyPrivacy.Private
      }
    },
    // one specific bot
    bots: {
      'bot-id-1': {
        statusText: ['Special bot']
      }
    }
  }
});

Overrides stay applied even if the category config is updated live.

See CATEGORY_CONFIG.md for every supported key and type.

Name your cluster

Useful when you run more than one host and want clear logs / gateway labels:

import FNLB from 'fnlb';

const fnlb = new FNLB({ clusterName: 'MyAwesomeCluster' });

await fnlb.start({
  token: 'your-api-token'
});

Restart on a schedule

import FNLB from 'fnlb';

const fnlb = new FNLB();

async function startFNLB() {
  await fnlb.start({
    token: 'your-api-token',
    categories: ['your-category-id'],
    numberOfShards: 1,
    botsPerShard: 5
  });
}

async function restartFNLB() {
  console.log('Restarting FNLB...');
  await fnlb.stop();
  await startFNLB();
}

await startFNLB();
setInterval(restartFNLB, 3_600_000); // every hour

Prefer a ready-made env-based launcher? Use the Self-Hosted template.

Options reference

Constructor (FNLBConfig)

| Option | Description | | --- | --- | | clusterName | Label for this cluster in logs / gateway | | fnlbPath | Directory for the .fnlb download cache (default: current working directory) | | channel | Default release channel: stable | beta | dev | | updateIntervalMs | How often to check for package updates | | maxDownloadRetries / maxBackoffMs | Download retry behavior | | onLogMessage / onSubProcessLogMessage | Log callbacks | | disableLogs / disableErrorLogs | Mute SDK logs | | disableSubProcessLogs / disableSubProcessErrorLogs | Mute shard stdout/stderr mirroring |

start() (StartConfig)

| Option | Description | | --- | --- | | token | Auth credential (one required) | | categories | Category ID include list | | bots | Bot ID include list | | numberOfShards | Number of subprocesses (default 1) | | botsPerShard | Max bots per shard (default 1) | | overrideCategoryConfig | Scoped partial category config for this run - see CATEGORY_CONFIG.md | | channel | Release channel for this run | | logLevel | 'INFO' or 'DEBUG' (LogLevel enum exported) | | hideUsernames / hideEmails | Redact PII in shard logs | | extraEnv | Extra env vars passed into each shard process |

Links

• Category config reference
• Website
• Documentation
• Node.js SDK docs
• Changelog
• Discord