lium.io is a Python package that provides both a command-line interface and a Python SDK for managing GPU pods on the Lium platform. Install it once — use whichever interface fits the job.
pip install lium.iocurl -fsSL https://lium.io/install.sh | bashFresh binary installs place a managed symlink at ~/.lium/bin/lium that points to a
versioned binary under ~/.lium/versions/<version>/lium.
# First-time setup
lium init
# List available nodes (GPU machines)
lium ls
# Create a pod using node index
lium up 1 # Use node #1 from previous ls
# Or create a pod using filters
lium up --gpu A100 # Auto-select best A100 node
# List your pods
lium ps
# Copy files to pod
lium scp 1 ./my_script.py
# SSH into a pod
lium ssh <pod-name>
# Stop a pod
lium rm <pod-name>The SDK mirrors the CLI's capabilities for programmatic use. Two entry points: the @lium.machine decorator for quickly offloading isolated functions, and the Lium() client for long-lived orchestration code.
High-level decorator — annotate a function and offload work to a GPU pod:
import lium
@lium.machine(machine="A100", requirements=["torch", "transformers", "accelerate"])
def infer(prompt: str) -> str:
from transformers import AutoTokenizer, AutoModelForCausalLM
tokenizer = AutoTokenizer.from_pretrained("sshleifer/tiny-gpt2")
model = AutoModelForCausalLM.from_pretrained("sshleifer/tiny-gpt2", device_map="cuda")
tokens = tokenizer(prompt, return_tensors="pt").to("cuda")
out = model.generate(**tokens, max_new_tokens=50)
return tokenizer.decode(out[0], skip_special_tokens=True)
print(infer("Who discovered penicillin?"))Direct SDK usage follows the same pattern:
from lium.sdk import Lium
lium = Lium()
node = lium.ls(gpu_type="A100")[0]
pod = lium.up(executor_id=node.id, name="demo")
ready = lium.wait_ready(pod, timeout=600)
print(lium.exec(ready, command="nvidia-smi")["stdout"])
lium.down(ready)Full API reference: https://docs.lium.io/developers/sdk/reference
- CLI docs: https://docs.lium.io/category/cli
- SDK docs: https://docs.lium.io/developers/sdk
- Supported binary targets:
darwin-amd64,darwin-arm64,linux-amd64,linux-arm64 - Maintainers can build locally with
bash scripts/build.sh [macos|linux|all] - Release artifacts publish through GitHub Releases with matching checksums
The lium CLI exposes the full pod lifecycle. Run lium --help to see everything, or browse the reference below.
lium init- Initialize configuration (API key, SSH keys)lium ls [GPU_TYPE]- List available nodeslium up [NODE_ID]- Create a pod (use node ID or filters like--gpu,--count,--country)lium ps- List active podslium describe <POD>- Full manifest of one pod: ports, GPU, template, billing (add--jsonfor machine-readable output)lium ssh <POD>- SSH into a podlium exec <POD> <COMMAND>- Execute command on podlium scp <POD> <LOCAL_FILE> [REMOTE_PATH]- Copy files to pods (add-dto download from pods)lium rsync <POD> <LOCAL_DIR> [REMOTE_PATH]- Sync directories to podslium rm <POD>- Remove/stop a podlium reboot <POD>- Reboot a podlium update <POD>- Install Jupyter on a podlium templates [SEARCH]- List available Docker templateslium fund- Fund account with TAO from Bittensor wallet
lium volumes list- List all volumeslium volumes new <NAME>- Create a new volumelium volumes rm <VOLUME>- Remove a volume
lium bk show <POD>- Show backup configuration for a podlium bk set <POD> <PATH>- Configure automatic backupslium bk logs <POD>- View backup logslium bk now <POD>- Trigger immediate backuplium bk restore <POD> <BACKUP_ID>- Restore from backuplium bk rm <POD>- Remove backup configuration
lium schedules list- List scheduled terminationslium schedules rm <POD>- Cancel scheduled termination
lium config show- Show all configurationlium config get <KEY>- Get configuration valuelium config set <KEY> <VALUE>- Set configuration valuelium config unset <KEY>- Remove configuration keylium config edit- Edit configuration filelium config path- Show configuration file pathlium config reset- Reset all configuration
lium provider … is the provider-side CLI for Bittensor Subnet 51 — full automation parity with the portal frontend at lium.io/portal: portal authentication, node lifecycle, central-miner-server configuration, batch sync, billing, and machine-request queries. Hotkey registration is still handled separately via btcli subnet register.
Group-level flags inherited by every subcommand: -w/--coldkey, -k/--hotkey, --portal-url, --json, --debug, -y/--yes, --dry-run. Persist wallet identity once with lium config set provider.coldkey <NAME> and lium config set provider.hotkey <NAME>. Spend-affecting subcommands run a persona prompt unless --yes or LIUM_PROVIDER_ACK=1 is set.
lium provider portal {login,logout,whoami}- Manage the cached portal JWTlium provider status [--netuid 51]- Aggregated provider snapshot (registration, portal session, nodes, validator weights)lium provider node list|get|add|rm|update-price|update-gpu- Node lifecycle on the portallium provider node min-gpu set|unset <NODE_ID> [COUNT]- Min GPU count for rental matchmakinglium provider node pods <NODE_ID>- Pods currently rented on a nodelium provider node machine-requests <NODE_ID>- Pending tenant requests on a nodelium provider node notice-period set|unset <NODE_ID>- Open/close a maintenance notice periodlium provider node notify-added <NODE_ID> --request-id <REQ>- Mark a tenant machine request fulfilledlium provider config show|opt-in|opt-out|set-email|set-subscriptions- Portal-account configuration (incl. lium.io central miner server toggle)lium provider sync from-miner-server|to-miner-server- Batch node-state sync between portal and the central miner serverlium provider billing list [--miner-hotkey HK] [--page N] [--limit N]- Paginated billing historylium provider machine-request list|get- Pending tenant machine requestslium provider machine list|estimate- Machine catalogue + reward estimates
Full reference with every flag and runnable examples: https://docs.lium.io/developers/cli/reference/provider.
lium theme [THEME]- Get or set UI theme (light/dark/auto)lium mine- Set up a compute subnet node/minersudo lium gpu-splitting setup [--device /dev/...] [--yes]- Prepare Docker storage for LIUM GPU splittinglium gpu-splitting check [--device /dev/...]- Inspect the host and print the GPU-splitting planlium gpu-splitting verify- Verify Docker storage matches LIUM GPU-splitting requirements
# Filter nodes by GPU type
lium ls H100
lium ls A100
# Create pod with node index
lium up 1 --name my-pod --yes
# Create pod with filters (auto-selects best node)
lium up --gpu A100 --count 8 --name my-pod --yes
lium up --gpu H200 --country US
# Create pod with specific template
lium up 1 --template_id <TEMPLATE_ID> --yes
# Set up node bootstrap flow
lium mine --auto --hotkey <HOTKEY>
# Provider-portal automation (same surface as the portal frontend)
lium config set provider.coldkey miner-prod # one-time: persist wallet identity
lium config set provider.hotkey miner-1
lium provider portal login # JWT exchange via hotkey signature
lium provider status # registration, portal session, nodes, weights
lium provider node list --limit 50
lium provider node add --gpu-type "NVIDIA H200 NVL" --gpu-count 8 \
--ip 203.0.113.42 --port 8080 --price 1.85 --yes
lium provider node update-price <NODE_ID> --price 2.10 --yes
lium provider config opt-in --yes # use lium.io's central miner server
lium provider machine estimate --gpu-type "NVIDIA H200 NVL" --gpu-count 8
lium provider --json status # JSON envelope for scripts/agents
# Inspect or configure Docker storage for GPU splitting (Ubuntu/Debian + systemd, run setup as root)
lium gpu-splitting check
sudo lium gpu-splitting setup --yes
lium gpu-splitting verify
# Create pod with volume
lium up 1 --volume id:<VOLUME_HUID>
lium up 1 --volume new:name=mydata,desc="My dataset"
# Create pod with auto-termination
lium up 1 --ttl 6h # Terminate after 6 hours
lium up 1 --until "today 23:00" # Terminate at 11 PM today
# Create pod with Jupyter
lium up 1 --jupyter --yes
# Execute commands
lium exec my-pod "nvidia-smi"
lium exec my-pod "python train.py"
# Copy files to and from pods
lium scp my-pod ./script.py # Copy to /root/script.py
lium scp 1 ./data.csv /root/data/ # Copy to specific directory
lium scp all ./config.json # Copy to all pods
lium scp 1,2,3 ./model.py /root/models/ # Copy to multiple pods
lium scp my-pod /root/output.log ./downloads -d # Download into ./downloads directory
# Reboot pods
lium reboot my-pod # Reboot a single pod
lium reboot 1,2 --yes # Reboot pods 1 and 2 without confirmation
lium reboot all # Reboot all active pods
lium reboot my-pod --volume-id <VOLUME_ID> # Reboot with a specific volume ID
# Sync directories to pods
lium rsync my-pod ./project # Sync to /root/project
lium rsync 1 ./data /root/datasets/ # Sync to specific directory
lium rsync all ./models # Sync to all pods
lium rsync 1,2,3 ./code /root/workspace/ # Sync to multiple pods
# Remove multiple pods
lium rm my-pod-1 my-pod-2
lium rm all # Remove all pods
# Install Jupyter on existing pod
lium update my-pod
# Manage volumes
lium volumes list
lium volumes new mydata --description "My dataset"
lium volumes rm <VOLUME_HUID>
# Manage backups
lium bk show my-pod
lium bk set my-pod /root/data --frequency 24 --retention 7
lium bk logs my-pod
lium bk now my-pod --name manual-backup
lium bk restore my-pod <BACKUP_ID> /root/restore
lium bk rm my-pod
# Manage schedules
lium schedules list
lium schedules rm my-pod
# Configuration management
lium config show
lium config get api.api_key
lium config set ssh.key_path /path/to/key
lium config edit
# Theme management
lium theme # Show current theme
lium theme dark # Set to dark theme
lium theme auto # Auto-detect based on system
# Fund account with TAO
lium fund # Interactive mode
lium fund -w default -a 1.5 # Fund with specific wallet and amount
lium fund -w mywal -a 0.5 -y # Skip confirmation- Dual Interface: Same package ships both the
liumCLI and a Python SDK (lium.sdk.Lium+@lium.machinedecorator) - Pareto Optimization:
lscommand shows optimal nodes with ★ indicator - Flexible Pod Creation: Use node index or auto-select with filters (GPU type, count, country)
- Index Selection: Use numbers from
lsoutput in commands - Full-Width Tables: Clean, readable terminal output
- Cost Tracking: See spending and hourly rates in
ps - Interactive Setup:
initcommand for easy onboarding - Volume Management: Create and attach persistent storage volumes
- Backup & Restore: Automated backups with configurable frequency and retention
- Auto-Termination: Schedule pods to terminate after duration or at specific time
- Jupyter Integration: One-command Jupyter installation on pods
- Theme Support: Light, dark, or auto-detect themes for better visibility
Configuration is stored in ~/.lium/config.ini:
[api]
api_key = your-api-key-here
[ssh]
key_path = /home/user/.ssh/id_ed25519You can also use environment variables:
export LIUM_API_KEY=your-api-key-here- Python 3.9+
# Clone repository
git clone https://github.com/datura-ai/lium.git
cd lium
# Install in development mode
pip install -e .MIT License - see LICENSE file for details.