flow-compute 3.22.1

CLI and SDK for submitting and managing GPU workloads

Flow CLI & SDK

Python → Petaflops with one CLI. Flow procures GPUs through Mithril, spins up InfiniBand-connected instances, and runs your workloads with a compact CLI and SDK.

Public repo

Background

There's a paradox in GPU infrastructure today: Massive GPU capacity sits idle, even as AI teams wait in queues—starved for compute. Mithril, the AI-compute omnicloud, dynamically allocates GPU resources from a global pool (spanning Mithril's first-party resources and 3rd-party partner cloud capacity) using efficient two-sided auctions, maximizing surplus and reducing costs. Mithril seamlessly supports both reserved-in-advance and just-in-time workloads—maximizing utilization, ensuring availability, and significantly reducing costs.

Infrastructure mode

flow instance create -i 8xh100 -N 20
╭─ Instance Configuration ────────────────────────────────╮
│                                                         │
│  Name           multinode-run                           │
│  Command        sleep infinity                          │
│  Image          nvidia/cuda:12.1.0-runtime-ubuntu22.04  │
│  Working Dir    /workspace                              │
│  Instance Type  8xh100                                  │
│  Num Instances  20                                      │
│  Max price      $12.29/hr                               │
│                                                         │
╰─────────────────────────────────────────────────────────╯

flow instance list
╭─────────────────────────────── ❊ Flow ────────────────────────────────╮
│                                                                       │
│     #     Status     Instance               GPU       Owner     Age   │
│     1   ● running    multinode-run        8×H100·80G  alex       0m   │
│     2   ● running    interactive-77c31e   A100·80G    noam       5h   │
│     3   ○ cancelled  dev-a100-test        A100·80G    alex       1d   │
│                                                                       │
╰───────────────────────────────────────────────────────────────────────╯

Research mode (in early preview)

flow submit "python train.py" # -i 8xh100
⠋ Bidding for best‑price GPU node (8×H100) with $12.29/h100-hr limit_price…
✓ Launching on NVIDIA H100-80GB for $1/h100-hr

---

Quick Start

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

# Install via uv or pipx (or see installer scripts in scripts/)
uv tool install flow-compute
# or: pipx install flow-compute

flow setup  # Requires a Mithril account, API key, and project access
flow dev   # Interactive GPU development after initial VM setup

Optional assistant integrations:

flow claude  # Install Flow skills for Claude Code
flow codex   # Install Flow skills for Codex

---

Why choose Flow

Status quo GPU provisioning involves quotas, complex setups, and queue delays, even as GPUs sit idle elsewhere or in recovery processes. Flow addresses this:

Dynamic Market Allocation – Efficient two-sided auctions ensure you pay the lowest market-driven prices rather than inflated rates.

Simplified Batch Execution – An intuitive interface designed for cost-effective, high-performance batch workloads without complex infrastructure management.

Provision from 1 to thousands of GPUs for long-term reservations, short-term "micro-reservations" (minutes to weeks), or spot/on-demand needs—all interconnected via InfiniBand. High-performance persistent storage and built-in Docker support further streamline workloads, ensuring rapid data access and reproducibility.

---

Why Flow + Mithril?

Pillar	Outcome	How
Iteration Velocity and Ease	Fresh containers quickly once capacity is allocated.	flow dev for DevBox or flow submit to programmatically launch tasks
Best price-performance via market-based pricing	Preemptible secure jobs for $1/h100-hr	Blind two-sided second-price auction; client-side bid capping
Availability and Elasticity	Self-serve access to spot and reserved capacity, subject to account access and market availability.	Spot capacity plus overflow capacity from partner clouds
Abstraction and Simplification	InfiniBand VMs, CUDA drivers, auto-managed healing buffer—all pre-arranged.	Mithril virtualization and base images preconfigured + Mithril capacity management.

"The tremendous demand for AI compute and the large fraction of idle time makes sharing a perfect solution, and Mithril's innovative market is the right approach." — Paul Milgrom, Nobel Laureate (Auction Theory and Mechanism Design)

---

Key Concepts to Get Started

Core Workflows

Infrastructure mode

• flow instance create -i 8xh100 -N 20 → request a 20-node GPU cluster
• flow volume create -s 10000 -i file → provision 10 TB of persistent, high-speed storage
• flow ssh instance -- nvidia-smi → run across all nodes in parallel

In research preview

Research mode

• flow dev → interactive development on allocated GPU instances.
• flow submit → reproducible batch jobs.
• Python API → easy pipelines and orchestration.

Examples

# Launch a batch job on discounted H100s
flow submit "python train.py" -i 8xh100

# Frictionlessly leverage an existing SLURM script
flow submit job.slurm

# Serverless‑style decorator
@app.function(gpu="a100")

---

Ideal Use Cases

• Rapid Experimentation – Quick iterations for research sprints.
• Instant Elasticity – Scale rapidly from one to thousands of GPUs.
• Collaborative Research – Shared dev environments with per-task cost controls.

Flow is not yet ideal for: always‑on ≤100 ms inference, strictly on‑prem regulated data, or models that fit on laptop or consumer-grade GPUs.

---

Architecture (30‑s view)

Your intent ⟶ Flow Execution Layer ⟶ Global GPU Fabric

Flow SDK abstracts complex GPU auctions, InfiniBand clusters, and multi-cloud management into a single seamless and unified developer interface.

---

Installation

Requirements

• Python 3.10 or later
• Recommended: use uv to auto-manage a compatible Python when installing the CLI
• Linux or macOS for native CLI workflows. On Windows, use WSL2; native Windows is not fully validated.

1) Install uv — optional but recommended

Installation guide: docs.astral.sh/uv/getting-started/installation

• macOS/Linux:

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

• Windows: use WSL2 for the Flow CLI, then run the macOS/Linux command inside WSL.

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

2) Install Flow

• Global CLI (uv):

  uv tool install flow-compute
  flow setup
  

• Global CLI (pipx):

  pipx install flow-compute
  flow setup
  

---

Under the Hood (Advanced)

• Bid Caps – Protect budgets automatically.
• Self-Healing – Spot nodes dynamically migrate tasks.
• Docker/Conda – Pre-built images or dynamic install.
• Multi-cloud Ready – Mithril (with Oracle, Nebius integrations internal to Mithril), and more coming
• SLURM Compatible – Run #SBATCH scripts directly.

---

Python SDK (Research Preview)

Advanced Task Configuration

# Distributed training example (32 GPUs, Mithril groups for InfiniBand connectivity by default)
task = flow.run(
    "torchrun --nproc_per_node=8 train.py",
    instance_type="8xa100",
    num_instances=4,  # Total of 32 GPUs (4 nodes × 8 GPUs each)
    env={"NCCL_DEBUG": "INFO"}
)

# Mount S3 data + persistent volumes
task = flow.run(
    "python analyze.py",
    gpu="a100",
    mounts={
        "/datasets": "s3://ml-bucket/imagenet",  # S3 via s3fs
        "/models": "volume://pretrained-models"   # Persistent storage
    }
)

Key Features Summary

• Distributed Training – Multi-node InfiniBand clusters auto-configured
• Code Upload – Automatic with .flowignore (or .gitignore fallback)
• Live Debugging – SSH into running instances (flow ssh)
• Cost Protection – Built-in max_price_per_hour safeguards
• Jupyter Integration – Connect notebooks to GPU instances

Documentation: https://docs.mithril.ai/cli-and-sdk/quickstart

Further Reading

• Restoring the Promise of Public Cloud for AI
• Introducing Mithril
• Spot Auction Mechanics