Flow CLI & SDK
Run GPU workloads on Mithril from the shell or from Python.
Flow procures GPUs through Mithril, spins up InfiniBand-connected instances, and runs your
workloads. It is one engine with two projections: the CLI is what you meet first, and
import flow is the same engine for programs. Every CLI verb runs on the SDK.
First hour
The same three commands flow --help teaches:
uv tool install flow-compute # or: pipx install flow-compute
flow setup # Mithril account, API key and project
flow tutorial # Guided first GPU run with health checks
flow run 'nvidia-smi' # Run a command on a GPU
flow run without -i bids on the cheapest NVIDIA GPU instance type with live capacity,
prints the choice with its family and hourly price, and asks before any bid above $20/hour.
The implicit default never picks a TPU or an accelerator family Flow does not know, since
the first command is nvidia-smi; name other hardware with -i (-i v6e-1, -i cpu).
flow tutorial prices its GPU test the same way and asks before launching it; --yes is
the only scripted consent and --skip-example leaves the test out. Add --dry-run to see
the configuration without bidding:
$ flow run 'nvidia-smi' --dry-run
╭─ Task Configuration ─────────────────────────────────────────────╮
│ Name run-0972ae │
│ Command nvidia-smi │
│ Instance Type a100 │
│ Market Price $8.00/hr (a100, cheapest live NVIDIA GPU) │
│ Priority Med │
│ Max Bid $16.00/hr │
│ Code Upload auto (timeout 600s) → /workspace (host+container) │
╰──────────────────────────────────────────────────────────────────╯
✓ Configuration is valid
Then watch, inspect and stop what you started:
flow status # List and monitor tasks
flow logs <task> -f # Stream task logs
flow ssh <task> # SSH into a running task
flow cancel <task> # Cancel a task
$ flow status
╭─ ❊ Flow • 9 completed ────────────────────────────────────────────╮
│ │
│ # Status Task Type │
│ 1 ✓ completed cli-welcome 1×A100 │
│ 2 ✓ completed post-training-sanity-1 1×A100·40G │
│ 3 ✓ completed pretraining-pending-a100-40g 1×A100·40G │
│ 4 ✓ completed post-training-fine-tune 8×H100 │
│ 5 ✓ completed inference-serving 1×H100 │
│ 6 ✓ completed pretraining-train-8xa100 8×A100 │
│ 7 ✓ completed post-training-sanity-2 1×A100·40G │
│ 8 ✓ completed reasoning-rollout-b200 8×B200 │
│ 9 ✓ completed pretraining-2048-h100 256×8×H100 │
│ │
╰───────────────────────────────────────────────────────────────────╯
The same first hour from Python:
import flow
task = flow.run("nvidia-smi", instance_type="a100")
for line in task.log_stream():
print(line, end="")
Optional assistant integrations:
flow claude # Install Flow skills for Claude Code
flow codex # Install Flow skills for Codex
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.
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 a GPU workstation or flow run to 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)
Workflows
Research mode
flow run→ reproducible batch jobs from a command, a YAML file or a SLURM script.flow dev→ interactive development on an allocated GPU workstation.import flow→ the same engine for pipelines and orchestration.
# Launch a batch job on discounted H100s
flow run 'python train.py' -i 8xh100
# Run a saved configuration
flow run task.yaml
# Frictionlessly leverage an existing SLURM script
flow run job.slurm
# Serverless-style decorator
@app.function(instance_type="a100")
def train(lr: float) -> dict:
...
Infrastructure mode
flow instance create -i 8xh100 -N 20→ request a 20-node GPU clusterflow volume create -s 10000 --interface file→ provision 10 TB of persistent, high-speed storageflow ssh instance -- nvidia-smi→ run across all nodes in parallel
$ flow instance create -i 8xh100 -N 20 --dry-run
╭─ Instance Configuration ────────────────────────────────╮
│ Name interactive-47fa95 │
│ Instances 20 × 8xh100 │
│ Max Bid $64.00/hr per instance ($1280.00/hr total) │
│ Code Upload disabled │
╰─────────────────────────────────────────────────────────╯
✓ Configuration is valid
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 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
uvto 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
Providers
Flow talks to one provider per configuration. Mithril is the default and the only provider
installed by the base package; flow setup --provider (or FLOW_PROVIDER) selects the active
one. The SkyPilot provider is an optional extra, pip install 'flow-compute[skypilot]', and
is not installed by default. Switching providers means switching configurations; a single
config does not span providers.
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
#SBATCHscripts directly.
Python SDK
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",
instance_type="a100",
data_mounts={
"/datasets": "s3://ml-bucket/imagenet", # S3 via s3fs
"/models": "volume://pretrained-models" # Persistent storage
}
)
The vocabulary is the same on every surface (instance_type, env, data_mounts, ...);
see docs/vocabulary.md.
Key Features Summary
- Distributed Training – Multi-node InfiniBand clusters auto-configured
- Code Upload – Automatic with
.flowignore(or.gitignorefallback) - Live Debugging – SSH into running instances (
flow ssh) - Cost Protection – Built-in
max_price_per_hoursafeguards - Jupyter Integration – Connect notebooks to GPU instances
Documentation: https://docs.mithril.ai/cli-and-sdk/quickstart
Further Reading
1 maintainer
Metadata
1 maintainer
Release files for flow-compute 3.27.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| flow_compute-3.27.0.tar.gz | 2.0 MB | Details |
Built distributions (wheels)
Total release size: 89.8 MB
Release files / flow_compute-3.27.0.tar.gz
| Download URL | flow_compute-3.27.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9932c1953bb564a503b40659f73a064b290c3479fe4ad019fc547ce83791a9c2
|
|
BLAKE2b-256 checksum How to use checksums |
a48f3a280ceb0dc9b916b8907cb55c6db4919c1710355f7da0a696149291aec8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-py3-none-any.whl
| Download URL | flow_compute-3.27.0-py3-none-any.whl |
|---|---|
| Size | 2.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6595274d93a49b6aa3050befa7e7adb88aa53bf7ac5dec980f85776a1f6050a7
|
|
BLAKE2b-256 checksum How to use checksums |
d1cd5008c8a0ef573e8f7eb1b6c0c9babdaf00efd5f00c46eb341b724e94379c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp313-cp313-manylinux_2_28_x86_64.whl
| Download URL | flow_compute-3.27.0-cp313-cp313-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
ec7210a50cb3cfd8b6d28d6bbb6c8e136640a8797a3722af7dab1a88a60ffae7
|
|
BLAKE2b-256 checksum How to use checksums |
ecbca08dfc41fafbd91bdbe9b41a142795e330283ec2fbb86aaa0c63c783e652
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp313-cp313-manylinux_2_28_aarch64.whl
| Download URL | flow_compute-3.27.0-cp313-cp313-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
78d42efcaea527e4f5caf5db7d9940f2e66e14bf14b3539b1e85d7faf5cf564a
|
|
BLAKE2b-256 checksum How to use checksums |
f3927eb68c84df1ab666a46f840d4616c228b7af22c4f54cb7979692b5649da1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | flow_compute-3.27.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
cf617e4c4961986f859b8966b620f6c5d85c843ad34a30e48871d9da7f8253f8
|
|
BLAKE2b-256 checksum How to use checksums |
7e14d47229e66261f7b95d0694cd59ca40d9519fed95f82dbde9dde007821712
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp313-cp313-macosx_10_12_x86_64.whl
| Download URL | flow_compute-3.27.0-cp313-cp313-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.13 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
624097525971118b2a6138a8a8c85ad62e9682e3ef7af70a4712c55e0e8a1c26
|
|
BLAKE2b-256 checksum How to use checksums |
75bc4593628e9f1f0f323cd839002c4c3448442950e77e37235259efc10ade50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp312-cp312-manylinux_2_28_x86_64.whl
| Download URL | flow_compute-3.27.0-cp312-cp312-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
fe49460df22476e76dbbfed5329fd0955a95962a5cc94aadc055532d2a2ea996
|
|
BLAKE2b-256 checksum How to use checksums |
37d498b66a86251c3ac61c72c0c723a1327c7d00865c6648991a03c4f092e7ce
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp312-cp312-manylinux_2_28_aarch64.whl
| Download URL | flow_compute-3.27.0-cp312-cp312-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.12 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
b23be7432158b036b8db43e1b1f10e9871d1c9df9069f65882da9895e4fc047a
|
|
BLAKE2b-256 checksum How to use checksums |
b1840bd3c5e4cb3ef9c3a3962839220eb0f4b480f0942cacc460eb65263f30c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | flow_compute-3.27.0-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
5030922896fe89f8e019f09c31f93b81bdc1bad9190b136ebe50959dd1b76763
|
|
BLAKE2b-256 checksum How to use checksums |
f77f3c1a10740948722c517e325ca1290af45b68bc3103a79bea0df4bc20b5db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp312-cp312-macosx_10_12_x86_64.whl
| Download URL | flow_compute-3.27.0-cp312-cp312-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.12 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4c7d0d3515badbdf2caf3f67b556561710c7765d11caaa9e5e0c71f0d108d309
|
|
BLAKE2b-256 checksum How to use checksums |
ea046ae1c3f1ebac2089e185b8c1d14cc4f3101e13e3d187830f2667d550cabd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp311-cp311-manylinux_2_28_x86_64.whl
| Download URL | flow_compute-3.27.0-cp311-cp311-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
93fad665ab2419b2e43fd5d078b244962feeb70b0a93bb42d013685510a5246d
|
|
BLAKE2b-256 checksum How to use checksums |
8e06c75924f2050f19e4111bccd4262901420530cc604456462bda707c679b24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp311-cp311-manylinux_2_28_aarch64.whl
| Download URL | flow_compute-3.27.0-cp311-cp311-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
9ba7da4e1aa0c4d11ab6ebb7aaaa4091deb557f64b021aa5809ca329856b65f2
|
|
BLAKE2b-256 checksum How to use checksums |
8896b2fdac7c2e25227914a102a3440ebcd7381eb18c69e016aeed19604b8a79
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | flow_compute-3.27.0-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b50aa92eee7d8104ccae0700a3cd7d9786a8828b457e4ff9e548237481599ff3
|
|
BLAKE2b-256 checksum How to use checksums |
2121adec85df25fae8f0da95dd75c312c8d7c753d100f0f53cef158143f38ff2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp311-cp311-macosx_10_12_x86_64.whl
| Download URL | flow_compute-3.27.0-cp311-cp311-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.11 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
1b539c779a54f93870e80274c910a92a98d09056587ee894c6af168d4653a66c
|
|
BLAKE2b-256 checksum How to use checksums |
e422d7be101d1c2c6ee155fef669ad34c26a8598bce65742cbe042a69745b37e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp310-cp310-manylinux_2_28_x86_64.whl
| Download URL | flow_compute-3.27.0-cp310-cp310-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ x86-64 |
|
SHA-256 checksum How to use checksums |
143ac5ea91e4e3f3dda9905e1aae0cc182ad39bd324fdbcbb6964dd110063fd1
|
|
BLAKE2b-256 checksum How to use checksums |
d21e3b2cf482f005614e049358eb3a0adcbdd54082a35de70eaa11f1dde1a4cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp310-cp310-manylinux_2_28_aarch64.whl
| Download URL | flow_compute-3.27.0-cp310-cp310-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 Linux glibc 2.28+ ARM64 |
|
SHA-256 checksum How to use checksums |
62baf3ecb8fa9a4e7347b78189861a8b802bf0a2bbf427cbc8936d96f88b7a63
|
|
BLAKE2b-256 checksum How to use checksums |
d3797b0c245d1ddaa9c289b1bf4d588b784ae5199820aeb3ef7cb85b0663ec2b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | flow_compute-3.27.0-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f71f1233cddf44660570e157a0baf7adaa33111f7ea7bfbe0fc995807d3b9cca
|
|
BLAKE2b-256 checksum How to use checksums |
72cdfce5368b022060ca81a848bbc4716b16203a2ad69f366ead51efee89db5b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / flow_compute-3.27.0-cp310-cp310-macosx_10_12_x86_64.whl
| Download URL | flow_compute-3.27.0-cp310-cp310-macosx_10_12_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
f507499d161176ca42a8e076eacf17555815982df7bfe84d7c2e3d7534c036ad
|
|
BLAKE2b-256 checksum How to use checksums |
041a85d12f3ebd0bcc0ccdcf7c8b0d3fc95f5a33ca461cf49fa8c6e495b05583
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
