codex-forum

Forum-first orchestration for ECHS-backed sessions and robotics workflows. Codex Forum keeps the discussion, agent state, and adapter events in one place so you can run long-lived threads across the web UI, CLI, and external surfaces (Discord/Matrix/Slack).

Codex Forum is a vBulletin-style forum UI + API that treats a thread as the canonical state machine for a running agent. Every post is a chat turn in the session, and forums act like folders (with optional pre-prompts) that shape how the ECHS-backed robot responds. The server tracks forums, topics, posts, identities, robot state, and tool runs; adapters map external events into topics; and the UI renders the live agent trace and moderation controls.

Key capabilities:

• Forum-native agent sessions: each topic is a durable session with posts, attachments, and robot activity.
• Live robot state + tool trace: see reasoning steps, tool runs, and outputs inline in a topic view.
• Forums as folders: organize workspaces with category + pre-prompt defaults per forum.
• Adapters as first-class citizens: Discord/Matrix/Slack/web surfaces share the same contracts.
• API-first + CLI ready: OpenAPI spec, Postman collection, and CLI command shapes are included.
• Admin + automation: deployment hooks, tamper plugins, persona prompts, and rate limits are designed in.

Screenshot is generated via Playwright using the live instance, with demo content injected in the DOM for a clean marketing preview. See scripts/capture-screenshots.mjs.

apps/
  codex-forum/        # Vue 3 UI (RoboBB theme)
packages/
  core/               # Domain entities + events + service interfaces
  contracts/          # DTOs, HTTP contracts, pagination, errors
  adapters/           # Surface adapter interfaces (Discord/Matrix/Slack/Web)
  server/             # Fastify server, auth, storage, routes, ECHS bridge
  cli/                # CLI command shapes

• Forums, topics, posts, identities, and events live in packages/core.
• Event envelopes describe forum/topic/post lifecycle (forum.created, topic.created, post.edited, etc.).
• Surface adapter contracts live in packages/adapters and define inbound/outbound event mapping.

• Fastify server in packages/server with SQLite storage and optional Redis stream bus.
• Robot orchestration is handled by the ECHS agent bridge and a tamper layer for personas, rewrites, and prompt enhancers.
• Feature flags (auth, rate limiting, search, Redis stream bus) are toggled via env vars.

• Vue 3 app in apps/codex-forum with classic forum UI.
• Topic view exposes live reasoning + tool runs and supports inline moderation.
• Developer Portal provides API key + impersonation token management.

Requires Node 20+ and pnpm 9+ (10.x recommended).

corepack enable
corepack prepare pnpm@10.26.2 --activate
pnpm install

Option A: Docker (recommended)

# Build and start the application
CODEX_FORUM_BASE_URL=http://localhost:4310 \
  docker compose up -d

Option B: Local dev

# Server (Fastify)
cd packages/server
pnpm dev

# UI (Vite)
cd apps/codex-forum
pnpm dev

Defaults:

• API server: http://localhost:4310
• UI dev server: http://localhost:5173
• API base URL env: CODEX_FORUM_BASE_URL

The API is designed for automation and external adapters:

• OpenAPI spec: docs/openapi.json (also GET /api/openapi.json) — manual reference only; the contracts in packages/contracts/src/schemas.ts are the canonical API boundary.
• Postman collection: docs/postman/codex-forum.postman_collection.json
• cURL quickstarts: docs/CURL_EXAMPLES.md

Example: list forums

export CODEX_FORUM_BASE_URL="https://forum.irrigate.cc"
curl -sS "$CODEX_FORUM_BASE_URL/api/forums" | jq

Example: create a topic

export CODEX_FORUM_TOKEN="cforum_..."
export FORUM_ID="..."

curl -sS \
  -H "Authorization: Bearer $CODEX_FORUM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"API topic","body":"Created via curl."}' \
  "$CODEX_FORUM_BASE_URL/api/forums/$FORUM_ID/topics"

Key env vars (see packages/server/src/runtimeConfig.ts for the full list):

For full deployment guidance, see docs/DEPLOYMENT.md.

• The repo is intentionally interface-first: most packages define types and boundaries so the system can evolve safely.
• The Admin Panel and Developer Portal are available under /admin and /developers.
• The UI assumes forum-native auth, but the API supports API keys and impersonation tokens.

pnpm test

Playwright E2E tests live under apps/codex-forum/e2e.

• Production host: forum.irrigate.cc
• Docker Compose is the primary deployment path. See docs/DEPLOYMENT.md for reverse proxy, SSL, and scaling notes.

Copyright (c) 2026 Irrigate Collective.

Except for the separately identified components in THIRD_PARTY_NOTICES.md, Codex Forum is licensed under the GNU Affero General Public License version 3 or later.