Docs

Running in under five minutes

Clone the repo, run one command, and reach a measured, revertible optimization outcome — no configuration required to start.

Get the code

1. Clone the repository

terminal

git clone https://github.com/ManojVihari/Fluxen.git
cd Fluxen

Run it

2. Deploy with Docker

One command brings up all four services — Postgres, Redis, the combined gateway/control binary, and the dashboard. Every setting has a working default: no .env file to create, no API key to set before it boots, no encryption key to generate by hand.

terminal

docker compose up --build

Prefer running the Go/Node processes yourself for local development instead of Docker? See Run locally, without Docker in the README.

First run

3. Complete the setup wizard

Open the dashboard

Visit localhost:3000. On a fresh deployment you land on the one-time setup wizard.

Create your organization and owner account

This runs exactly once per deployment — see the product overview for how Fluxen's single-tenant-per-deployment model works. Add teammates later from Settings → Users.

Add a provider credential

From Settings → Providers, add an OpenAI, Gemini, or self-hosted Ollama credential. It's encrypted at rest with a key Fluxen generates for itself — nothing to configure.

Connect your app

4. Point your existing client at Fluxen

Create an application and generate a key

Applications are Fluxen's unit of optimization. Create one, then click Generate API key on the connect screen — the raw key is shown exactly once.

Change two lines in your code

Nothing else about your application needs to change.

python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="fx_live_...",
)
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, Fluxen!"}],
)

See it work

5. Watch traffic and opportunities appear

Usage, cost, and model mix show up in Application Detail within a few minutes. Once traffic clears the minimum volume floor, detectors start surfacing real, evidence-backed opportunities in Optimizations. Want to see it immediately instead of waiting for real traffic? Run docker compose exec fluxen fluxenctl seed --demo to seed a realistic demo application and see the whole loop end to end.

Reference

Guides

Self-hosting guide

Deployment topology, environment variables (all optional), security notes, and the load-testing methodology — docs/self-hosting.md in the repo.

Concepts

Applications, opportunities, policies, the Efficiency Score formula, and value labeling (estimated/projected/measured/realized) — docs/concepts.md.

Provider setup

Configuring OpenAI, Gemini, and Ollama credentials, including the encrypted Settings → Providers flow — docs/providers.md.

Reference

API reference

A hand-maintained reference for the control API lives in docs/api-reference.md in the repository. An OpenAPI-generated reference is on the roadmap but not yet built.

View source on GitHub