Quickstart

Get from zero to GPU in 5 minutes with the CLI and Python SDK.

1. Setup (2 minutes)

Requirements

Python 3.10 or later
Recommended: use uv to auto-manage a compatible Python when installing the CLI

1) Install uv (once) — optional but recommended

macOS/Linux:

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

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

More options: see the uv installation guide: docs.astral.sh/uv/getting-started/installation

Note: Ensure the directory uv adds (often ~/.local/bin) is on your PATH.

2) Install Flow

Global CLI (uv):
```
uv tool install flow-compute
flow init
```
Global CLI (pipx):
```
pipx install flow-compute
flow init
```

One-liner (macOS/Linux) without uv/pipx:

curl -fsSL https://raw.githubusercontent.com/mithrilcompute/flow/main/scripts/install.sh | sh
flow init

Per‑project (uv-managed env):

uv init my-project
cd my-project
uv add flow-compute
uv sync
uv run flow init

Authenticate

flow init

Get your API key at app.mithril.ai/account/api-keys

Verify Installation

flow --version

2. First GPU Task

CLI: Quick GPU Check

# Create a GPU instance and run nvidia-smi
flow compute create --instance-type a100 --command "nvidia-smi"

# List all your instances
flow compute list

# Check details of a specific instance
flow compute get <instance-name>

SDK: Same Task Programmatically

import flow

# Run nvidia-smi on A100 GPU
task = flow.run("nvidia-smi", instance_type="a100")

# Check status
print(f"Task ID: {task.task_id}")
print(f"Status: {task.status}")

# Wait for completion and get logs
task.wait()
print(task.logs())

3. Development

Interactive Environment

# Launch persistent development environment
flow dev

# Use specific GPU type
flow dev --instance-type h100

# SSH into any running instance
flow ssh <task-id>

The flow dev command gives you a persistent GPU environment that stays running between sessions - perfect for iterative development.

Basic Management

# List all instances and tasks
flow compute list

# Get details about a specific instance
flow compute get <instance-name>

# Delete an instance
flow compute delete <instance-name>

# View logs from any task
flow logs <task-id>

4. Simple Training

CLI: Run Training Script

# Run a training script on single GPU
flow run --instance-type a100 --command "python train.py"

# With specific requirements
flow run --instance-type a100 \
         --max-price 5.00 \
         --command "pip install torch && python train.py"

# Monitor the job
flow status
flow logs <task-id> --follow

SDK: Programmatic Training

import flow
from flow import TaskConfig

# Simple training task
task = flow.run("python train.py", instance_type="a100")

# More detailed configuration
config = TaskConfig(
    name="mnist-training",
    command="python train.py",
    instance_type="a100",
    max_run_time_hours=2,
    max_price_per_hour=5.00
)

task = flow.run(config)
print(f"Training started: {task.task_id}")

# Wait for completion
task.wait()
print(f"Final status: {task.status}")
print(f"Total cost: {task.total_cost}")

Decorator Pattern (Zero-Import Remote Execution)

from flow import FlowApp

app = FlowApp()

@app.function(gpu="a100", max_run_time_hours=1)
def train_model(dataset_path: str, epochs: int = 10):
    # Your training code here
    import torch
    print(f"Training on {torch.cuda.get_device_name(0)}")
    return {"accuracy": 0.95, "loss": 0.05}

# Run remotely
result = train_model.remote("./data/mnist", epochs=5)
print(result)

5. Instance Types

Type

GPUs

Memory

Use Case

a100

1x A100

80GB

Single GPU training, inference

4xa100

4x A100

320GB

Multi-GPU workloads

h100

8x H100

640GB

Large-scale distributed training

Check current pricing:

flow pricing

6. Essential Commands

Core Workflow

# Infrastructure management
flow compute create --instance-type a100 --command "nvidia-smi"
flow compute list
flow compute get <name>
flow compute delete <name>

# Task execution  
flow run --instance-type a100 --command "python train.py"
flow status
flow logs <task-id>

# Development
flow dev
flow ssh <task-id>

# Pricing & monitoring
flow pricing

Quick Reference

flow compute --help    # Instance management options
flow run --help        # Task execution options  
flow dev --help        # Development environment options
flow status            # List all tasks
flow pricing           # Current GPU rates

7. Working with Data

Basic File Upload

# Upload current directory to running task
flow upload-code <task-id>

# Run with persistent storage
flow run --instance-type a100 \
         --volume "size=100" \
         --command "python train.py"

SDK: Data Management

# Task with volume
config = TaskConfig(
    command="python train.py",
    instance_type="a100",
    volumes=[{"name": "training-data", "size_gb": 100}]
)
task = flow.run(config)

8. Cost Management

Set Price Limits

# CLI with price limit
flow run --max-price 5.00 --command "python train.py"

# Check current market rates
flow pricing

SDK: Cost Controls

config = TaskConfig(
    command="python train.py",
    instance_type="a100",
    max_price_per_hour=5.00,
    max_run_time_hours=2  # Safety timeout
)

9. Common Patterns

Distributed Training

# Multi-GPU training
flow run --instance-type 8xh100 \
         --command "torchrun --nproc_per_node=8 train.py"

SLURM Migration

# Run existing SLURM scripts unchanged
flow run job.slurm

Interactive Debugging

# Launch interactive session
flow dev
# Inside the session:
python train.py --debug

Flow gives you instant access to GPU clusters with simple commands. Start with flow dev for development, then use flow run for production workloads.

PreviousOverview NextMulti-node training

Last updated 15 days ago