The fluksio command¶

pip install fluksio

Installs the engine and the fluksio command. Python 3.10 or newer, Linux or macOS.

There is a second, smaller distribution — fluksio-worker — for a machine that should only run nodes for an engine elsewhere. It has none of the engine in it. See Remote workers.

fluksio serve¶

Runs the engine.

fluksio serve

On the first start it creates an admin account and prints its password once. Nothing else has to be running: no database server, no message broker, no Docker.

--enroll with --portal is the one-command setup: it pairs before the engine starts, so the connection is dialled as part of coming up rather than needing a restart. It is skipped if the installation is already enrolled.

What it prints¶

Created the admin account admin@example.com
  password: k3Qm-8vTpLdX
  Shown once. Change it from the dashboard.
Fluksio 0.1.0 — data in /home/you/.fluksio
  API      http://127.0.0.1:8000/api/v1
  No portal. Pair this installation with:
    fluksio enroll <code> --portal https://hub.example.com

An enrolled installation says which portal it is on instead, and notes that the dashboard is served from there rather than here.

fluksio enroll¶

Pairs an existing installation with a portal.

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

Get the code from the portal under Installations → Add installation. It is single-use and expires in fifteen minutes. --as matters when the installation has several superusers — without it, enrolment refuses rather than guessing.

Afterwards, fluksio serve dials the portal as it comes up. See Accounts and the portal.

fluksio worker¶

Runs nodes for an engine elsewhere. Everything after worker belongs to the agent's own parser — it is the same program fluksio-worker installs, so the two are interchangeable:

fluksio worker --url wss://api.example.com/api/v1/workers/attach \
               --token "$FLUKSIO_WORKER_TOKEN" --labels gpu

See Remote workers.

What lives in the data directory¶

~/.fluksio/
├── fluksio.db          SQLite: users, runs, metrics, observability, agents
├── flows/              a git repository — one directory per flow
│   ├── house/
│   │   ├── flow.json           the published structure
│   │   ├── nodes/*.py          the published node code
│   │   ├── flow.draft.json     unpublished edits, if any
│   │   └── nodes.draft/*.py
│   ├── _lib/           shared node sources
│   ├── _dashboards/    dashboards, drafts and all
│   └── requirements.txt        what the Modules screen installs
├── artifacts/          content-addressed bytes, two levels deep
├── user-venv/          the interpreter your node code runs on
├── secrets.enc         encrypted credentials, deliberately outside flows/
├── alerts.json         alert channels and rules
├── panels.json         wall-panel pairings
├── oauth-key.pem       signs agent tokens
├── cloud.json          the portal enrolment, if there is one
├── secret_key          signs sessions and derives the secrets key
└── env                 optional settings file

Two things follow from this layout and are worth internalising:

flows/ is a real git repository. git log is the history of every change anyone made to any flow. A run records the commit it ran at, so git show on that hash is literally the code that produced the number.

Backing up the data directory backs up the installation. Everything else is rebuildable. Copy it while the engine is stopped, or use SQLite's online backup for the database if it is not.

Settings¶

Settings come from the environment, or from an env file in the data directory. The ones you are most likely to touch:

The full list is in Configuration.