Discourse AI Connect — Installation & Setup Guide

Overview

Goldnat AI Connect for Discourse consists of 2 components:

1. Sinatra bridge (Ruby) — a separate OAuth + Manifest service
2. Discourse plugin (Ruby on Rails) — installed inside the Discourse container

This structure is required because Discourse core doesn’t expose “middleware”-style plugins — the bridge needs to be standalone.

What you get:

• 5 free tools — searchTopics, getTopic, getLatestTopics, getPost, getCategories
• Pro upgrade — getUserProfile, createTopic, replyToTopic, editPost, sendMessage, likePost
• Separate Pro extension: discourse-moderator-ai-connect (Moderation + Groups + Admin)

Note: This guide assumes Discourse is already installed and running. The plugin is configured by your site administrator.

Prerequisites

• Discourse 3.1+ (installed via Docker)
• Ruby 3.1+ (ships with Discourse)
• PostgreSQL 13+
• Redis 6+
• Bridge server — Ruby 3.2+ + Sinatra
• HTTPS required
• Site admin

Installation

Step 1: Install the plugin in Discourse

Edit containers/app.yml:

Download the plugin package from your personal area at goldnat.ai and host it where your Discourse server can reach it (your own Git server or an internal URL), then reference that location:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone <your-hosted-discourse-ai-connect-url>

Run:

cd /var/discourse
./launcher rebuild app

Step 2: Run the Sinatra bridge

Download the bridge package from your personal area at goldnat.ai (sign in → your plugins → download the latest version), then extract and set it up:

cd /var/www/
# Extract the package you downloaded from goldnat.ai into ./discourse-ai-connect
cd discourse-ai-connect/sinatra_service
bundle install
cp .env.example .env

Edit .env:

DISCOURSE_URL=https://forum.example.com
DISCOURSE_API_KEY=YOUR_ADMIN_API_KEY
DB_HOST=localhost
DB_NAME=discourse_aiconnect
PORT=3086

Run under systemd or PM2:

bundle exec ruby app.rb

Step 3: Reverse Proxy

ProxyPass /api/ai-connect http://localhost:3086/api/ai-connect
ProxyPassReverse /api/ai-connect http://localhost:3086/api/ai-connect

Connecting to an AI Agent

1. https://forum.example.com/my-tokens — the bridge’s token management page.
2. Generate Prompt → paste into your agent.
3. OAuth PKCE runs → approve.

First Test

• “Search topics about deployment” → discourse.searchTopics with q=deployment
• “What categories does this community have?” → discourse.getCategories
• “What does the first topic say?” → discourse.getTopic + discourse.getPost

With Pro:

• “Create a new topic in ‘Q&A’” → discourse.createTopic
• “Like this post” → discourse.likePost

Reconnecting

Tokens valid for 30 days. Refresh:

1. My Tokens → Revoke the old.
2. Generate Prompt again.

Token Management

/my-tokens page on the bridge. Filters + revoke as with the other plugins.

Uninstalling

1. Revoke all tokens

• My Tokens → Revoke All — kills every active session.

2. Stop the Sinatra bridge

systemctl stop discourse-aiconnect-bridge
systemctl disable discourse-aiconnect-bridge

Or, if running under PM2: pm2 stop discourse-ai-connect && pm2 delete discourse-ai-connect.

3. Remove the reverse-proxy rules

• Delete the ProxyPass /api/ai-connect ... lines from your Apache/Nginx vhost.
• Reload the web server.

4. Remove the Discourse plugin

Edit containers/app.yml — remove the git clone <your-hosted-discourse-ai-connect-url> line you added for the plugin.

cd /var/discourse
./launcher rebuild app

5. Remove the bridge code

rm -rf /var/www/discourse-ai-connect

6. Drop the DB (fresh reinstall only)

DROP DATABASE discourse_aiconnect;

Warning: Deletes all token history.

Common Troubleshooting

Error	Cause	Fix
Bridge 502	Sinatra not running	systemctl status discourse-aiconnect-bridge
Plugin not loaded	Rebuild failed	./launcher logs app — check for errors
OAuth PKCE failed	Missing Discourse API Key	Verify DISCOURSE_API_KEY in .env
Topic not accessible	Category restricted	The token-generating user must be able to see the category

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 the plugin in the Discourse container + rebuild, (C) running the Sinatra bridge, (D) connecting to an AI agent + typical queries.

What Pro adds

The free Discourse bridge gives AI agents read-only access (browse topics, posts, categories, search). Pro adds the write tools, so an agent can create topics, reply, edit content, send private messages and like posts.

Pro ships as a separate package (discourse-moderator-ai-connect) that installs alongside the free bridge. The core Sinatra service 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 message to a user
likePost	write	Like or unlike a post

Enabling Pro

1. Install the free Discourse bridge first (see the basic guide above).
2. Install the discourse-moderator-ai-connect package alongside it.
3. Set the edition to Pro: AICONNECT_EDITION=pro in the Sinatra service’s environment, then restart it.
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 Discourse — the scope is the ceiling, the user’s trust level and permissions are the floor.