WorldFlux Docs - BYO-compute physical-AI evaluation evidence

Install

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

During beta, design partners install from a private checkout or private package index. Public PyPI installation will be documented after the public package release.

Sync the dev environment

uv sync --extra dev

From a checkout. For an installed package, skip to the next step.

Confirm the install

uv run worldflux --version
uv run worldflux doctor

doctor checks Python, uv, every registered runtime plugin, and the cloud session if you are logged in.

First local run

uv run worldflux init demo-box
uv run worldflux run --project demo-box
uv run worldflux verify --project demo-box
uv run worldflux report --project demo-box
uv run worldflux visualize --project demo-box

demo-box/outputs/ now holds a manifest, metrics, logs, run history, and any artifacts the recipe produced. report.md lands in demo-box/. Nothing left the machine.

The default recipe is cpu-smoke. Pick a different one with --recipe <id>. List options with worldflux recipes list (recipes that ship: cpu-smoke, vector-control-smoke, vision-smoke, linear-world-model, mlp-world-model, mujoco-smoke, mujoco-policy-eval, dreamer-style-light, libero-pro, libero-plus).

Sync to the cloud

The CLI never echoes the API key to your shell history when you use --token-env or the interactive prompt. Avoid --token <inline> outside one-off debugging.

printf "Paste WorldFlux API key: "
IFS= read -r -s WORLDFLUX_TOKEN
echo
export WORLDFLUX_TOKEN

uv run worldflux login \
  --api-url http://localhost:8000 \
  --token-env WORLDFLUX_TOKEN \
  --workspace <workspace-uuid> \
  --project <project-uuid>

unset WORLDFLUX_TOKEN
uv run worldflux sync --project demo-box --cloud-project-id <project-uuid>

The default --api-url is http://localhost:8000; point at a deployed cloud control plane in production. Create and list Cloud workspaces/projects in the dashboard, then use their UUIDs in the CLI. The dashboard now lists demo-box. Open it to inspect the synced run. Public share links are created from verified evidence-package artifacts, so package and verify evidence before sharing externally.

On machines with no OS keyring (some Linux containers), worldflux login fails until you pass --allow-plaintext. That writes the key to ~/.worldflux/credentials.toml. In CI, prefer --token-env and short-lived secrets over plaintext storage.

Compare two runs

uv run worldflux init linear-box --recipe linear-world-model
uv run worldflux run --project linear-box

uv run worldflux init mlp-box --recipe mlp-world-model
uv run worldflux run --project mlp-box

uv run worldflux compare linear-box mlp-box

comparison.md lands at the repo root with metric deltas, the chosen winner, and links to whichever artifacts (prediction_plot.svg, rollout.html, rollout.mp4) the recipes produced.

Curated adapters

uv run worldflux curated list
uv run worldflux curated inspect openpi
uv run worldflux use openpi
uv run worldflux env build openpi          # build the adapter's venv
uv run worldflux curated run openpi rollout

worldflux use clones the upstream adapter into ~/.worldflux/curated/<id>/. The first call to env build resolves the adapter’s pyproject and downloads dependencies or weights required by the upstream project. curated run reuses that environment.

Package an audit

If you already have evaluation output, package it without rerunning the model:

uv run worldflux claim create --template openpi-libero --output claim_pkg/
uv run worldflux audit import lerobot \
  --from /tmp/lerobot_run_001/eval_info.json \
  --output audit_input.json
uv run worldflux audit run lerobot \
  --from /tmp/lerobot_run_001/eval_info.json \
  --claim claim_pkg/claim.json \
  --protocol claim_pkg/protocol.json \
  --output evidence_pkg/
uv run worldflux evidence inspect evidence_pkg/

The package contains claim.json, protocol.json, evidence.json, provenance, and artifact metadata. Add worldflux audit sign and worldflux audit verify when reviewers need signed evidence. To create a public share that uploads sanitized evidence package bytes after Cloud login, verification, and explicit customer approval:

worldflux audit publish evidence_pkg/ \
  --share \
  --cloud-run-id <cloud-run-uuid> \
  --confirm-public-share-upload \
  --approval-file public_share_approval.json \
  --password-env WORLDFLUX_SHARE_ACCESS_CODE

To reuse an already uploaded package artifact, use:

worldflux audit publish evidence_pkg/ \
  --share \
  --evidence-package-artifact-id <artifact-uuid> \
  --approval-file public_share_approval.json \
  --password-env WORLDFLUX_SHARE_ACCESS_CODE

Where to go next

CLI reference

Every top-level command and sub-tree, with --json examples for CI.

Dashboard

Sidebar, runs, compare, public share, billing.

Concepts

BYO model, runtime plugins, eval bridges, anti-cherrypick eval packets.

FAQ

Edge cases, error messages, common slips.

Get started

Concepts

Reference

Quickstart

Install

First local run

Sync to the cloud

Compare two runs

Curated adapters

Package an audit

Where to go next

CLI reference

Dashboard

Concepts

FAQ

​Install

​First local run

​Sync to the cloud

​Compare two runs

​Curated adapters

​Package an audit

​Where to go next

CLI reference

Dashboard

Concepts

FAQ

Install

First local run

Sync to the cloud

Compare two runs

Curated adapters

Package an audit

Where to go next