Configuration

Fluent OSS is configured through CLI flags, environment variables, and the data root directory.

CLI Flags

npm run oss:start -- --host <host> --port <port>

Flag	Default	Purpose
--host	127.0.0.1	Bind address
--port	8788	Listen port

Bind to 127.0.0.1 for local-only access. Bind to 0.0.0.0 when you want LAN or VPS access:

npm run oss:start -- --host 0.0.0.0 --port 8788

Environment Variables

Core

Variable	Purpose
FLUENT_OSS_HOST	Override bind address
FLUENT_OSS_PORT	Override listen port
FLUENT_OSS_ROOT	Override data root (default ~/.fluent/)
FLUENT_OSS_TOKEN	Override bearer token (instead of reading from disk)

Legacy Bridge

These variables still work but new setups should use the FLUENT_OSS_* equivalents:

Variable	Maps To
FLUENT_LOCAL_TOKEN	FLUENT_OSS_TOKEN

Data Root

All Fluent OSS state lives under a single root directory, defaulting to ~/.fluent/:

~/.fluent/
  db/              # SQLite database
  artifacts/       # Uploaded photos, files
  auth/
    oss-access-token.json   # Bearer token

Override with FLUENT_OSS_ROOT or --root:

npm run oss:start -- --host 127.0.0.1 --port 8788 --root /data/fluent

Token Management

Bootstrap

Generate a new token for first-time setup:

npm run oss:token:bootstrap

Print

Display the current token:

npm run oss:token:print

Rotate

Replace the current token with a new one:

npm run oss:token:rotate

TIP

After rotating the token, you need to update your MCP client configuration with the new token. Regenerate it with the scaffold command.

Token Storage

The token is stored at ~/.fluent/auth/oss-access-token.json (or under your custom FLUENT_OSS_ROOT).

The preferred environment variable is FLUENT_OSS_TOKEN. When set, it takes precedence over the on-disk token file.

Reverse Proxy / TLS

Fluent OSS itself is plain HTTP. For production or remote deployments, place a reverse proxy in front:

1. Run Fluent OSS on a private interface or internal port
2. Terminate TLS at the reverse proxy (nginx, Caddy, Traefik, etc.)
3. Forward only /mcp, /health, /codex-probe, and any image routes you intend to expose
4. Keep the bearer token secret even behind the proxy

If the proxy changes the public origin, generate client config with the proxied base URL:

npm run scaffold:mcp -- --client codex --track oss --base-url https://fluent.yourdomain.com

LAN / VPS Deployment

For LAN or VPS deployment:

npm run oss:start -- --host 0.0.0.0 --port 8788

Recommended pattern:

1. Bind Fluent OSS to a private interface
2. Put TLS and perimeter controls at the reverse proxy layer
3. Keep the bearer token secret
4. Use firewall rules to restrict access to trusted clients

Legacy Commands

The older local:* command family remains as a bridge alias:

Legacy	Current
npm run local:start	npm run oss:start
npm run local:token:bootstrap	npm run oss:token:bootstrap
npm run local:token:print	npm run oss:token:print
npm run local:token:rotate	npm run oss:token:rotate
npm run verify:local-parity	npm run verify:oss-parity

These aliases are compatibility-only. New setups should use the oss:* commands.