Postgres + S3 (Experimental)

Fluent OSS has an experimental storage backend that replaces SQLite and filesystem storage with Postgres and S3-compatible object storage. The MCP contract and all tool behavior remain identical.

WARNING

This backend is experimental. The default supported production backend is SQLite + filesystem. Use this if you already want managed relational storage or shared object storage.

What This Is

• Same single-user OSS runtime
• Same bearer-token auth on /mcp
• Postgres for relational state (instead of SQLite)
• S3-compatible storage for artifacts (instead of filesystem)
• Additive storageBackend: "postgres-s3" in capabilities metadata

Required Environment Variables

Start from the example file:

cp .env.postgres-s3.example .env.postgres-s3

Then fill in the following required variables:

Variable	Purpose
FLUENT_POSTGRES_URL	Postgres connection string
FLUENT_S3_ENDPOINT	S3-compatible endpoint URL
FLUENT_S3_REGION	S3 region
FLUENT_S3_BUCKET	S3 bucket name
FLUENT_S3_ACCESS_KEY_ID	S3 access key
FLUENT_S3_SECRET_ACCESS_KEY	S3 secret key
FLUENT_S3_FORCE_PATH_STYLE	Use path-style addressing (for MinIO, etc.)

Optional variables:

Variable	Purpose
FLUENT_OSS_HOST	Bind address
FLUENT_OSS_PORT	Listen port
FLUENT_OSS_ROOT	Still used for auth state and local operator files

TIP

FLUENT_OSS_ROOT is still used for auth state and local operator files even though relational data and artifacts live outside the filesystem.

Example Local Stack

A practical local setup uses:

Service	Address
Postgres	127.0.0.1:55432
MinIO	127.0.0.1:59000
Fluent OSS	127.0.0.1:8788

The example env file is already shaped for this style of stack.

Getting Started

1. Copy and fill in the environment template:

cp .env.postgres-s3.example .env.postgres-s3
# Edit .env.postgres-s3 with your Postgres and S3 credentials

2. Export the env vars into your shell.

3. Validate connectivity, schema bootstrap, and bucket access:

npm run oss:check:postgres-s3 -- --host 127.0.0.1 --port 8788

4. Start the runtime:

npm run oss:start:postgres-s3 -- --host 127.0.0.1 --port 8788

5. Verify:

curl http://127.0.0.1:8788/health
curl http://127.0.0.1:8788/codex-probe

Snapshot Import / Export

Export from the Postgres + S3 backend:

npm run oss:export:snapshot -- --backend postgres-s3 \
  --out "./tmp/fluent-oss-postgres-s3-snapshot.json"

Import into the Postgres + S3 backend:

npm run oss:import:snapshot -- --backend postgres-s3 \
  --file "./tmp/fluent-oss-postgres-s3-snapshot.json"

Portability

What moves cleanly:

• Relational rows
• Artifact metadata rows

What does not move yet:

• Artifact binary bytes inside the snapshot JSON
• Automated object-store-to-object-store blob migration

Technical Notes

• The bootstrap schema is a current-state Postgres snapshot, not a replay of every historical SQLite migration
• This backend proves Fluent can run on a third storage stack without changing the MCP contract
• Cloud and default SQLite OSS remain the supported release paths