stezkoy / flarum-ai-openreply

1.0.0-beta.3 2026-09-10 15:34 UTC

Requires

• php: ^8.3
• flarum/core: ^2.0
• guzzlehttp/guzzle: ^7.10

MIT

• Ngo Quoc Dat
• Michael V.
• Stezkoy

• assistant
• ai
• flarum
• chatbot
• autoreply
• opencode
• openreply

Published on Packagist.org on 2026-09-10 15:38 UTC

README

A Flarum extension.

Automatically replies to new discussions (or to every post made by the original poster) using an AI assistant. Replies are generated by opencode — a headless opencode serve instance — and posted by a designated assistant user.

Each discussion gets its own persistent opencode session, so the assistant keeps full context of the conversation. The assistant's reply is inserted into the thread as a text post.

A fork of michaelbelgium/flarum-ai-autoreply, reworked to work exclusively with the opencode 1.x server API.

Requirements

• Flarum >= 2.0 and PHP 8.3
• A running opencode server instance reachable from the Flarum host

Installation

Install with composer:

composer require stezkoy/flarum-ai-openreply

Then run migrations:

php flarum migrate

Installing opencode on Ubuntu

Install the opencode CLI on the machine that runs Flarum:

curl -fsSL https://opencode.ai/install | bash

The script installs opencode into ~/.opencode/bin and prints next steps. Alternatively, install it globally via npm so the binary lands on your PATH (convenient for a systemd service later):

sudo apt-get install -y nodejs npm
sudo npm install -g opencode-ai
which opencode   # -> /usr/bin/opencode

Configure at least one AI provider for opencode (this is done once per machine, not per session):

opencode auth login

Setting up the opencode server

The AI provider(s) and API keys are configured inside opencode itself. This extension only talks HTTP to the opencode server.

Safe default: localhost only (recommended)

The server binds to 127.0.0.1 by default, so it is only reachable from the same machine. Start it with basic auth and a fixed port:

OPENCODE_SERVER_PASSWORD=your-strong-password opencode serve --hostname 127.0.0.1 --port 4096

The extension's default http://localhost:4096 matches this command. Nothing is exposed to the network; you don't need to touch the firewall.

Exposing it externally (not recommended)

Only do this if the opencode server must live on a different machine than Flarum. Always set a password:

OPENCODE_SERVER_PASSWORD=your-strong-password opencode serve \
  --hostname 0.0.0.0 --port 4096 \
  --cors https://forum.example.com

Notes:

• With --hostname 0.0.0.0 the server listens on all interfaces — restrict access with a firewall (ufw allow from <flarum-ip> to any port 4096) and put it behind TLS (Nginx/Caddy reverse proxy) if possible.
• --cors is only needed for browser-based clients. This extension calls the API from PHP, so CORS is not required for it to work.

opencode serve options

Flag	Description	Default
--port	Port to listen on	4096
--hostname	Hostname to listen on	127.0.0.1
--mdns	Enable mDNS discovery (implies 0.0.0.0)	false
--mdns-domain	mDNS domain name	opencode.local
--cors	Extra browser origins to allow (repeatable)	[]

Authentication is controlled with environment variables:

• OPENCODE_SERVER_PASSWORD — enables HTTP basic auth (required if the server is reachable by anyone else).
• OPENCODE_SERVER_USERNAME — basic auth username, defaults to opencode (the username the extension sends).

Running as a systemd service

Create /etc/systemd/system/opencode.service:

[Unit]
Description=opencode headless server (AI Open-Reply)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=opencode
WorkingDirectory=/var/lib/opencode
Environment=OPENCODE_SERVER_PASSWORD=your-strong-password
ExecStart=/usr/bin/opencode serve --hostname 127.0.0.1 --port 4096
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Adjust ExecStart if opencode lives elsewhere (which opencode), then:

sudo useradd -r -s /usr/sbin/nologin --home-dir /var/lib/opencode opencode
sudo mkdir -p /var/lib/opencode && sudo chown opencode:opencode /var/lib/opencode
sudo systemctl daemon-reload
sudo systemctl enable --now opencode
sudo systemctl status opencode

The User=opencode account stores its own provider credentials and session data. Add Environment=OPENCODE_SERVER_USERNAME=... if you changed the basic auth username.

Server recommendations

opencode is a local LLM agent runtime: it loads the model, keeps the full conversation (and often the context window) in memory, and may spawn long-running background tasks. The headless server used by this extension is no exception, so plan its resources accordingly.

Performance and stability

• Run it next to Flarum on a dedicated machine (or container), not on the same process as PHP. Reply generation can be slow (tens of seconds to minutes), so isolate it from the web stack and give it its own CPU/memory budget and network.
• Ensure the extension can reach the server. The extension uses a 600-second request timeout (OpencodeClient), so slow generations are fine, but the connection timeout is 5 seconds — the server must respond quickly at the TCP level. Keep them on the same LAN / low-latency network to avoid spurious failures.
• Watch memory. Each discussion keeps its own persistent session; long conversations and large context windows accumulate in RAM. Set a safe limit on the number of active discussions or restart the service periodically (Restart=always above) to reclaim memory.
• Use a fast network and a stable provider for the upstream LLM. generation latency and provider rate limits dominate response time.
• Apply an access token / basic auth so the server is not left open (see authentication section above).

Minimum / recommended hardware

These are rough guidelines for a CPU-only setup running a headless server that serves a small-to-medium forum. Rent a dedicated VM or container rather than sharing a tiny VPS with heavy applications.

Model size (approx.)	RAM	vCPU	Notes
Small (cloud / hosted APIs)	2–4 GB	1–2	Model runs on the provider, little local load
Local 7–8B quantized model	16 GB	4	Comfortable for multi-session use
Large 70B+ / many concurrent	64 GB+	8+	Heavy; prefer hosted APIs instead

If you are using hosted APIs (recommended for most forums), opencode itself only needs modest resources — the table's first row. Save the bigger rows for running local models.

In the extension's admin settings page:

• opencode server URL — the address of your headless opencode server (default http://localhost:4096).
• opencode server username — the basic auth username (default opencode). Used only when a password is set.
• opencode server password — the OPENCODE_SERVER_PASSWORD value if basic auth is enabled.
• Agent — a preset that shapes how the assistant replies: the standard build (answers right away) or plan (thinks the answer over first), or the default. The server-side validation falls back to the default agent (with a server-log warning) if a saved name is unknown, so a reply never fails on a typo.
• System prompt (persona) — optional free-text instructions for the assistant's behavior, sent with every message (this is what makes "call yourself Pupsik" type personas work without editing the server config).
• Model — the model to use, in provider/model format (e.g. opencode/big-pickle). Type it manually, or click Get free models to fetch the currently available free models from your opencode server and click one to fill the field. Leave empty to use the server's default model. This is independent of the agent: the agent fixes how it behaves, the model fixes which AI answers.
• User assistant — the user ID of the account that posts the AI replies (required).
• User assistant badge — a toggle plus the text shown in the badge below the assistant's posts. Disabled or empty — no badge is rendered.
• Enable on discussion start — when enabled, the AI replies only when a discussion is started. When disabled, the discussion becomes a chat between the OP and the assistant.
• Tags — restrict the assistant to specific tags.
• Actions — three buttons: Check connection (server health + current model), Count sessions (total sessions on the server and how many belong to this extension), and Close all sessions (closes this extension's sessions in bounded batches — if some remain, click again; other server sessions are left untouched).
• Resource limits — max_active_sessions, max_messages_per_session, session_ttl_days. Set 0 to disable a limit.
• Retries — retry_attempts (total attempts, default 1, max 10) and retry_delay_seconds (delay before each retry, default 1, max 120) for requests to the opencode server.

The agent and model are sent with each request, so new discussions pick up the latest setting. The assistant's instructions (a "system prompt") are configured on the agent itself, e.g. in opencode.json:

{
  "agent": {
    "prompt": "You are a helpful assistant on a Flarum forum. Answer in the language of the user's post."
  }
}

Also grant the "Use AI assistant" permission to the desired user groups.

Features

• Auto-reply to new discussions using AI
• Chat mode: a discussion becomes a 1-on-1 chat between the OP and the assistant
• Persistent per-discussion context (one opencode session per discussion)
• Replies are posted as regular text posts by a designated assistant user
• Restrict the assistant to selected tags
• Permission controls for who can trigger the auto-reply
• Replies go through the full Flarum event lifecycle: discussion counters, last-post pointers and subscriber notifications stay correct
• Dynamic free model list fetched live from the opencode server (no hardcoded presets)
• Configurable retries (retry_attempts, retry_delay_seconds) and resource limits

Updating

composer update stezkoy/flarum-ai-openreply
php flarum migrate
php flarum cache:clear

Links

• Packagist
• GitHub
• Discuss