serve: refuse a second engine for one data directory whatever port it was
asked for, using the pidfile and a token this directory signed. The check
runs before the database is touched and before the credential is written,
which is what left every later CLI call pointing at a dead port.

The terminal dashboard is three tabs (Overview, Runs, Logs) with the toolbar
following the focused pane, the engine's output goes to serve.log rather than
down a pipe, and closing the screen stops both reader threads so the prompt
comes back. It adopts a running engine on every start, so stop/start and
restart work on one it did not start, and a stop waits for the process to be
gone before the next start. Enrolment reports itself in the modal.

enroll: a new claim code replaces the pairing instead of being refused. The
code is redeemed before anything is written, mappings to a portal being left
are cleared, and a running engine redials when the stored enrolment changes.

runs: an engine re-queues the runs left `queued` by the one before it, and
`fluksio retry <id>` / `retry --group <sweep>` submits an interrupted run
again with the same inputs and group, recorded through Run.parent_id.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U9BoNGq6V9MdRWAte7JBuC

2026-08-31 17:37:13 +02:00

5.0 KiB

Raw Blame History

Accounts and the portal

Fluksio is self-hosted by default. An instance runs offline, keeps its data on its own disk, and never contacts anything unless you tell it to.

The portal is optional, and it exists to solve two specific problems:

Your machine has no inbound route. A homelab behind CGNAT, a cluster node with no open ports, a laptop. Opening one is work, and often not allowed.
You want a browser on it anyway. A pip install fluksio instance has no web server for the dashboard at all.

An enrolled instance dials out to the portal and holds one websocket open. The portal serves the dashboard from its own side, and only the API calls travel down the tunnel, so the interface loads at portal speed and your machine stays unreachable from the internet.

Enrolling

Two halves: whoever performs the second step decides what the instance's owner gets.

On the portal (hub.${DOMAIN}, or fluksio.com for the hosted one): Instances → Add instance, give it a name, and copy the code.

On the instance, either from the dashboard:

Settings → Remote access, enter the portal URL and the code, press Connect.

or from the command line, which is the path for an instance with no web interface of its own:

fluksio enroll ABCD-1234 --portal https://hub.fluksio.com

The code is single-use and expires in fifteen minutes. A fresh code on an instance that is already paired replaces the pairing, so moving an instance to another portal is one command rather than a disconnect and a reconnect.

A portal session then arrives as that local account, which the settings screen states plainly. Use --as someone@example.com to enrol as a specific local account when the instance has several superusers.

Once enrolled, the instance appears under Instances with its status, when it was last seen and its version. Open takes you to its dashboard at ${DOMAIN}/i/{instance-id}.

What the portal can and cannot do

The portal holds one credential for your instance and proxies requests down the tunnel. What those requests may do is decided on the instance, by the same checks a local session passes.

The trust anchor is a signing keypair on the portal. Every instance pins its public half at enrolment and rejects anything else, which is what stops a hijacked DNS entry or a mis-issued certificate from impersonating the portal.

Letting someone else in

Anyone else on the portal reaches your instance only if a superuser there admits them, and they arrive as a local user of their own rather than as you.

They: Instances → Join an instance, and copy the code. It is bound to their portal account and expires in fifteen minutes.
You, on the instance: Settings → Remote access → Add remote user, and enter the code.
They now see the instance under Instances, marked Shared by, with Open and nothing else. Renaming, re-keying and removing stay with you.

The instance redeems that code against the portal using its own credential. A portal session cannot do this, which is what stops somebody you let in from letting others in.

On the instance they appear under Admin → Users, badged Portal, never a superuser and with no password.

Cutting it off

From	Action	Effect
The portal	New code	rotates the credential and drops the current link
The portal	Remove	deletes the registration and cuts the connection
The instance	Disconnect	unilateral and immediate — the portal's tokens stop verifying here whatever the portal still has on file
The instance	delete a user under Admin → Users	that one person, immediately, independent of the portal

New code also cuts every credential the portal minted for this instance, including wall panels paired through it.

The instance's own Disconnect is the one to reach for if you are ever unsure: it does not need the portal's cooperation.

Running your own portal

The portal is the index stack's hub service: accounts, the registry of connected instances, and the websocket each one dials in on. Two things about it are load-bearing:

It runs a single process. It keeps its attached instances in the memory of the process holding their sockets, so a second worker would answer for links it does not hold. Scaling out needs a routing layer first.
Back up the signing keypair with the database. Replacing it forces every instance to be enrolled again.

Websocket upgrades must be enabled on the hub hostname in whatever proxy fronts it. Without them every instance sits in a reconnect loop and the portal shows them all offline.

5.0 KiB Raw Blame History