The fluksio command¶

Install on Linux or macOS with Python 3.12 or newer:

pip install fluksio
fluksio serve

For the browser dashboard, sign up at fluksio.com, add an instance, then run fluksio enroll <code> in the same directory.

Use fluksio --help or fluksio COMMAND --help for command options. pip install 'fluksio[server]' adds MQTT, InfluxDB, outbound mail, error reporting and numpy, or name only what you need, such as fluksio[mqtt]. A machine that only executes remote nodes can install fluksio-worker.

Where an instance lives¶

By default, Fluksio finds the nearest .fluksio/ directory by walking up from your working directory. serve creates one in the current directory if needed. Separate project directories can therefore hold separate instances.

--global selects ~/.fluksio. --data-dir PATH or FLUKSIO_HOME selects a directory explicitly. The data directory contains a .gitignore that excludes its database, credentials and other contents from your project.

fluksio serve¶

Starts the API and flow engine. No external database, broker or Docker is needed for the default setup.

fluksio serve
fluksio serve --plain --port 9000

The first start prints an admin password once. Local CLI commands receive a saved token automatically; login is for connecting to another engine.

The default port is 8000, advancing to the next free port if necessary. An explicit --port fails when occupied. The startup banner and saved client configuration show the selected URL.

Run one engine per instance. At a terminal, a second serve reattaches to that instance's running engine; plain mode refuses to start a duplicate.

Resource defaults can also come from the corresponding FLOW_* settings; see Configuration. GPU detection counts the entries of CUDA_VISIBLE_DEVICES when it is set, otherwise NVIDIA device nodes. Set --gpus when your hardware is not detected.

Use local disk for the data directory on a cluster: SQLite's write-ahead log does not support NFS.

The dashboard¶

At a terminal, serve opens Overview, Runs and Logs:

On Runs, space selects runs, enter opens a chart or comparison, c cancels a run, and a lists or downloads artifacts. Compare curves by step, elapsed time or another metric.

Run fluksio serve again to reopen the dashboard. Its engine writes to serve.log in the data directory; the log is truncated after 5 MB. Without a terminal, or with --plain, the command prints logs directly.

fluksio enroll¶

Connects this instance to the portal:

fluksio enroll ABCD-1234

Get a code from Instances → Add instance in the portal. Run the command from the instance's project directory, or select it explicitly.

With multiple local superusers, --as is required. A new code replaces an existing enrollment only after the portal accepts it. A running engine picks up the change and reconnects automatically.

The instance keeps an outbound connection to the portal and reconnects after network interruptions. See Accounts and the portal.

fluksio worker¶

Starts the same agent as the standalone fluksio-worker command:

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

Create the worker token on the engine first. See Remote workers for token creation, interpreter selection and labels.

Talking to an engine¶

Client commands use the nearest .fluksio/client.json, or the global configuration when there is no project instance. Legacy client configuration is a fallback. FLUKSIO_URL and FLUKSIO_TOKEN override saved values; command options --url and --token override both.

fluksio login¶

fluksio login --url https://fluksio.example.com

Prompts for credentials and saves an API token for a remote engine. --global saves it in ~/.fluksio instead of this project. Your locally started engine already saves a token.

fluksio sync¶

fluksio sync study
fluksio sync examples/myresearch
fluksio sync --dry-run study

Imports modules, packages or directories and uploads the declared flows. With no target, it searches the current directory. Directory searches skip hidden folders, virtual environments, __pycache__ and node_modules. File paths are not targets: use study, not study.py.

The generated node bodies import your functions. Keep the project available to each machine running them; sync does not copy your package to a remote worker. Uploading source requires a superuser token.

The flow records the git repository it was declared in, or the directory when there is none, and each run hashes the Python files below it. The engine refuses /, its home directory and relative paths there, so run sync from inside the project's repository.

Sync records source digests for stage caching and refreshes local workers, so edited imports are picked up. An unchanged flow reports unchanged. See the data science guide for a complete example.

fluksio run¶

fluksio run train --lr 0.05 --epochs 20 --follow

Syncs local code, then submits a run. Flags such as --lr name the flow's declared inputs and are converted to their declared types. Unknown inputs are rejected. Use --param name=a,b with sweep for multiple values.

Everything after -- is an input written as name=value. Use it for an input that shares its name with a flag of run, such as timeout:

fluksio run train --wait --timeout 600 -- timeout=30 lr=0.05

After the first sync, run imports the module that declared the flow. If no declaration is recorded, it searches the working directory and skips paths covered by .gitignore. Import errors in that fallback search produce warnings. Use --sync PATH to choose a target explicitly.

With no parameters at a terminal, the command prompts for each input. Press Enter to keep its default. Scripted commands do not prompt. Ctrl-C while waiting cancels the run and exits with status 130.

A seed does not initialize your libraries' random number generators. Declare a seed input and pass it to your code if it controls randomness.

Inputs can reference earlier results:

fluksio run evaluate --dataset @run:<run-id>.dataset
fluksio run evaluate --dataset sha256:<digest>

@run:<id>.<output> resolves a run output; sha256:<digest> resolves stored bytes into an artifact reference.

--local uses the same data directory, history and artifacts as serve. It starts and stops the engine for each command, so keep serve running when iterating frequently.

fluksio status¶

fluksio status
fluksio status --watch

Shows engine health, portal connectivity, flows, recent runs and available resources. --watch refreshes every five seconds. --local reads the local instance without a served engine.

fluksio runs¶

fluksio runs --flow train --limit 10

Lists recent runs, newest first. Omit --flow for all flows. --local reads the local instance.

fluksio retry¶

fluksio retry <run-id>
fluksio retry --group <sweep-id>

Submits a new run with the previous inputs, seed and group, linked to its parent. --group retries finished runs in that group that did not end ok. Active runs must be cancelled before retrying.

Queued runs survive engine restarts. Interrupted running runs become abandoned after their lease expires; retry them to resume with any available cached stages.

fluksio flavors¶

fluksio flavors

Lists named resource sizes, usable as @node(resources="gpu-small"). Edit them in Workers or through the flavors API.

fluksio sweep¶

fluksio sweep train --param lr=0.01,0.1 --param epochs=10,50 --wait

Submits every combination of the declared input values: four runs here, sharing a group_id. Runs execute concurrently within the engine's limits. To vary seeds, the flow must declare a seed input; use --param seed=1,2,3.

--seed, --sync, --no-sync, --no-cache, --timeout and --local work as for run. --wait exits non-zero if any run fails.

fluksio export¶

fluksio export metrics --flow train --list
fluksio export metrics --flow train --name train.loss -o curves.csv
fluksio export runs --flow train --status ok -o results.csv

metrics exports a row per run, metric and step. --list lists metric names; --name A,B selects them; --stride N keeps every Nth point.

runs exports a row per run with inputs, final numeric results, status, duration and code identifiers. Use --params A,B and --metrics A,B to select columns, including dotted paths such as final_metrics.train_loss.

Both support --flow, repeated --run ID, --group, --status, --since, --until and --local. The run ID joins results to metrics. An export stops at the newest 10 000 runs, and when a selection matches more, the CLI and the Python client warn how many were left out.

Output defaults to CSV on stdout. -o FILE writes a file; --format jsonl writes JSON Lines. Parquet requires pip install 'fluksio[parquet]' and --format parquet -o FILE.

In Python, Client.export_metrics() and Client.export_runs() return the same rows as lists of dictionaries.

fluksio artifacts¶

fluksio artifacts <run-id>
fluksio artifacts <run-id> train.weights -o weights.json

Lists a run's returned artifacts, including their message names, sizes and filenames. Pass a name from that list to download it. Output uses the stored filename unless -o selects another path. --local reads the local instance.

What lives in the data directory¶

The main files and directories are:

The flow repository records edits in Git. Runs record its commit and code digests; code-defined nodes also depend on your project files, so keep that project's history too.

Back up the data directory while the engine is stopped. An adopted venv and your project files live outside it and need their own backup.

Settings¶

Settings come from environment variables or an env file in the data directory. Common choices:

See Configuration for defaults and the full list.