NodeBB AI Connect — Installation & Setup Guide

Overview

Goldnat AI Connect for NodeBB turns your NodeBB forum into a Servio Protocol tool server. NodeBB is built on Node.js + Redis/PostgreSQL/MongoDB, and our plugin runs inside the NodeBB process itself.

What you get:

• 7 free tools — getCategories, getTopics, getTopic, getPost, searchTopics, getUserProfile, getRecentTopics
• Pro upgrade — createTopic, replyToTopic, editPost, sendMessage, followTopic
• Separate Pro extension: nodebb-admin-ai-connect (Moderation + Groups + Analytics)

Prerequisites

• NodeBB 3.x
• Node.js 18+
• DB backend — Redis / PostgreSQL / MongoDB (whatever NodeBB uses)
• HTTPS recommended
• Administrator permission

Installation

Via NPM (recommended)

cd /path/to/nodebb
npm install nodebb-plugin-ai-connect
./nodebb build
./nodebb restart

Via the Admin UI

1. Admin → Extend → Plugins → search for nodebb-plugin-ai-connect.
2. Install → Activate.
3. Admin → Restart NodeBB (required!).
4. After restart: Admin → Extend → Plugins — the plugin should be “Active”.

Connecting to an AI Agent

1. User Menu → AI Connect Tokens (or /user/username/ai-connect).
2. Generate Prompt — a ready-to-paste block appears.
3. Paste it into your agent → OAuth PKCE runs → approve.

First Test

• “What categories exist on this forum?” → nodebb.getCategories
• “Show 5 recent topics” → nodebb.getRecentTopics with limit=5
• “Search for topics about React” → nodebb.searchTopics with q=React

With Pro:

• “Create a new topic in ‘General’ with title X” → nodebb.createTopic
• “Reply to topic #42” → nodebb.replyToTopic

Reconnecting

Tokens valid for 30 days. Refresh:

1. AI Connect Tokens → Revoke the old.
2. Generate Prompt again.

Token Management

/user/{username}/ai-connect page with filters: Active / Renewable / Unused / Inactive / Revoked / All. Bulk revoke available.

Uninstalling the Plugin

1. Revoke all tokens

• AI Connect Tokens → Revoke All — kills every active session.

2. Deactivate the plugin

• Admin → Extend → Plugins → find nodebb-plugin-ai-connect → Deactivate.

3. Uninstall via NPM

cd /path/to/nodebb
npm uninstall nodebb-plugin-ai-connect
./nodebb build
./nodebb restart

4. Reset the plugin data (fresh reinstall only)

./nodebb reset -p nodebb-plugin-ai-connect

Warning: Deletes all token history and audit logs.

Common Troubleshooting

Error	Cause	Fix
Plugin not found after install	Rebuild didn’t run	./nodebb build && ./nodebb restart
Manifest 404	Routes not loaded	./nodebb reset -p nodebb-plugin-ai-connect
WebSocket disconnect	Proxy doesn’t support WS	Ensure nginx/apache sets Upgrade: websocket
Bearer token invalid	Token expired/revoked	Reconnect

Support

Need help? Contact us and we’ll get back to you.

Video Tutorial (Coming Soon)

Segments: (A) Goldnat AI Connect on the Servio Protocol, (B) installing via admin UI + rebuild + restart, (C) connecting to an AI agent, (D) live usage — 3 requests.

What Pro adds

The free NodeBB plugin gives AI agents read-only access (browse categories, topics, posts, search). Pro adds the write tools, so an agent can create topics, reply, edit content, message members and follow topics.

Pro ships as a separate package (nodebb-admin-ai-connect) that installs alongside the free plugin. The core plugin holds the tool infrastructure; the Pro package holds the Pro tools and registers them into the same manifest — they never appear unless the edition is Pro.

Pro tools

Tool	Scope	What it does
createTopic	write	Create a new topic in a category
replyToTopic	write	Post a reply to an existing topic
editPost	write	Edit an existing post
sendMessage	write	Send a private chat message to a user
followTopic	write	Follow or unfollow a topic for notifications

Enabling Pro

1. Install the free NodeBB plugin first (see the basic guide above).
2. Install the nodebb-admin-ai-connect package alongside it.
3. Set the edition to Pro: AICONNECT_EDITION=pro in the plugin’s .env, then restart NodeBB (./nodebb restart).
4. Regenerate your connection prompt — the five Pro tools now appear in the manifest.

Scope note

All Pro tools require the write scope. Every action runs as the token owner, so it is limited to what that user may do in NodeBB — the scope is the ceiling, the user’s permissions are the floor.