Self-Hosting Fluxify
Fluxify is built to run on your own infrastructure. There are two ways to deploy it, and this page helps you pick the right one and points you to the exact steps for each.
TIP
New to how Fluxify works internally? The Architecture section explains the control plane / worker split that both setups below are built on.
WARNING
Alpha software. Fluxify is in active alpha development. It is suitable for self-hosted trials and early production use, but internal schemas may change between versions — read the release notes before upgrading.
The two ways to run Fluxify
| Kit (all-in-one) | Admin + Workers (scale-out) | |
|---|---|---|
| Best for | Prototypes and testing only | Production, on one Docker host or Kubernetes |
| Containers | One — database, cache and event bus included | Separate admin + many workers |
| Scaling | Vertical only (bigger machine) | Horizontal — add workers on demand |
| Edge proxy | Built into the image | Traefik (load-balances the workers) |
| Setup effort | Lowest — one command | Moderate |
| Guide | Quick Run with the Kit Image → | Production Setup → |
Which should I choose?
Prototyping or testing? Use the Kit, and only for that: never for production. It bundles every service into a single container and starts with one command. → Quick Run guide
Anything in production, even on a single machine? Use Admin + Workers. The control plane runs once; stateless workers scale horizontally behind Traefik. The workers run on either:
- Docker: one host, a fixed number of workers per claim. → Production guide
- Kubernetes: your cluster, with workers that grow and shrink with load. → Install on Kubernetes
TIP
Start with the Kit to evaluate, then move to Admin + Workers when you need to scale — your .env and database carry straight over.
TIP
Let a coding agent do it. Claude Code, Cursor or Codex can deploy either setup from these docs. See Deploy with a Coding Agent for copy-paste prompts and a checklist to check its work.
How the pieces fit together
Both topologies share the same three backing services and the same URL layout — they differ only in how the application containers are split up.
Kit — everything in one container:
Admin + Workers — control plane split from a worker pool:
Notice that only the admin container reaches PostgreSQL. Workers receive your routes ready to run over NATS, so they never need database access — see Request Lifecycle.
Backing services (both setups)
| Service | Role |
|---|---|
| PostgreSQL | Stores workflows, project configuration, and user accounts. Only the admin container connects to it. |
| Valkey / Redis | Caching and fast lookups. |
| NATS | Delivers compiled routes to workers and keeps live configuration in sync. |
WARNING
NATS must be started with JetStream enabled (-js on the command line). Fluxify uses it to queue compile work and to store the compiled routes that workers pull. Without it the compiler will not start and your workers will have nothing to serve. The bundled compose files already set this.
URL layout (both setups)
| Path | Serves |
|---|---|
/_/admin/ui | Web dashboard (visual editor) |
/_/admin/api | Admin REST API |
/_/admin/api/openapi/ui | API documentation |
/_/admin/mcp | MCP server for AI apps and coding agents |
/.well-known/oauth-… | Sign-in details for MCP clients |
/ | Your published workflows and custom endpoints |
NOTE
Namespace isolation. Everything under /_/admin is platform management and the visual editor. The rest of the root path / is reserved for the endpoints you build in Fluxify, so your APIs never collide with the admin surface. The one exception is /.well-known/oauth-…, which MCP clients need for sign-in.
System requirements
| Resource | Kit (trial) | Admin + Workers (production) |
|---|---|---|
| CPU | 1 core | 2+ cores (plus ~1 core per worker) |
| RAM | 2 GB | 4 GB+ |
| Disk | 5 GB | 20 GB+ SSD |
| Docker | Engine 20.10+ / Desktop | Engine 20.10+ |
Generate your secret keys
Both setups need the same secrets in their .env. Generate them once here, then follow the guide for your chosen setup:
MASTER_ENCRYPTION_KEY— encrypts stored credentials.BETTER_AUTH_SECRET— signs authentication sessions.
WARNING
Back up MASTER_ENCRYPTION_KEY. If you lose or change it after storing data, every saved credential becomes permanently unreadable.
IMPORTANT
Admin and workers must share the same MASTER_ENCRYPTION_KEY. Project configuration reaches workers encrypted with it; a worker with a different key starts up and then fails every request. A worker refuses to start without one.
One more setting: which project a worker serves
A request worker serves either exactly one project, named by WORKER_PROJECT_ID, or every project with *. You get a project id from the project's settings page in the dashboard.
The production guides create the project first, then pin a worker group to its id. The Kit defaults to *, so it serves routes from the first boot without an id to copy.
To serve several projects with a pinned worker, run a separate group of workers for each. Copies of the same worker share their settings, so they always share a project.
Serving every project from one worker
Set WORKER_PROJECT_ID to * (the Kit's default) and the worker serves every project you have, picking up new ones as you create them — no restart, no id to copy.
Good for a personal install or a staging box. Give each project its own subdomain (Project settings → General) and two projects can use the same route path without clashing: shop.example.com/orders and blog.example.com/orders reach different projects. Projects without a subdomain share the bare domain, where a path used by two of them resolves to only one. The base domain is set in Instance settings → Hosting.
A slow project still slows the rest, since they share one worker.
Next steps
Pick your path and jump straight to the steps:
- Kit: run one command → turn on the request worker
- Admin + Workers: why Traefik → create your
.env→ start the stack → scale the workers - With a coding agent: pick a prompt → check its work
- On Kubernetes: install step by step → what it creates → size and scale workers