Self-Hosting Flux

One binary. One Postgres database. Zero external dependencies.

Overview

Flux is a single Rust binary that runs five in-process modules on one port (:4000). All state lives in one Postgres database. There is no inter-service messaging, no Redis, no external queue — just the binary and Postgres.

No distributed state to manage
Single process, single port
Any Postgres 14+ host works: RDS, Supabase, Neon, Fly Postgres, or your own server
Open source — no license keys, no usage limits

Quickstart

The fastest way to run Flux is with Docker Compose.

1. Download the compose file

$ curl -fsSL https://flux.sh/docker-compose.yml -o docker-compose.yml

2. Start everything

$ docker compose up -d

This starts Flux and a Postgres instance. Flux runs migrations automatically on first startup.

3. Deploy a function

$ flux init my-app && cd my-app
$ flux dev

That's it. Flux is running at localhost:4000.

Single binary

If you prefer to run without Docker, download the binary directly:

$ curl -fsSL https://fluxbase.co/install | bash
$ export DATABASE_URL=postgres://user:password@localhost:5432/flux
$ flux serve

The flux serve command starts all five modules (Gateway, Runtime, Data Engine, Queue, API) in a single process on port 4000.

Configuration

Flux is configured via environment variables or a project.toml file.

Required

Variable	Description
`DATABASE_URL`	Postgres connection string (`postgres://user:pass@host:5432/db`)

Optional

Variable	Default	Description
`PORT`	4000	Listen port
`RUNTIME_POOL_SIZE`	4	V8 isolates in the pool
`TRACE_RETENTION_DAYS`	30	Days before execution records are deleted
`MAX_FUNCTION_DURATION_MS`	30000	Timeout per function execution
`LOG_LEVEL`	info	`trace` / `debug` / `info` / `warn` / `error`
`RUST_LOG`	—	Fine-grained module logging (e.g. `flux_gateway=debug`)

Scaling

Single server

One Flux binary handles thousands of concurrent requests. For most projects, a single instance on a $20/month VPS is more than enough.

Multiple instances

Because all state is in Postgres, you can run multiple Flux instances behind a load balancer. The gateway uses LISTEN/NOTIFY to coordinate route cache invalidation across instances.

# Scale to 4 instances
$ docker compose up -d --scale flux=4

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flux
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: flux
          image: ghcr.io/flux-run/flux:latest
          ports:
            - containerPort: 4000
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: flux-secrets
                  key: database-url

Postgres requirements

Flux requires Postgres 14 or later. Recommended options by environment:

Environment	Recommended Postgres
Local development	Included `postgres` service in docker-compose
Single VPS / Fly.io	Fly Postgres, Supabase, Neon
AWS	RDS PostgreSQL or Aurora Postgres
GCP / Azure	Cloud SQL / Azure Database for PostgreSQL
On-prem	Any Postgres 14+ instance

← Production Guide · Architecture →