Get Flui running

Everything else in these docs assumes you have done what this page describes.

This page has no dashboard tab, because the dashboard is one of the things this command installs. Until it has run, there is no dashboard to run it from. So the first hour belongs to the CLI, or to app.flui.cloud, which runs the same install from the web on the providers Flui integrates and hands it over to you with flui env adopt.

What you end up with is the control cluster: the cluster that carries Flui itself, with the dashboard, the API, the identity provider, the database, and the metrics and logs. One command brings all of it up together.

First, the vault

Flui keeps provider tokens and SSH keys on your machine. A key kept in the same folder as what it seals protects nothing from anyone who can read the folder. So set up the vault before you store a single credential.

flui vault init      # choose a passphrase, once per machine
flui vault unlock    # open it for this session
flui vault status    # is it open, and for how long
flui vault lock      # close it now

flui vault init asks for a passphrase and suggests a five-word one you can remember. Write it down before you continue. It is not stored anywhere and cannot be reset. If you lose it, you lose every credential this machine has sealed.

flui vault unlock asks once. A small background process then holds the key in memory for the session and overwrites it when you lock. You are asked once per session, not once per command.

A locked vault is not an error by itself. Commands that only read a preference or an endpoint never ask for anything. Only a command that opens a stored credential stops, and it tells you to run flui vault unlock.

If this machine already holds credentials sealed outside the vault, the first unlock moves them in and removes the plaintext copies.

Two ways to get a machine

Flui can buy the server for you, or install onto a Linux machine you already have.

A provider Flui provisions on. flui env create creates the control cluster on a provider Flui integrates. Flui buys the server, sets up the private network and the firewall, then installs on top. Where the provider has no firewall Flui can drive, the Flui firewall is applied on the machine itself; everything else is the same.
A machine you already own. A rented server, a server in an office, a spare machine under a desk. Pass --host and Flui installs over SSH. It buys nothing and creates nothing at any provider. The machine has to run Ubuntu 22.04 or 24.04.

Both paths give you the same result, and nothing later in these docs depends on which one you took.

Store the credentials it needs

If you skip this, flui env create asks for the same things when it needs them and saves your answers. Storing them up front lets the run go unattended.

flui config set email you@example.com
flui config set hetzner --stdin      # then paste the token
flui config set scaleway             # a pair of values, interactive
flui config set ovh                  # a pair of values, interactive

For OVHcloud, the pair is the OpenStack username and password of a Public Cloud user, not an OVH API application key. Create the user in the OVH Manager under Public Cloud → Users & Roles; the password is shown once, when the user is created. The credential must reach exactly one OpenStack project.

Prefer --stdin over passing the value as an argument. Every process on the machine can see an argument through the process list, which is not acceptable for a credential on a shared or managed host.

Create it on a provider

flui env create

That is the whole command for the common case. It picks the provider you have credentials for, the provider’s recommended server size and its default region, and streams the installation log as it runs.

The main flags:

Flag	What it decides
`-p, --provider`	`hetzner`, `scaleway` or `ovh`. Omit it when only one is configured.
`-r, --region`	Where the server sits. Defaults to the provider’s default.
`--node-size`	The shape of the server. Defaults to the provider’s recommended size.
`--node-count`	Worker nodes. Default `0` (master only).
`--acme-staging`	Issue a staging certificate instead of a real one.
`--auth-mode`	Only `oidc`.
`--ssh-mode`	Whether this machine keeps a way in afterwards.
`--non-interactive`	Never ask a question; fail instead.

Region and size are provider words

A size code that exists on one provider means nothing on another. To see what a provider offers:

flui server-types list --provider hetzner
flui server-types list --provider scaleway --region fr-par
flui server-types list --provider ovh --region EU-SOUTH-MIL

Flui accepts a fixed set of regions per provider. If you ask for one outside it, the command stops before anything is bought and names the regions it accepts: nbg1, fsn1, hel1, ash, hil and sin on Hetzner; fr-par, nl-ams, pl-waw on Scaleway; GRA, SBG, RBX-A, EU-WEST-PAR, EU-SOUTH-MIL, DE, UK, WAW, BHS, SGP and SYD on OVHcloud.

On OVHcloud the list is only part of the picture. Which regions your account can reach is decided per project, so Flui reads them from OVHcloud itself rather than from a table. Once your credentials are stored, flui server-types list --provider ovh --region <code> shows what a region offers. Milan and Paris carry only the current-generation c3/b3/r3 shapes, so the cheap d2 family is not available there.

`--acme-staging`, and why you might want it

By default the cluster comes up with a real, browser-trusted certificate. That is what you want for an installation you intend to keep.

--acme-staging asks for a Let’s Encrypt staging certificate instead. Browsers do not trust it, and your CLI complains until you allow it, but it does not count against the production rate limits. If you expect to build and tear down the same installation several times in a week, use it. The production limits run on rolling windows and cannot be reset on request.

`--auth-mode`

Only oidc is supported. Naming anything else stops the command instead of falling back silently. The identity provider is installed as part of the cluster, and you log in against it afterwards.

`--ssh-mode`, or: who can open a shell later

This flag decides who holds the keys.

ca (the default) enrols this machine’s SSH certificate authority on every node and leaves it there. Your machine can open a shell on those servers from now on. Use it when you are building your own installation.
ephemeral-key creates no certificate authority at all. The run uses a throwaway key, revokes it on the nodes and deletes it at the provider before it finishes. When the run ends, nothing can open a shell on those servers, neither you nor Flui, until the owner runs flui env adopt. Use it when you are provisioning on someone else’s behalf.

--ssh-mode ephemeral-key requires --wait or -d/--detached. The default mode follows the installation log over SSH, and this mode enrols no certificate to authenticate with. Without one of those flags the command would not fail; it would hang for ten minutes while you pay for the servers.

`--non-interactive`

In a script or a managed runner, a prompt does not fail. It waits forever while you pay for the servers. --non-interactive turns every missing answer into an error instead of a question.

It adds one rule. If the firewall is being configured, you must also pass --firewall-ip. Auto-detection resolves the address of whichever machine runs the command. That is right on your laptop but wrong in CI, where it would open the cluster to the runner and lock you out. Pass --no-configure-firewall to skip firewall setup entirely instead.

Install onto a machine you already own

With --host, nothing above about providers applies. There is no region, size or worker count to choose; you install on the machine you have.

flui env create --host 203.0.113.10
flui env create --host box.example.com --user ubuntu --port 2222

Flag	What it decides
`--host`	The address to install onto. Passing it turns this mode on.
`--port`	SSH port. Default `22`.
`--user`	SSH user. Default `root`.
`--ssh-key`	A private key to use. Optional; see below.
`--ssh-password`	The host password, for unattended runs.
`--master-public-ip`	The address the world should use, when it differs from `--host`.
`--skip-precheck`	Do not ask the machine about itself first.
`--best-effort`	Ask, warn, and carry on anyway.

If you leave out --ssh-key, Flui reuses a key that already works on that host. If none does, it authorises one: it asks for the host password once, uses it only in memory, and never stores it. A key with a passphrase works only when it is already loaded in your ssh-agent, so run ssh-add first.

For an unattended install, --ssh-password accepts the password, but prefer the FLUI_SSH_PASSWORD environment variable so it stays out of your shell history.

The precheck, and ARM

Before installing anything, Flui asks the machine to describe itself: operating system, architecture, memory, cores, and whether a cluster is already installed on it. It stops on an architecture it does not support, on less than about 2 GB of memory, and on a machine that already carries an install. --best-effort turns those into warnings; --skip-precheck skips the question.

A 64-bit ARM machine works. The check accepts 64-bit Intel/AMD and 64-bit ARM alike, so a small, cheap, quiet ARM machine is a supported target.

The firewall on your own machine

There is no provider firewall to create here, so Flui applies one on the host itself: everything denied by default, with SSH, HTTP and HTTPS open. The installation is not reported ready until that firewall is in place, because an install that leaves the cluster reachable from anywhere has not succeeded.

You can inspect and re-apply it later:

flui env firewall status
flui env firewall apply

What the run hands back

flui env status         # state and nodes
flui env credentials    # the endpoints, and the first login

flui env credentials prints the public addresses of the dashboard, the API and the identity provider, together with the bootstrap admin email and its one-time password. Change that password the first time you log in. Other secrets are hidden unless you ask for them with --show-secrets.

If a run failed, flui env logs reads the log the CLI wrote while driving the operation, and flui env inspect opens the machine’s own system log over SSH.

When a run dies half-way

Provisioning creates real, billable resources before it finishes: a server, a firewall, an SSH key. If the run dies while holding your provider token, it cannot clean up after itself. You are left with a few resources in your account that nothing points at.

flui env scrub removes them. It works from the JSON resource list the failed run reported:

flui env scrub --ledger ./flui-run.json
cat flui-run.json | flui env scrub --stdin
flui env scrub --ledger ./flui-run.json --delete

Without --delete it changes nothing. It asks the provider what exists, matches that against the list, and prints what it would remove.

Two rules limit what it deletes. The list decides what to look for and the provider decides what is really there; anything that is not in both is left alone. And if part of the account could not be listed, it refuses to delete anything, because a part it cannot see is not necessarily empty.

A different leftover, from a flui env destroy that failed rather than a create, is handled by flui env orphan-volumes.

Reinstalling in place

Sometimes the server is fine and the installation on top of it is not. flui env reinstall wipes Flui and everything inside the cluster off the existing server and runs the installation again from the start.

flui env reinstall
flui env reinstall --dry-run    # print the teardown, run nothing
flui env reinstall --force      # skip the typed confirmation

The server itself, its firewall, its network attachment and its attached shared storage volume all stay. Everything in the cluster (your applications, the database, the dashboard’s state) is lost. It is the same data loss as flui env destroy, without losing the machine.

It asks you to type the cluster’s name back before it starts. Two limits apply: it works only on clusters Flui provisioned on a provider, and only on single-node ones. On your own machine, the equivalent is flui env destroy --purge-host followed by flui env create --host again.

Taking over an installation somebody else set up

Someone can provision an installation for you and keep no access to it. With --ssh-mode ephemeral-key, the key that built the machine is destroyed at the end of the run, and no certificate authority was ever created. The servers are running and sealed.

Adoption is how the owner opens them, on their own terms.

On the installation, ask for a token:

flui env adoption-token
flui env adoption-token --format json

The token is single use, valid for one hour, and tied to that one installation. Anyone holding it can register a certificate authority there, so treat it like a password and hand it over the way you would hand over a password.

On the owner’s machine:

flui env adopt flui_adopt_eyJlbmRwb2ludCI...
flui env adopt <token> --endpoint https://your-install.example.com
flui env adopt <token> --skip-ca

Adopting does four things: it asks the installation to describe itself, writes a local profile pointing at it, creates the SSH certificate authority on this machine, and has the installation enrol the public half on every node.

Because of the third step, the key that opens those servers is created on the owner’s machine, at a moment the owner chose. Nobody who built the installation ever holds it.

--endpoint is only needed when the token does not carry one. --skip-ca rebuilds the local profile and leaves SSH dormant, which is the right choice if you only use the dashboard.

Where to go next

Creating a cluster from zero: the reasoning behind the choices above (addressing, certificates, storage, firewall).
Environments: the full env command surface, including power state, scaling and the diagnostic commands.
Getting started: installing the CLI, logging in, and connecting GitHub.