Installation

Fluent OSS is the self-hosted open-source runtime for Fluent. It is single-user in v1, self-hostable over HTTP, and exposes the same MCP contract as Fluent Hosted.

Source: github.com/shaner-git/fluent-oss
License: Apache 2.0

Requirements

• Node.js 18+ (for bare runtime) or Docker (recommended)
• Any Linux, macOS, or Windows machine

Quick Install

Docker (Recommended)

git clone https://github.com/shaner-git/fluent-oss.git
cd fluent-oss
docker compose --env-file .env.oss.example up --build

Bare Node.js

git clone https://github.com/shaner-git/fluent-oss.git
cd fluent-oss
npm install
npm run oss:token:bootstrap
npm run oss:start -- --host 127.0.0.1 --port 8788

What Gets Installed

Fluent OSS stores everything under ~/.fluent/ by default:

Path	Purpose
~/.fluent/db/	SQLite database
~/.fluent/artifacts/	Uploaded photos and files
~/.fluent/auth/oss-access-token.json	Bearer token

Endpoints

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

OSS Boundaries

Fluent OSS in v1:

• Single-user only
• Bearer-token auth (no OAuth)
• No /authorize or /token endpoints
• Plain HTTP (use a reverse proxy for TLS)
• Contract-compatible with Fluent Hosted
• Docker-first distribution with raw Node.js as an alternative

Verify Installation

After starting the server:

# Check liveness
curl http://127.0.0.1:8788/health

# Check the probe
curl http://127.0.0.1:8788/codex-probe

Run the full verification suite:

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

This checks:

• Open health and probe endpoints
• Bearer-token protection on /mcp
• MCP contract parity with Hosted
• Reversible writes
• Domain-event logging

Next Steps

• Docker Setup -- customize your Docker deployment
• Configuration -- tokens, ports, and environment
• Postgres + S3 -- experimental storage backend