Quickstart (Self-Host)

Get Fluent OSS running on your own machine in under ten minutes.

Prerequisites

• Node.js 18+ or Docker
• An MCP-compatible AI client (Claude Desktop, Claude Code, Codex CLI)

Option A: Docker (Recommended)

The fastest way to start:

# Clone the repo
git clone https://github.com/shaner-git/fluent-oss.git
cd fluent-oss

# Start with Docker Compose
docker compose --env-file .env.oss.example up --build

Print your bearer token:

docker compose exec fluent-oss npm run oss:token:print

The server is now running at http://127.0.0.1:8788. The named Docker volume persists your SQLite database, artifact storage, and token state across restarts.

Option B: Bare Node.js

# Clone the repo
git clone https://github.com/shaner-git/fluent-oss.git
cd fluent-oss

# Install dependencies
npm install

# Bootstrap a bearer token
npm run oss:token:bootstrap

# Start the server
npm run oss:start -- --host 127.0.0.1 --port 8788

Print your token:

npm run oss:token:print

Connect Your Client

Generate the MCP configuration for your client:

Claude

npm run scaffold:mcp -- --client claude --track oss --base-url http://127.0.0.1:8788

To write the config directly to a file:

npm run scaffold:mcp -- --client claude --track oss \
  --base-url http://127.0.0.1:8788 \
  --out ./tmp/fluent-claude.mcp.json

Codex

npm run scaffold:mcp -- --client codex --track oss --base-url http://127.0.0.1:8788

The scaffold generator reads your OSS token automatically from ~/.fluent/. You can also pass --token or --root explicitly.

Verify

Check the health endpoint:

curl http://127.0.0.1:8788/health

Run the full parity verification suite:

npm run verify:oss-parity -- --base-url "http://127.0.0.1:8788"

This checks open endpoints, bearer-token protection, contract parity, reversible writes, and domain-event logging.

What is Running

Fluent OSS exposes:

Endpoint	Auth	Purpose
GET /health	Open	Liveness probe
GET /codex-probe	Open	Codex compatibility probe
POST /mcp	Bearer token	MCP transport

All data is stored under ~/.fluent/ by default:

• SQLite database for relational state
• Filesystem directory for artifact storage (photos, etc.)
• Token state at ~/.fluent/auth/oss-access-token.json

Next Steps

• Docker Setup -- customize ports and volumes
• Configuration -- token management and environment variables
• Backup & Restore -- export and import your data
• Connecting to Claude -- detailed client setup