> ## Documentation Index
> Fetch the complete documentation index at: https://developer-docs.fnlb.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js SDK

> Learn how to install and control FNLB programmatically using JavaScript or TypeScript. Includes examples for running single or multiple bots, managing shards, and auto-restarting.

## 📦 Installation

Install the latest version via **npm install**:

```bash theme={null}
npm install fnlb@latest
```

Using **[bun](https://bun.sh)**? Install the latest version via **bun install**:

```bash theme={null}
bun install fnlb@latest
```

## Authentication

Pass any supported credential as `apiToken` or `token`:

| Type                | Format          | Notes                                                                                   |
| :------------------ | :-------------- | :-------------------------------------------------------------------------------------- |
| API token           | `FNLB_...`      | From [app.fnlb.net/account](https://app.fnlb.net/account)                               |
| OAuth2 access token | `FNLBOA2AT_...` | Requires the `bots.run`, `categories.read` and `bots.read`scopes, see [OAuth2](/oauth2) |

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

## Starting a Single Bot

Get started with a single bot using your [FNLB API token](https://app.fnlb.net/account). [Learn more](/authenticating):

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  apiToken: 'your-api-token', //  Replace with your actual token
  categories: ['your-category-id'] // Get this from your bot’s page
});
```

## Running Multiple Bots (Same Shard)

Run multiple bots in a **single subprocess** using the `botsPerShard` option:

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

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

## Using Multiple Shards (Subprocesses)

Scale even more by spawning multiple **shards** (subprocesses) with multiple bots each:

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  apiToken: 'your-api-token',
  categories: ['your-category-id'],
  numberOfShards: 2,     // 2 shards 
  botsPerShard: 10       // max 10 bots per shard
});
```

<Info>
  Total bots: `numberOfShards × botsPerShard`\
  In this example: 2 × 10 = **20 bots max**
</Info>

## Launching Bots Across Multiple Categories

Want to run bots from different FNLB categories? Just add them to the `categories` array:

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

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

## Starting Specific Bots by ID

Run exact bots without filtering by category using the `bots` array. Get bot IDs from your bot's page on [app.fnlb.net/bots](https://app.fnlb.net/bots).

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

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

Multiple shards can share the same `bots` list — the gateway distributes IDs across shards with no duplicates. You can combine `bots` and `categories` to narrow selection further.

Omit `categories` (or pass `[]`) to allow bots from any category. When `categories` is set, bots without a category are still included.

## Stopping All Bots

Shut everything down cleanly using the `stop()` method:

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

await fnlb.start({
  apiToken: 'your-api-token',
  numberOfShards: 2,
  botsPerShard: 10
});

await fnlb.stop(); // Stops all shards and bots
```

## Naming Your Cluster

Customize your cluster with a unique name using the `clusterName` option:

```ts theme={null}
import FNLB from 'fnlb';

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

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

## Auto-Restart Every Hour (Optional)

Want to keep things fresh? Here's how to restart your bots automatically every hour:

```ts theme={null}
import FNLB from 'fnlb';

const fnlb = new FNLB();

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

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

await startFNLB();

// Restart every hour (3600000 ms)
setInterval(restartFNLB, 3_600_000);
```

## 🔗 Useful Links

* 🌐 **[FNLB Website](https://fnlb.net)**
* 📖 **[FNLB Documentation](https://docs.fnlb.net/introduction)**
* 📄 **[FNLB Changelog](https://docs.fnlb.net/bots/changelog)**
* 🗨️ **[FNLB Discord Server](https://fnlb.net/discord)**

## 🗨️ Join the Community

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

<Card title="Join Discord" icon="discord" href="https://fnlb.net/discord">
  Get help, support, or chat with other developers
</Card>